从PyPI安装¶
本页面介绍使用PyPI发布的apache-airflow包进行安装的相关内容。
安装工具¶
目前仅官方支持pip安装方式。
注意
虽然使用其他工具如poetry或pip-tools取得了一些成功，但它们的工作流程与pip并不相同——特别是在约束条件与需求管理方面。目前不支持通过Poetry或pip-tools安装airflow。如果您希望使用这些工具安装airflow，您应该使用约束条件并将其转换为您的工具所需的适当格式和工作流程。
已知在使用bazel安装Airflow时可能会出现循环依赖问题。如遇此类问题，请改用pip安装。Bazel社区正在通过这个PR修复该问题，因此新版bazel可能会解决此问题。
从PyPI以可重现的方式全新安装airflow的典型命令如下所示：
pip install "apache-airflow[celery]==2.10.5" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.5/constraints-3.8.txt"
通常，您可以在完成可复现安装后，通过单独命令添加其他依赖项和providers——这样您就可以根据需要升级或降级依赖项，而不受约束限制。最佳实践是在此类pip install命令中扩展使用apache-airflow，并将其固定到已安装版本，以确保不会因pip操作意外升级或降级。
pip install "apache-airflow==2.10.5" apache-airflow-providers-google==10.1.0
这些只是示例，更多关于为什么这些是最佳实践的解释请继续往下看。
注意
一般来说，Python社区建立的惯例是在通过virtualenv或venv工具创建的虚拟环境中执行应用安装。您也可以使用pipx将Airflow®安装到专为应用程序创建的虚拟环境中。还有其他工具可用于管理虚拟环境安装，您可以自由选择环境管理方式。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.5。
通过这种方式，我们在发布时维护了一套经过测试的依赖项。这使您能够获得与发布时已知可用的airflow + providers + dependencies完全相同的安装环境 - 即该版本Airflow的固定依赖集合。Airflow支持的每个Python版本都有单独的约束文件。
您可以通过替换下方模板中的变量来创建文件的URL。
https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt
其中：
AIRFLOW_VERSION- Airflow版本号（例如2.10.5）或main、2-0，表示最新开发版本PYTHON_VERSIONPython版本，例如3.8,3.9
以下示例假设您希望以可重现的方式安装airflow并使用celery扩展包，但您可以选择自己的扩展包集合和提供程序进行安装。
pip install "apache-airflow[celery]==2.10.5" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.5/constraints-3.8.txt"
注意
可重现的安装保证了这些初始安装步骤始终有效 - 前提是您使用正确的Python版本，并且为要安装的providers安装了适当的操作系统依赖项。某些providers需要安装额外的操作系统依赖项，例如build-essential用于编译库，或者如果您安装数据库provider，则需要数据库客户端库等。当安装失败时，您需要确定需要哪些系统依赖项，并在重试安装之前安装它们。
升级和安装依赖项（包括providers）¶
上述可复现的安装方式不应妨碍您升级或降级提供程序及其他依赖项的版本
例如，您可以在发布后安装新版本的providers和依赖项，以使用最新版本并保持与最新安全修复同步——即使您不想升级airflow核心版本。或者，出于兼容性原因，如果您希望保留旧版本，也可以降级某些依赖项或providers。安装此类依赖项时应作为单独的pip命令执行，无需约束。
在进行此类升级时，您应确保将apache-airflow包添加到待安装包列表中，并将其固定为您当前使用的版本，否则您可能会得到与预期不同的Airflow版本，因为pip在执行依赖项解析时会自动升级/降级该包。
pip install "apache-airflow[celery]==2.10.5" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.5/constraints-3.8.txt"
pip install "apache-airflow==2.10.5" apache-airflow-providers-google==10.1.1
您也可以通过这种方式降级或升级其他依赖项 - 即使它们与原始约束文件中存储的那些依赖项不兼容：
pip install "apache-airflow[celery]==2.10.5" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.5/constraints-3.8.txt"
pip install "apache-airflow[celery]==2.10.5" 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.10.5" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.5/constraints-3.8.txt"
pip install "apache-airflow==2.10.5" dbt-core==0.20.0
pip freeze > my-constraints.txt
然后，你可以通过本地约束文件，在单一操作中创建可复现的环境安装：
pip install "apache-airflow[celery]==2.10.5" --constraint "my-constraints.txt"
与Airflow原始约束条件类似，您也可以将约束文件托管在自己的代码库或服务器上，并远程调用使用。
在发布时修复约束条件¶
发布的"版本化"约束在Airflow版本发布时大多是固定的，我们只在特殊情况下才会更新它们。例如当我们发现已发布的约束可能会阻止Airflow从头开始一致安装时。
在正常情况下，即使Airflow依赖项发布了新版本，约束文件也不会发生变化——即使这些版本包含关键的安全修复。Airflow的发布流程设计为在适用时自动升级依赖项，但仅在我们发布新版本的Airflow时进行，不会针对已发布的版本进行更新。
在版本发布之间，您可以自行升级依赖项，并按照前一节所述保持自己的约束条件更新。
跟上最新发布依赖项的最简单方法是升级到最新发布的Airflow版本。每当我们发布新版本的Airflow时，我们都会将所有依赖项升级到最新的适用版本并进行联合测试，因此如果您想保持与这些测试同步，保持使用最新版本的Airflow就是更新这些依赖项的最简单方式。
安装与升级场景¶
为了简化安装过程，我们准备了如何升级Airflow和提供者的示例。
安装Airflow®及其扩展和提供程序¶
如果您需要安装Airflow®的额外依赖项，可以使用以下脚本实现一行式安装（以下示例安装了Postgres和Google提供商，以及async扩展包）。
AIRFLOW_VERSION=2.10.5
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版本发布时可用的provider版本。如果您想升级后续发布的provider包，需要运行不带约束条件的单独pip命令。
将Airflow与providers一起升级¶
您可以升级airflow及其扩展功能（安装时提供的providers版本与所安装的Airflow版本同步）。这将使apache-airflow和所有providers升级到与您安装的Airflow版本同时发布并经过测试的对应版本。
AIRFLOW_VERSION=2.10.5
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核心包。我们发布的providers与Airflow核心是分开的，因此新版本的providers通常会在Airflow发布之前推出。此外，如果您还不想将Airflow升级到最新版本，您可能希望单独安装部分（或全部）新发布的providers。
如上所述，单独安装providers时，不应使用任何约束文件。
如果您自动构建环境，应在安装Airflow后（通常带有约束条件）单独运行提供程序的安装命令。约束仅在执行pip install命令时有效。
最佳实践是将apache-airflow安装为与原始镜像相同的版本。这样可以确保pip在安装其他依赖项时不会尝试降级或升级apache airflow，这种情况可能发生在您尝试添加与当前使用的apache-airflow版本冲突的依赖项时：
pip install "apache-airflow==2.10.5" "apache-airflow-providers-google==8.0.0"
注意
单独安装、升级或降级providers不能保证与所有Airflow版本或其他providers兼容。某些providers对Airflow有最低版本要求，而某些provider版本可能存在依赖限制，这些限制可能与其他providers或已安装的其他依赖项冲突。例如google provider在10.1.0版本之前对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.5
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.5/constraints-no-providers-3.8.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而非框架安装版本(例如对于python 3.8来说应该是/usr/local/opt/python@3.8/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 python@3.8
virtualenv -p /usr/local/opt/python@3.8/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。