从 PyPI 安装¶
此页面描述了使用 apache-airflow 包 在 PyPI 中发布 进行的安装。
安装工具¶
目前仅官方支持 pip 安装。
注意
虽然使用诸如 poetry 或 pip-tools 之类的其他工具取得了一些成功，但它们与 pip 不共享相同的工作流程，尤其是在约束与需求管理方面。目前不支持通过 Poetry 或 pip-tools 进行安装。如果您希望使用这些工具安装 airflow，则应使用约束并将其转换为您的工具所需的适当格式和工作流程。
已知 bazel 存在一些问题，当使用它来安装 Airflow 时可能会导致循环依赖。如果遇到此类问题，请切换到 pip。Bazel 社区正在 此 PR 中修复该问题，因此较新版本的 bazel 可能会处理它。
从 PyPI 以可复现的方式从头开始安装 airflow 的典型命令如下所示
pip install "apache-airflow[celery]==2.10.4" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.4/constraints-3.8.txt"
通常，您可以在可复现安装后添加其他依赖项和 providers 作为单独的命令 - 这样，您可以根据自己的需要升级或降级依赖项，而不会将其限制为约束。对于这些依赖项和 providers 的良好做法是使用 apache-airflow 将 pip install 命令扩展到您已安装的版本，以确保它不会被 pip 意外升级或降级。
pip install "apache-airflow==2.10.4" apache-airflow-providers-google==10.1.0
这些只是示例，请进一步了解为什么这些是最佳实践。
注意
一般来说，Python 社区建立的实践是在使用 virtualenv 或 venv 工具创建的 virtualenv 中执行应用程序安装。您也可以使用 pipx 在为您创建的应用程序专用虚拟环境中安装 Airflow®。还有其他工具可用于管理您的 virtualenv 安装，您可以自由选择如何管理环境。当涉及到虚拟环境时，Airflow 对您选择的工具没有任何限制。
您可能考虑不使用 virtualenv 的唯一例外是当您构建仅安装了 Airflow 的容器镜像时 - 例如，这就是 Airflow 在官方容器镜像中的安装方式。
约束文件¶
为什么我们需要约束¶
Airflow® 安装可能很棘手，因为 Airflow 既是库又是应用程序。
库通常保持其依赖项开放，而应用程序通常会固定它们，但我们应该同时做到这两者。我们决定尽可能保持依赖项的开放（在 pyproject.toml 中），以便用户可以在需要时安装不同版本的库。这意味着有时简单的 pip install apache-airflow 将不起作用或将产生无法使用的 Airflow 安装。
可复现的 Airflow 安装¶
为了实现可复现的安装，我们还在 constraints-main、constraints-2-0、constraints-2-1 等孤立分支中保留一组约束文件，然后为每个发布的版本创建一个标签，例如 constraints-2.10.4。
这样，我们在发布时保留了一组经过测试的依赖项。这使您能够拥有与发布时已知可工作的完全相同的 airflow + providers + 依赖项安装 - 针对该版本的 Airflow 的冻结依赖项集。Airflow 支持的每个 Python 版本都有一个单独的约束文件。
您可以通过在下面的模板中替换变量来创建文件的 URL。
https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt
其中
AIRFLOW_VERSION- Airflow 版本（例如2.10.4）或main，2-0，适用于最新的开发版本PYTHON_VERSIONPython 版本，例如3.8，3.9
下面的示例假设您希望使用 celery extra 以可复现的方式安装 airflow，但您可以选择自己的一组 extras 和 providers 进行安装。
pip install "apache-airflow[celery]==2.10.4" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.4/constraints-3.8.txt"
注意
可复现的安装保证此初始安装步骤始终适用于您 - 前提是您使用正确的 Python 版本，并且您已为要安装的 providers 安装了适当的操作系统依赖项。某些 providers 需要安装其他操作系统依赖项，例如 build-essential 以编译库，或者例如，如果您安装数据库 provider，则需要安装数据库客户端库等。当您的安装失败时，您需要弄清楚您需要哪些系统依赖项，并在重试安装之前安装它们。
升级和安装依赖项（包括 providers）¶
上面的可复现安装不应阻止您升级或降级 providers 和其他依赖项到其他版本
例如，您可以在发布后安装新版本的 providers 和依赖项，以使用最新版本并及时进行最新的安全修复 - 即使您不想升级 airflow 核心版本。或者，如果您出于兼容性原因想要保留以前的版本，则可以降级某些依赖项或 providers。安装此类依赖项应在没有约束的情况下作为单独的 pip 命令完成。
当您进行此类升级时，您应该确保还将 apache-airflow 包添加到要安装的包列表中，并将其固定到您拥有的版本，否则您可能会最终得到与您期望的不同的 Airflow 版本，因为 pip 在执行依赖项解析时可以自动升级/降级它。
pip install "apache-airflow[celery]==2.10.4" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.4/constraints-3.8.txt"
pip install "apache-airflow==2.10.4" apache-airflow-providers-google==10.1.1
您也可以通过这种方式降级或升级其他依赖项 - 即使它们与原始约束文件中存储的那些依赖项不兼容
pip install "apache-airflow[celery]==2.10.4" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.4/constraints-3.8.txt"
pip install "apache-airflow[celery]==2.10.4" dbt-core==0.20.0
警告
并非所有依赖项都可以通过这种方式安装 - 您可能会遇到与 Airflow 的基本要求或系统中安装的其他依赖项冲突的依赖项。但是，通过在安装或升级依赖项时跳过约束，您可以让 pip 有机会为您解决冲突，同时将依赖项保持在 Apache Airflow、providers 和其他依赖项要求的限制范围内。这些依赖项的组合和约束附带的依赖项集可能之前未经测试，但它在大多数情况下应该可以工作，因为当 Airflow 依赖于某些依赖项的特定版本时，我们通常会添加要求。如果您无法在与 Airflow 相同的环境中安装某些依赖项，则可以尝试使用其他方法。请参阅 处理冲突/复杂的 Python 依赖项的最佳实践
验证已安装的依赖项¶
您还可以始终运行 pip check 命令来测试您的 Python 包集是否一致且没有冲突。
> pip check
No broken requirements found.
当您看到这样的消息并且 pip check 的退出代码为 0 时，您可以确定您的环境中没有冲突的依赖项。
使用您自己的约束¶
当您决定安装自己的依赖项，或者想要升级或降级 providers 时，您可能希望继续能够通过单个命令保持 Airflow 和这些依赖项的可复现安装。为此，您可以生成自己的约束文件，并使用它来安装 Airflow，而不是社区提供的约束文件。
pip install "apache-airflow[celery]==2.10.4" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.4/constraints-3.8.txt"
pip install "apache-airflow==2.10.4" dbt-core==0.20.0
pip freeze > my-constraints.txt
然后，您可以使用它通过本地约束文件在单个操作中创建可复现的环境安装
pip install "apache-airflow[celery]==2.10.4" --constraint "my-constraints.txt"
与 Airflow 原始约束的情况类似，您也可以将您的约束托管在您自己的存储库或服务器上，并从那里远程使用它。
在发布时修复约束¶
发布的“版本化”约束在 Airflow 版本发布时大多是 fixed 的，我们只会在特殊情况下更新它们。例如，当我们发现发布的约束可能导致 Airflow 无法从头开始一致安装时。
在正常情况下，如果发布了新版本的 Airflow 依赖项，约束文件不会更改 - 即使这些版本包含关键的安全修复程序。Airflow 发布过程的设计理念是在适用情况下自动升级依赖项，但仅在发布新版本的 Airflow 时升级，而不是针对已发布的版本。
在发布版本之间，您可以自行升级依赖项，并且可以按照上一节中的说明保持您自己的约束更新。
跟上最新发布依赖项的最简单方法是升级到最新发布的 Airflow 版本。每当我们发布新版本的 Airflow 时，我们会将所有依赖项升级到最新的适用版本并一起测试它们，因此，如果您想跟上这些测试，保持 Airflow 最新版本是最简单的更新这些依赖项的方法。
安装和升级场景¶
为了简化安装，我们准备了如何升级 Airflow 和 providers 的示例。
安装带有 extras 和 providers 的 Airflow®¶
如果您需要安装 Airflow® 的额外依赖项，可以使用下面的脚本使安装成为一行代码（下面的示例安装了 Postgres 和 Google providers，以及 async extra）。
AIRFLOW_VERSION=2.10.4
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 发布时可用的 providers 版本。如果您想在 provider 包发布后升级它们，则需要运行单独的不带约束的 pip 命令。
将 Airflow 与 providers 一起升级¶
您可以将 airflow 与 extras 一起升级（在安装 Airflow 时可用的 providers）。这将使 apache-airflow 和所有 providers 升级到您正在安装的 Airflow 版本发布时发布并一起测试的版本。
AIRFLOW_VERSION=2.10.4
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 核心分开管理 providers¶
为了添加新功能、实现错误修复或仅仅维护向后兼容性，您可能需要安装、升级或降级任何 provider - 与 Airflow Core 包分开。我们独立于 Airflow 核心发布 providers，因此通常 providers 的新版本会在 Airflow 发布之前发布，如果您不想将 Airflow 升级到最新版本，您可能只想单独安装一些（或全部）新发布的 providers。
正如您在上面看到的，当单独安装 providers 时，您不应该使用任何约束文件。
如果您自动构建环境，则应该在安装 Airflow 之后（通常带有约束）运行单独的命令来安装 provider。约束仅在使用它们的 pip install 命令期间有效。
最佳实践是以与原始镜像相同的版本安装 apache-airflow。这样可以确保在安装其他要求时，pip 不会尝试降级或升级 apache-airflow，如果您尝试添加与您正在使用的 apache-airflow 版本冲突的依赖项，可能会发生这种情况。
pip install "apache-airflow==2.10.4" "apache-airflow-providers-google==8.0.0"
注意
单独安装、升级、降级 providers 并不能保证适用于所有 Airflow 版本或其他 providers。一些 providers 对 Airflow 有最低版本要求，一些版本的 providers 可能对依赖项有限制，这些限制与其他 providers 或其他已安装依赖项的限制冲突。例如，10.1.0 版本之前的 google provider 对 protobuf 库的限制为 <=3.20.0，而 google 支持的 google-ads 库则要求 protobuf 库为 >=4。在这种情况下，在单个环境中同时安装这两个依赖项将不起作用。在这种情况下，您可以尝试使用其他方法。请参阅处理冲突/复杂的 Python 依赖项的最佳实践
仅管理 Airflow 核心，不包括 providers¶
如果您不想安装任何 providers，只想安装或升级 Apache Airflow，您可以简单地安装您需要的 Airflow 版本。您可以使用特殊的 constraints-no-providers 约束文件，该文件更小，并且仅将依赖项限制为 Airflow 的核心，但是，如果您的环境中已经安装了某些不同版本的依赖项，并且您安装了其他 providers，则可能会导致冲突。但是，此命令为您提供了 Airflow 发布时与 Airflow 核心兼容的最新版本的依赖项。
AIRFLOW_VERSION=2.10.4
PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
# For example: 3.8
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-2.10.4/constraints-no-providers-3.8.txt
pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
注意
Airflow 使用 Scarf 在运行期间收集基本使用情况数据。请查看使用情况数据收集常见问题解答，以获取有关收集的数据以及如何选择退出的更多信息。
故障排除¶
本节介绍如何对 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 而不是框架安装（例如，对于 python 3.8：/usr/local/opt/[email protected]/Frameworks/Python.framework/Versions/3.8）造成的。
问题的关键在于 Airflow 依赖的库 setproctitle 使用了一个非公开的 Python API，该 API 在标准安装 /usr/local/opt/ （它符号链接到 /usr/local/Cellar 下的路径）中不可用。
一个简单的解决方法是确保您使用的 Python 版本具有可用的 Python 库的 dylib。例如
# Note: these instructions are for python3.8 but can be loosely modified for other versions
brew install [email protected]
virtualenv -p /usr/local/opt/[email protected]/Frameworks/Python.framework/Versions/3.8/bin/python3 .toy-venv
source .toy-venv/bin/activate
pip install apache-airflow
python
>>> import setproctitle
# Success!
或者，您可以直接从Python 网站下载并安装 Python。