从 PyPI 安装¶
本页介绍使用 在 PyPI 中发布的 apache-airflow 软件包进行安装。
安装工具¶
目前官方仅支持 pip 安装。
注意
虽然使用 poetry 或 pip-tools 等其他工具取得了一些成功，但它们与 pip 的工作流程并不相同，尤其是在约束与需求管理方面。目前不支持通过 Poetry 或 pip-tools 进行安装。如果您希望使用这些工具安装 airflow，则应使用约束并将它们转换为您的工具所需的适当格式和工作流程。
已知 bazel 存在一些问题，在使用它安装 Airflow 时可能会导致循环依赖。如果遇到此类问题，请切换到 pip。 Bazel 社区正在 此 PR 中努力解决此问题，因此较新版本的 bazel 可能会处理它。
以下是从 PyPI 以可重复的方式从头开始安装 airflow 的典型命令
pip install "apache-airflow[celery]==2.9.2" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.9.2/constraints-3.8.txt"
通常，您可以在可重复安装后将其他依赖项和提供者作为单独的命令添加 - 这样您就可以根据需要升级或降级依赖项，而不会将它们限制为约束。这些命令的良好做法是使用已安装的 apache-airflow 版本扩展此类 pip install 命令，以确保它不会被 pip 意外升级或降级。
pip install "apache-airflow==2.9.2" 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.9.2。
通过这种方式，我们在发布时保留了一组经过测试的依赖项。这使您能够拥有与发布时已知工作完全相同的 airflow + 提供者 + 依赖项安装 - 该 Airflow 版本的冻结依赖项集。Airflow 支持的每个 Python 版本都有一个单独的约束文件。
您可以通过替换以下模板中的变量来创建文件的 URL。
https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt
其中
AIRFLOW_VERSION- Airflow 版本（例如2.9.2）或main、2-0，用于最新的开发版本PYTHON_VERSIONPython 版本，例如3.8、3.9
以下示例假设您希望以可重复的方式使用 celery 额外功能安装 airflow，但您可以选择自己的额外功能和提供者集进行安装。
pip install "apache-airflow[celery]==2.9.2" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.9.2/constraints-3.8.txt"
注意
可重复安装保证了此初始安装步骤将始终对您有效 - 前提是您使用正确的 Python 版本，并且已为要安装的提供者安装了适当的操作系统依赖项。某些提供者需要安装额外的操作系统依赖项，例如 build-essential 以便编译库，或者例如在您安装数据库提供者的情况下安装数据库客户端库等。您需要在安装失败时找出需要哪些系统依赖项，并在重试安装之前安装它们。
升级和安装依赖项（包括提供者）¶
上述可重复安装不应妨碍您能够将提供者和其他依赖项升级或降级到其他版本
例如，您可以在发布后安装新版本的提供者和依赖项，以使用最新版本并更新最新的安全修复程序 - 即使您不想升级 airflow 核心版本。或者，如果您出于兼容性原因希望保留以前的版本，则可以降级某些依赖项或提供者。安装此类依赖项应在没有约束的情况下作为单独的 pip 命令完成。
执行此类升级时，应确保将 apache-airflow 软件包添加到要安装的软件包列表中，并将其固定到您拥有的版本，否则您最终可能会得到与预期不同的 Airflow 版本，因为 pip 可以在执行依赖项解析时自动升级/降级它。
pip install "apache-airflow[celery]==2.9.2" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.9.2/constraints-3.8.txt"
pip install "apache-airflow==2.9.2" apache-airflow-providers-google==10.1.1
您还可以通过这种方式降级或升级其他依赖项 - 即使它们与存储在原始约束文件中的那些依赖项不兼容
pip install "apache-airflow[celery]==2.9.2" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.9.2/constraints-3.8.txt"
pip install "apache-airflow[celery]==2.9.2" 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]==2.9.2" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.9.2/constraints-3.8.txt"
pip install "apache-airflow==2.9.2" dbt-core==0.20.0
pip freeze > my-constraints.txt
然后，您可以使用它通过本地约束文件在一个操作中创建可重复的环境安装
pip install "apache-airflow[celery]==2.9.2" --constraint "my-constraints.txt"
与 Airflow 原始约束类似，您也可以将约束托管在您自己的存储库或服务器上，并从那里远程使用它。
在发布时修复约束¶
已发布的“版本化”约束在我们发布 Airflow 版本时大多是 固定的，我们只会在特殊情况下更新它们。例如，当我们发现发布的约束可能会阻止 Airflow 从头开始一致地安装时。
在正常情况下，如果发布了新版本的 Airflow 依赖项，约束文件将不会更改 - 即使这些版本包含关键的安全修复程序也是如此。Airflow 版本的流程旨在在适用时自动升级依赖项，但仅在我们发布新版本的 Airflow 时，而不是针对已发布的版本。
在版本之间，您可以自行升级依赖项，并且可以按照上一节中的描述保持自己的约束更新。
跟上最新发布的依赖项的最简单方法是升级到最新发布的 Airflow 版本。每当我们发布新版本的 Airflow 时，我们都会将所有依赖项升级到最新的适用版本并一起测试它们，因此，如果您想跟上这些测试 - 保持最新版本的 Airflow 是更新这些依赖项的最简单方法。
安装和升级方案¶
为了简化安装，我们准备了一些如何升级 Airflow 和提供程序的示例。
安装带有额外功能和提供程序的 Airflow™¶
如果您需要安装 Airflow™ 的额外依赖项，可以使用以下脚本使安装成为一行代码（以下示例安装 Postgres 和 Google 提供程序，以及 async 额外功能）。
AIRFLOW_VERSION=2.9.2
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 与额外功能（在安装 Airflow 时可用的提供程序）一起升级。这会将 apache-airflow 和所有提供程序升级到在您要安装的 Airflow 版本发布时一起发布和测试的版本。
AIRFLOW_VERSION=2.9.2
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==2.9.2" "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=2.9.2
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.9.2/constraints-no-providers-3.8.txt
pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
故障排除¶
本节介绍如何解决 PyPI 安装问题。
无法识别“airflow”命令¶
如果无法识别 airflow 命令（在 Windows 上使用 WSL 时可能会发生），请确保 ~/.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.8：/usr/local/opt/[email protected]/Frameworks/Python.framework/Versions/3.8）。
问题的症结在于 Airflow 依赖的库 setproctitle 使用了标准安装 /usr/local/opt/（符号链接到 /usr/local/Cellar 下的路径）中不可用的非公共 Python API。
一个简单的解决方法是确保您使用的是具有 Python 库的 dylib 的 Python 版本。例如
# 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。