Airflow Summit 2025 将于 10 月 07-09 日举行。立即注册获取早鸟票！

从 PyPI 安装

本页面介绍如何使用 apache-airflow 包进行安装，该包 发布在 PyPI 上。

安装工具

目前官方只支持 pip 安装。

注意

尽管使用其他工具如 poetry 或 pip-tools 取得了一些成功，但它们的流程与 pip 不同——尤其是在处理约束文件与 requirements 文件方面。目前不正式支持通过 Poetry 或 pip-tools 进行安装。如果您希望使用这些工具安装 Airflow，您应该使用约束文件并将其转换为您所用工具所需的相应格式和流程。

从 PyPI 从头开始以可复现的方式安装 Airflow 的典型命令如下所示：

pip install "apache-airflow[celery]==3.0.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.0.0/constraints-3.9.txt"

通常，您可以在可复现安装之后将其他依赖项和提供者作为单独的命令添加——这样您可以根据需要升级或降级依赖项，而无需受约束文件限制。一个好的实践是，在执行这样的 pip install 命令时，将 apache-airflow 锁定到您已安装的版本，以确保它不会被 pip 意外升级或降级。

pip install "apache-airflow==3.0.0" apache-airflow-providers-google==10.1.0

这些只是示例，更多解释说明为什么这些是最佳实践，请继续阅读。

注意

总的来说，Python 社区的惯例是在使用 virtualenv 或 venv 工具创建的虚拟环境中执行应用程序安装。您也可以使用 uv 或 pipx 将 Airflow 安装在专门为您创建的应用程序专用虚拟环境中。还有其他工具可用于管理您的虚拟环境安装，您可以自由选择管理环境的方式。对于虚拟环境工具的选择，Airflow 没有限制。

唯一的例外是当您构建一个仅安装了 Airflow 的容器镜像时，您可能可以考虑不使用虚拟环境——例如，官方容器镜像就是这样安装 Airflow 的。

约束文件

为什么需要约束文件

Airflow® 的安装可能有些棘手，因为 Airflow 既是库又是应用程序。

库通常保持其依赖项开放，而应用程序通常会固定它们，但我们既不应该这样做，又应该同时做到。我们决定尽可能地开放依赖项（在 pyproject.toml 中），以便用户可以根据需要安装不同版本的库。这意味着有时简单的 pip install apache-airflow 可能无法工作或会导致安装的 Airflow 无法使用。

可复现的 Airflow 安装

为了实现可复现的安装，我们还在 constraints-main、constraints-2-0、constraints-2-1 等孤立分支中维护了一组约束文件，然后为每个发布的版本创建了一个标签，例如 constraints-3.0.0。

通过这种方式，我们在发布时保存了一组经过测试的依赖项。这使得您能够获得与发布时已知工作的 Airflow + 提供者 + 依赖项完全相同的安装——即该版本 Airflow 的固定依赖项集。Airflow 支持的每个 Python 版本都有一个单独的约束文件。

您可以通过替换以下模板中的变量来创建文件的 URL。

https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt

其中

  • AIRFLOW_VERSION - Airflow 版本（例如 3.0.0），或 main、2-0 表示最新的开发版本

  • PYTHON_VERSION Python 版本，例如 3.9、3.10

以下示例假设您希望以可复现的方式安装带有 celery extra 的 Airflow，但您可以选择自己的 extra 和提供者集进行安装。

pip install "apache-airflow[celery]==3.0.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.0.0/constraints-3.9.txt"

注意

可复现安装保证了初始安装步骤对您始终有效——前提是您使用了正确的 Python 版本，并且为要安装的提供者安装了相应的操作系统依赖项。一些提供者需要安装额外的操作系统依赖项，例如用于编译库的 build-essential，或者例如在安装数据库提供者时需要数据库客户端库等。您需要在安装失败时找出您需要的系统依赖项，并在重试安装之前安装它们。

升级和安装依赖项（包括提供者）

上述的可复现安装不应阻止您将提供者和其他依赖项升级或降级到其他版本

例如，您可以在发布后安装新版本的提供者和依赖项，以使用最新版本并及时获取最新的安全修复——即使您不想升级 Airflow core 版本。或者，出于兼容性原因，您可以降级一些依赖项或提供者以保留旧版本。此类依赖项的安装应在不使用约束文件的情况下作为单独的 pip 命令进行。

