Installation and Constraints

Purpose and Scope

This page explains how to think about installing Apache Airflow and managing dependency constraints when working from this repository. Airflow is distributed as a Python package, is published with PyPI metadata, and is also commonly consumed through containers and deployment packaging. The top-level repository readme makes those distribution channels visible through project badges for PyPI, Python versions, Docker pulls, Docker stars, and Artifact Hub. For a new installer, those signals matter because they point to the supported ways people usually obtain Airflow rather than a single repository-only path. Sources: README.md

Airflow installation is not just a package download decision. A working environment combines the Airflow distribution, Python compatibility, provider packages, optional extras, a metadata database, and deployment-specific services. The official installation documentation organizes those choices around prerequisites, dependencies, supported versions, installing from sources, installing from PyPI, database setup, production Docker images, the official Helm chart, managed services, and third-party deployments. In this repository page, the key source-backed addition is the constraints workflow used by developers when dependency resolution needs to be controlled or iterated locally. Sources: README.md, constraints/README.md

Relevant Source Files

README.md — Provides the repository-level Apache Airflow entry point and distribution signals, including PyPI, supported Python version metadata, container availability, and community-facing project identity.
constraints/README.md — Documents the development-only workflow for storing local constraint files, passing them into Breeze image builds, regenerating constraints from an installed environment, and sharing temporary constraints with collaborators.

Installation Entry Points

For most users, the official documentation separates installation from local source development. Installing from PyPI is the natural path when a user wants a Python environment containing an Airflow release and its selected dependencies. Container-based installation is the natural path when a user wants an image-oriented runtime, and Helm or managed services are deployment entry points for Kubernetes or hosted environments. The repository readme does not prescribe a full command sequence in the provided excerpt, but it does expose the same ecosystem through PyPI and container badges, which is a useful first confirmation that Airflow is published for both package-manager and image-based consumption. Sources: README.md

The practical decision is to choose the installation path that matches the operator model. A local learner may start with a quick-start environment, then move to PyPI or Docker once they need repeatability. A platform team may evaluate the production Docker image or Helm chart because those paths model deployment as an artifact and configuration problem. A contributor or dependency maintainer may instead install from sources or build images through the development tooling, because they need to test unreleased code or dependency changes. These entry points are complementary; they differ mainly in who owns dependency resolution and runtime packaging. Sources: README.md, constraints/README.md

Constraints and Dependency Resolution

A constraints file is a pinned list of dependency versions used to make Python dependency resolution predictable. The constraints readme is explicitly scoped to development use only, and it describes the problem it solves: when working on a related set of packages or dependencies, repeated pip backtracking can make image rebuilds slow, and conflicting dependency solutions can force repeated rebuild attempts. Storing a local constraints file gives a developer a stable input to the image build so they can iterate on dependency changes without continuously asking the tooling to upgrade dependencies from scratch. Sources: constraints/README.md

The documented workflow starts by downloading a constraints file, copying it into the constraints folder, and modifying it locally. The example references a raw constraints file for a Python version and then passes that local file into a Breeze continuous-integration image build. The important contract is the build option that points Breeze at the developer-controlled constraints file. That option lets the image build use the chosen dependency set while the developer edits, rebuilds, and tests the result. The readme also notes that collaborators can temporarily commit the file on a branch or fork, but it should be removed before merge to the main branch. Sources: constraints/README.md

breeze ci-image build --python 3.10 --airflow-constraints-location constraints/constraints-3.10.txt

Extras, Providers, and Version Compatibility

Package extras are optional dependency groups that make an Airflow installation include additional integrations or capabilities. The official reference groups extras for the Airflow distribution, core Airflow, meta-airflow packages, providers, Apache Software integrations, external services, locally installed software, and other grouped capabilities. In practice, extras are one way users express integration intent at installation time, while provider packages are the long-term extension surface for service-specific operators, hooks, triggers, auth managers, connection types, and other integrations. This repository page does not enumerate every extra, but it places extras beside constraints because both influence the resolved dependency graph. Sources: README.md, constraints/README.md

Version compatibility should be treated as a three-part decision: the Airflow release, the Python runtime, and the dependency set selected by the resolver or constraints file. The readme’s PyPI badge includes Python version metadata, which is a repository-level pointer that Python compatibility is part of the published package contract. The constraints workflow also encodes Python version awareness through filename and command examples that use a Python-specific constraints file. When dependency maintainers test a new version, they should keep the Airflow release line, Python version, and pinned dependency set aligned rather than treating constraints as a generic requirements snapshot. Sources: README.md, constraints/README.md

Regenerating Local Constraints

After a developer has manually added or updated dependencies and is satisfied with the installed environment, the constraints readme shows how to regenerate a constraints file from the current environment. The pipeline sorts installed packages, removes Airflow package entries, removes direct references and local installation paths, and writes the remaining pins into the Python-version-specific constraints file. This is useful because the local environment becomes the source of truth for the next image build iteration, while the filters avoid pinning the Airflow source checkout itself as though it were an external dependency. Sources: constraints/README.md

pip freeze | sort | \
    grep -v "apache_airflow" | \
    grep -v "apache-airflow==" | \
    grep -v "@" | \
    grep -v "/opt/airflow" > /opt/airflow/constraints/constraints-3.10.txt

This regeneration step is especially helpful when several dependency updates must be evaluated together. Instead of repeatedly solving the full dependency graph from an unconstrained starting point, a contributor can converge on a known set of versions, freeze that set, rebuild with the same constraint file, and share the temporary file with other people testing the same branch. The readme’s warning about removing the file before merge is important operational hygiene: local development constraints are a collaboration aid, not a permanent replacement for the project’s release-managed constraints process. Sources: constraints/README.md

Practical Workflow

A safe installation planning flow starts by deciding the runtime shape: PyPI environment, source checkout, production image, Helm deployment, managed service, or third-party packaging. Next, identify which optional capabilities are needed, such as provider integrations or extras. Then choose the Python version supported by the target Airflow release. Only after those decisions should dependency pins be adjusted. If the work is ordinary installation, follow the official installation and extra package references. If the work is dependency maintenance or image iteration, use the local constraints process described in this repository. Sources: README.md, constraints/README.md

When troubleshooting installation failures, distinguish resolver problems from runtime configuration problems. Resolver problems usually appear while packages are being selected or built, and they are the situations where a constraints file can reduce backtracking and preserve a known dependency solution. Runtime configuration problems appear after Airflow is installed, for example during database setup or service startup, and should be handled through the installation, configuration, deployment, or troubleshooting documentation rather than by repeatedly changing constraints. Keeping that boundary clear prevents constraint files from becoming an all-purpose workaround for unrelated setup issues. Sources: constraints/README.md

After this page, read the Docker Compose quick start if the immediate goal is a local runnable environment, or the production deployment and Kubernetes and Helm pages if the goal is an operational installation. Read the providers overview and operators reference before selecting extras for external systems, because provider packages define much of the integration surface. For repository contributors changing dependencies, keep the constraints readme close at hand, use the Breeze build option shown above, regenerate pins from a tested environment, and remove temporary local constraints before merging shared work. Sources: README.md, constraints/README.md

Ask a question...