Environment:Apache Airflow Development Contributor Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Development |
| Last Updated | 2026-02-08 20:00 GMT |
Overview
Local development environment requiring Python 3.10-3.13, Docker CE with buildx/compose, uv package manager, and system libraries for PostgreSQL, MySQL, and Kerberos.
Description
This environment defines the prerequisites for contributing to the Apache Airflow project. Contributors can choose between two development approaches: (1) the Breeze containerized environment (recommended) using Docker, or (2) a local virtualenv setup. Both approaches require Python 3.10 or higher, Docker with buildx and Docker Compose support, and various system libraries. The uv package manager is recommended for managing Python versions and virtual environments. The Go SDK component requires Go 1.24.0+.
Usage
Use this environment when developing, testing, or contributing to Apache Airflow. This includes running unit tests, integration tests, Helm chart tests, building documentation, and running the Breeze development tool.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux (Ubuntu/Debian recommended) or macOS | Windows via WSL2 |
| Python | 3.10, 3.11, 3.12, or 3.13 | 3.11.9 recommended for local dev |
| Docker | Docker CE with buildx | Colima also supported on macOS |
| Docker Compose | v2+ | Required for Breeze environment |
| Go | >= 1.24.0 | Only for Go SDK development; toolchain 1.24.6 |
| Helm | 3.19.0 | Only for Helm chart tests |
Dependencies
System Packages (Ubuntu/Debian)
- `openssl`
- `sqlite3`
- `default-libmysqlclient-dev`, `libmysqlclient-dev`
- `postgresql`
- `build-essential`
- `libkrb5-dev` (Kerberos)
- `libldap2-dev` (LDAP)
- `libsasl2-dev` (SASL)
- `libssl-dev`
Development Tools
- `uv` >= 0.6.3 (Python package manager, recommended)
- `pip` >= 26.0.1 (alternative package manager)
- `prek` = 0.3.2 (pre-commit alternative)
- `helm` >= 3.19.0 (for chart tests)
Credentials
- `GITHUB_TOKEN`: For GitHub API operations during release tooling
- No credentials required for basic development and testing
Quick Install
# Install system dependencies (Ubuntu/Debian)
sudo apt install openssl sqlite3 default-libmysqlclient-dev \
libmysqlclient-dev postgresql build-essential
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install Python via uv
uv python install 3.11
# Clone and set up Airflow
git clone https://github.com/apache/airflow.git
cd airflow
# Install in development mode
uv sync --all-extras
# Or use Breeze (containerized development)
uv tool install apache-airflow-breeze
breeze
Code Evidence
Python version support from `contributing-docs/07_local_virtualenv.rst:37-40`:
* Python (One of: 3.10, 3.11, 3.12, 3.13)
* MySQL 5.7+
* libxml
* helm (only for helm chart tests)
Contributor prerequisites from `contributing-docs/03_contributors_quick_start.rst:53-56`:
1. UV is recommended for managing Python versions and virtual environments
2. Docker Community Edition (you can also use Colima or others)
3. Docker buildx
4. Docker Compose
Go SDK requirement from `go-sdk/go.mod:3-5`:
go 1.24.0
toolchain go1.24.6
uv minimum version from `airflow-core/pyproject.toml:306`:
required-version = ">=0.6.3"
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Docker daemon not running` | Docker not started | Start Docker service or install Docker CE |
| `uv: command not found` | uv not installed | sh` |
| `mysqlclient build failed` | Missing MySQL dev headers | `sudo apt install default-libmysqlclient-dev` |
| `No module named 'kerberos'` | Missing Kerberos dev headers | `sudo apt install libkrb5-dev` |
Compatibility Notes
- macOS: Use Colima as a Docker alternative. The `graphviz` extra is not supported.
- Windows: Only supported via WSL2 with Docker Desktop.
- Breeze: The containerized development environment handles most dependency installation automatically.
- Go SDK: Requires Go 1.24.0+ only when developing or testing the Go Task SDK.