在进行此类升级时，您应该确保也将 apache-airflow 包添加到安装列表中，并将其固定到您现有的版本，否则您最终可能会得到与预期不同的 Airflow 版本，因为 pip 在执行依赖项解析时会自动升级/降级它。

pip install "apache-airflow[celery]==3.0.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.0.0/constraints-3.9.txt"
pip install "apache-airflow==3.0.0" apache-airflow-providers-google==10.1.1

您也可以通过这种方式降级或升级其他依赖项——即使它们与原始约束文件中存储的依赖项不兼容。

pip install "apache-airflow[celery]==3.0.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.0.0/constraints-3.9.txt"
pip install "apache-airflow[celery]==3.0.0" dbt-core==0.20.0

警告

并非所有依赖项都可以通过这种方式安装——您的依赖项可能与 Airflow 的基本要求或系统中安装的其他依赖项发生冲突。然而，通过在安装或升级依赖项时跳过约束文件，您给了 pip 机会为您解决冲突，同时将依赖项保持在 Apache Airflow、提供者和其他依赖项要求的范围内。由此产生的依赖项组合和约束文件附带的依赖项集可能之前未经过测试，但在大多数情况下应该可以工作，因为我们通常会在 Airflow 依赖于某些特定版本的依赖项时添加要求。在您无法在与 Airflow 同一环境安装某些依赖项的情况下，您可以尝试使用其他方法。请参阅 处理冲突/复杂 Python 依赖项的最佳实践

验证已安装的依赖项

您也可以随时运行 pip check 命令来测试您的 Python 包集是否一致且没有冲突。

> pip check
No broken requirements found.

当您看到此类消息且 pip check 的退出代码为 0 时，您可以确定您的环境中没有冲突的依赖项。

使用您自己的约束文件

当您决定安装自己的依赖项，或希望升级或降级提供者时，您可能希望继续通过一个命令保持 Airflow 和这些依赖项的可复现安装。为了做到这一点，您可以生成自己的约束文件，并使用它来安装 Airflow，而不是使用社区提供的约束文件。

pip install "apache-airflow[celery]==3.0.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.0.0/constraints-3.9.txt"
pip install "apache-airflow==3.0.0" dbt-core==0.20.0
pip freeze > my-constraints.txt

然后您可以使用它通过本地约束文件在一次操作中创建您的环境的可复现安装

pip install "apache-airflow[celery]==3.0.0" --constraint "my-constraints.txt"

与 Airflow 原始约束文件的情况类似，您也可以将您的约束文件托管在您自己的仓库或服务器上，并从那里远程使用它。

在发布时修复约束

已发布的“版本化”约束文件在我们发布 Airflow 版本时基本上是 固定 的，我们只在特殊情况下更新它们。例如，当我们发现已发布的约束文件可能妨碍从头开始一致地安装 Airflow 时。

在正常情况下，即使新的 Airflow 依赖项版本发布——甚至包含关键安全修复——约束文件也不会改变。Airflow 的发布过程设计为在适用的情况下自动升级依赖项，但这仅在发布新版本的 Airflow 时进行，而不是针对已发布的版本。

在发布之间，您可以自行升级依赖项，并按照上一节的描述更新您自己的约束文件。

跟随后最新发布的依赖项的最简单方法是升级到最新发布的 Airflow 版本。每当我们发布新版本的 Airflow 时，我们都会将所有依赖项升级到最新的适用版本并对其进行测试，因此如果您想跟上这些测试，升级到最新版本的 Airflow 是更新这些依赖项的最简单方法。

安装和升级场景

为了简化安装，我们准备了如何升级 Airflow 和提供者的示例。

安装带有 extras 和提供者的 Airflow®

如果您需要安装 Airflow® 的额外依赖项，您可以使用以下脚本将其简化为一行命令（以下示例安装了 Postgres 和 Google 提供者，以及 async extra）。

AIRFLOW_VERSION=3.0.0
PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"
pip install "apache-airflow[async,postgres,google]==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"

请注意，这将安装该版本 Airflow 发布时可用的提供者版本。如果您希望升级在发布后更新的提供者，则需要运行不带约束文件的单独 pip 命令。

将 Airflow 与提供者一起升级

您可以将 Airflow 与 extras（安装的 Airflow 版本发布时可用的提供者）一起升级。这将把 apache-airflow 和所有提供者升级到您正在安装的 Airflow 版本发布时已发布并经过测试的版本。

