act-runner-el/docs/python.md

Python configuration

This document details the Python setup in our ACT runner images, including installed tools, environment variables, and configuration decisions.

What's included

Python installations

Images include Ubuntu's native Python version, with optionally additional versions from the deadsnakes PPA in separate image variants. The native Python version varies by Ubuntu release and includes python3-apt for system package compatibility.

Each Python installation includes:

• python{version} - The Python interpreter
• python{version}-venv - Virtual environment support
• python3-apt - APT Python bindings (only with native Python versions)

Modern Python versions (3.12+) don't include python-distutils as it was deprecated in 3.10 and removed entirely. Legacy code requiring distutils may need to install it separately.

See the main README for current available versions.

Pre-installed development tools

All Python images include these development tools pre-installed via uv:

• prek - Pre-commit hook runner
• ruff - Fast Python linter and formatter
• mypy - Static type checker
• pytest - Testing framework
• black - Code formatter
• isort - Import sorter

Environment configuration

The following environment variables are pre-configured:

Variable	Value	Purpose
UV_LINK_MODE	copy	Reduces verbosity in CI logs
PATH	/root/.local/bin:$PATH	Includes uv and installed tools

The PATH modification ensures uv itself is available, makes tools installed via uv tool install accessible, and prevents warnings about PATH during tool installation.

Working with Python

Managing tools

You can manage all Python tools via uv:

# Update a tool
uv tool update ruff

# Install additional tools
uv tool install poetry
uv tool install pipenv

# Remove a tool
uv tool remove black

# List installed tools
uv tool list

Virtual environments

Virtual environment support works as expected:

# Create a virtual environment
python -m venv .venv

# Or use uv for faster venv creation
uv venv

# Activate it
source .venv/bin/activate

Design decisions

Why uv?

We use uv as our Python package installer because it:

• Is 10-100x faster than pip
• Provides consistent tool management via uv tool
• Reduces CI build times significantly
• Is maintained by the Ruff team (Astral)

Why these specific tools?

The pre-installed tools cover common Python development needs:

• Linting & Formatting: ruff, black, isort
• Type Checking: mypy
• Testing: pytest
• Pre-commit: prek

This gives you a complete Python development environment whilst keeping the image size reasonable.

Why no distutils?

Python's distutils was deprecated in Python 3.10 and removed entirely in Python 3.12. Most modern Python packages have migrated to setuptools or other build systems. We don't include it to:

• Keep images smaller
• Encourage modern packaging practices
• Avoid confusion with deprecated APIs

Why deadsnakes PPA?

The deadsnakes PPA provides:

• Newer Python versions on older Ubuntu releases
• Consistent Python packaging across Ubuntu versions
• Regular security updates
• Minimal overhead (only adds package repository)

Troubleshooting

Module not found

If you encounter import errors for standard library modules:

# Ensure you're using the right Python
which python
python --version

# For virtual environments, check activation
echo $VIRTUAL_ENV

Tool not in PATH

All tools should be in PATH, but if not:

# Check tool installation
uv tool list

# Manually add to PATH if needed
export PATH="/root/.local/bin:$PATH"

Need a different Python version?

If you need a Python version not included in our images, use the actions/setup-python action in your workflow. It supports all Python versions and includes built-in caching.