从 PyPI 安装
本页面介绍了如何使用 发布在 PyPI 上的 apache-airflow 包进行安装。
通过 pipx 或 uv 作为工具进行安装
对于本地开发和测试环境，您可以直接从 PyPI 安装并运行 Apache Airflow。
如果您使用 pipx，可以通过以下命令直接从 PyPI 运行：
pipx run "apache-airflow==3.2.0" standalone
通过 Astral uv，可以使用以下方式从 PyPI 安装：
uv tool install "apache-airflow==3.2.0"
此外，为了快速启动，您还可以通过 uvx 命令直接运行，而无需先进行安装：
uvx apache-airflow standalone
在您的环境中安装
目前仅官方支持使用 pip 和 uv 进行安装。
注意
虽然使用 poetry 或 pip-tools 等其他工具取得了一些成功，但它们与 pip 的工作流不尽相同——尤其是在约束（constraints）与需求（requirements）管理方面。目前不支持通过 Poetry 或 pip-tools 进行安装。如果您希望使用这些工具安装 Airflow，则应使用约束文件，并将它们转换为您的工具所要求的适当格式和工作流。Uv 遵循与 pip install 类似的方法，因此效果应该相似。
从头开始以可重现的方式从 PyPI 安装 Airflow 的典型命令如下：
pip install "apache-airflow[celery]==3.2.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.2.0/constraints-3.10.txt"
通常，您可以在可重现的安装之后，通过单独的命令添加其他依赖项和提供程序——这样您就可以根据需要升级或降级依赖项，而不会受到约束文件的限制。对于这些操作，一个好的做法是在 pip install 命令中加入锁定到您已安装版本的 apache-airflow，以确保它不会被 pip 意外升级或降级。
pip install "apache-airflow==3.2.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 3.1 起，约束文件不再包含仅用于测试的开发依赖项，如 pytest、moto 等。
可重现的 Airflow 安装
为了实现可重现的安装，我们在 constraints-main、constraints-2-0、constraints-2-1 等孤立分支中维护了一组约束文件，并为每个发布的版本创建标签，例如 constraints-3.2.0。
通过这种方式，我们在发布时保持了一组经过测试的依赖项。这使您能够拥有与发布时已知可用的完全相同的 Airflow + 提供程序 + 依赖项的安装——即该版本 Airflow 的冻结依赖项集合。Airflow 支持的每个 Python 版本都有一个单独的约束文件。
您可以通过替换下述模板中的变量来构建文件 URL。
https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt
其中
AIRFLOW_VERSION- Airflow 版本（例如3.2.0）或main、2-0（用于最新的开发版本）PYTHON_VERSION- Python 版本，例如3.10,3.11
以下示例假设您希望使用 celery extra 以可重现的方式安装 Airflow，但您可以根据需要选择自己的 extras 和提供程序进行安装。
pip install "apache-airflow[celery]==3.2.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.2.0/constraints-3.10.txt"
注意
可重现的安装保证了这些初始安装步骤始终为您工作——前提是您使用了正确的 Python 版本，并为要安装的提供程序安装了适当的操作系统依赖项。某些提供程序需要安装额外的操作系统依赖项，例如编译库所需的 build-essential，或者如果您安装数据库提供程序时所需的数据库客户端库等。当您的安装失败时，您需要找出所需的系统依赖项，并在重试安装之前安装它们。
升级和安装依赖项（包括提供程序）
上述可重现的安装方法不会阻止您将提供程序和其他依赖项升级或降级到其他版本。
例如，您可以在发布后安装新版本的提供程序和依赖项，以使用最新版本并保持最新的安全修复——即使您不想升级 Airflow 核心版本。或者，如果您出于兼容性原因想保留以前的版本，也可以降级某些依赖项或提供程序。安装此类依赖项应作为单独的 pip 命令，且无需使用约束。
进行此类升级时，您应确保将 apache-airflow 包也添加到要安装的包列表中，并将其锁定到您当前的版本，否则您最终得到的 Airflow 版本可能会与您预期的不同，因为 pip 在执行依赖项解析时可能会自动升级或降级它。
pip install "apache-airflow[celery]==3.2.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.2.0/constraints-3.10.txt"
pip install "apache-airflow==3.2.0" apache-airflow-providers-google==10.1.1
您也可以通过这种方式降级或升级其他依赖项——即使它们与原始约束文件中存储的那些依赖项不兼容。
pip install "apache-airflow[celery]==3.2.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.2.0/constraints-3.10.txt"
pip install "apache-airflow[celery]==3.2.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.2.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.2.0/constraints-3.10.txt"
pip install "apache-airflow==3.2.0" dbt-core==0.20.0
pip freeze > my-constraints.txt
然后，您可以使用它通过本地约束文件在单次操作中创建环境的可重现安装。
pip install "apache-airflow[celery]==3.2.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.2.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.2.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 核心管理提供程序
为了添加新功能、实现错误修复或仅仅是维护向后兼容性，您可能需要安装、升级或降级任何提供程序——与 Airflow 核心包分开操作。我们独立于 Airflow 核心发布提供程序，因此通常提供程序的新版本会在 Airflow 之前发布，而且如果您还不打算将 Airflow 升级到最新版本，您可能只想单独安装一些（或全部）新发布的提供程序。
如上所述，在单独安装提供程序时，您不应使用任何约束文件。
如果您自动构建环境，则应在安装 Airflow 后（通常使用约束）将提供程序的安装作为单独的命令运行。约束仅在执行 pip install 命令时才有效。
最佳做法是安装与原始镜像中提供的版本相同的 apache-airflow。这样您可以确信 pip 不会在安装其他需求时尝试降级或升级 Apache Airflow，如果您尝试添加与您正在使用的 apache-airflow 版本冲突的依赖项，这种情况可能会发生。
pip install "apache-airflow==3.2.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 核心
如果您不想安装任何提供程序，只想安装或升级 Apache Airflow，您可以简单地安装您需要的 Airflow 版本。您可以使用特殊的 constraints-no-providers 约束文件，它更小，并将依赖项仅限于 Airflow 核心，但是如果您所在的系统中已经安装了某些依赖项的不同版本，或者安装了其他提供程序，这可能会导致冲突。不过，此命令为您提供了在 Airflow 发布时与仅 Airflow 核心兼容的最新版本依赖项。
AIRFLOW_VERSION=3.2.0
PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
# For example: 3.10
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.2.0/constraints-no-providers-3.10.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.10：/usr/local/opt/python@3.10/Frameworks/Python.framework/Versions/3.10）。
问题的核心是 Airflow 依赖的库 setproctitle 使用了一个非公开的 Python API，而标准安装 /usr/local/opt/（链接到 /usr/local/Cellar 下的路径）中不提供该 API。
一个简单的解决方法是确保使用一个具有可用 Python 库 dylib 的 Python 版本。例如：
# Note: these instructions are for python3.10 but can be loosely modified for other versions
brew install python@3.10
virtualenv -p /usr/local/opt/python@3.10/Frameworks/Python.framework/Versions/3.10/bin/python3 .toy-venv
source .toy-venv/bin/activate
pip install apache-airflow
python
>>> import setproctitle
# Success!
或者，您可以直接从 Python 网站 下载并安装 Python。