AIRFLOW_VERSION=3.0.0
PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"
pip install "apache-airflow[postgres,google]==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"

将提供者与 Airflow Core 分开管理

为了添加新功能、实现错误修复或仅维护向后兼容性，您可能需要安装、升级或降级任何提供者——与 Airflow Core 包分开。我们独立于 Airflow core 发布提供者，因此提供者的新版本通常在 Airflow 发布之前就已发布，此外，如果您还不想将 Airflow 升级到最新版本，您可能希望仅单独安装一些（或所有）新发布的提供者。

如您之前所见，在单独安装提供者时，您不应使用任何约束文件。

如果您自动构建环境，您应该在安装 Airflow（通常使用约束文件）后作为单独的命令运行提供者安装。约束文件仅在使用它们的 pip install 命令期间有效。

最佳实践是安装与原始镜像版本相同的 apache-airflow 版本。这样可以确保 pip 在安装其他 requirements 时不会尝试降级或升级 apache Airflow，否则可能会在您尝试添加与正在使用的 apache-airflow 版本冲突的依赖项时发生。

pip install "apache-airflow==3.0.0" "apache-airflow-providers-google==8.0.0"

注意

单独安装、升级、降级提供者不能保证与所有 Airflow 版本或其他提供者兼容。某些提供者对 Airflow 有最低版本要求，并且某些提供者版本可能对依赖项有限制，而这些限制与其他提供者或系统中安装的其他依赖项的限制冲突。例如，10.1.0 版本之前的 google 提供者对 protobuf 库的限制为 <=3.20.0，而例如 google 支持的 google-ads 库要求 protobuf 库版本 >=4。在这种情况下，将这两个依赖项同时安装在同一环境中将无法工作。在这种情况下，您可以尝试使用其他方法。请参阅 处理冲突/复杂 Python 依赖项的最佳实践

仅管理 Airflow Core 而不管理提供者

如果您不想安装任何提供者，只想安装或升级 Apache Airflow，您可以直接安装您需要的版本的 Airflow。您可以使用特殊的 constraints-no-providers 约束文件，该文件更小，并且仅限制对 Airflow core 的依赖项，但这可能导致冲突，如果您的环境已经安装了不同版本的某些依赖项，并且安装了其他提供者。然而，此命令为您提供了 Airflow 发布时与 Airflow core 兼容的最新版本的依赖项。

AIRFLOW_VERSION=3.0.0
PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
# For example: 3.9
CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-no-providers-${PYTHON_VERSION}.txt"
# For example: https://raw.githubusercontent.com/apache/airflow/constraints-3.0.0/constraints-no-providers-3.9.txt
pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"

故障排除

本节介绍如何解决 PyPI 安装问题。

'airflow' 命令无法识别

如果 airflow 命令无法识别（在使用 WSL 的 Windows 上可能发生），请确保 ~/.local/bin 在您的 PATH 环境变量中，并在必要时添加它。

PATH=$PATH:~/.local/bin

您也可以使用 python -m airflow 启动 Airflow。

找不到符号: _Py_GetArgcArgv

如果在启动或导入 airflow 时看到 Symbol not found: _Py_GetArgcArgv，这可能意味着您正在使用不兼容的 Python 版本。对于通过 homebrew 安装的 Python 版本，这通常是由于使用了 /usr/local/opt/bin 中的 Python，而不是 Frameworks 安装（例如，对于 python 3.9：/usr/local/opt/python@3.9/Frameworks/Python.framework/Versions/3.9）。

问题的关键在于 Airflow 依赖的一个库 setproctitle 使用了非公开的 Python API，该 API 在标准安装路径 /usr/local/opt/ 中不可用（该路径符号链接到 /usr/local/Cellar 下的一个路径）。

一个简单的修复方法是确保您使用的 Python 版本具有可用的 Python 库的 dylib 文件。例如：

# Note: these instructions are for python3.9 but can be loosely modified for other versions
brew install python@3.9
virtualenv -p /usr/local/opt/python@3.9/Frameworks/Python.framework/Versions/3.9/bin/python3 .toy-venv
source .toy-venv/bin/activate
pip install apache-airflow
python
>>> import setproctitle
# Success!

或者，您可以直接从 Python 网站下载并安装 Python。

此条目有帮助吗？