從 PyPI 安裝¶
本頁說明使用 apache-airflow 套件從 PyPI 發布 進行安裝。
安裝工具¶
目前僅正式支援 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.4" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.4/constraints-3.8.txt"
通常，您可以在可重現的安裝之後添加其他依賴性和供應商作為單獨的命令 - 這樣您可以隨意升級或降級依賴性，而無需將它們限制在約束中。對於這些依賴性和供應商，良好的做法是使用 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 + 供應商 + 依賴性完全相同的安裝 - 該 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
以下範例假設您想要以可重現的方式安裝 airflow，並使用 celery 額外功能，但您可以選擇自己的一組額外功能和供應商進行安裝。
pip install "apache-airflow[celery]==2.10.4" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.10.4/constraints-3.8.txt"
注意
可重現的安裝保證此初始安裝步驟始終適用於您 - 前提是您使用正確的 Python 版本，並且您已安裝適用於要安裝的供應商的適當作業系統依賴性。某些供應商需要安裝額外的作業系統依賴性，例如 build-essential 以編譯函式庫，或者例如在您安裝資料庫供應商時的資料庫用戶端函式庫等。當您的安裝失敗時，您需要找出您需要的系統依賴性，並在重新嘗試安裝之前安裝它們。
升級和安裝依賴性（包含供應商）¶
上述可重現的安裝不應阻止您升級或降級供應商和其他依賴性到其他版本
例如，您可以在發布後安裝新版本的供應商和依賴性，以使用最新版本並與最新的安全性修復保持同步 - 即使您不想升級 airflow 核心版本。或者，如果您想基於相容性原因保留以前的版本，您可以降級某些依賴性或供應商。安裝此類依賴性應該在沒有約束的情況下作為單獨的 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、供應商和其他依賴性要求的限制範圍內。這些依賴性的結果組合以及約束附帶的依賴性集可能以前未經過測試，但在大多數情況下應該可以運作，因為我們通常會在 Airflow 依賴於某些依賴性的特定版本時新增需求。如果您無法在與 Airflow 相同的環境中安裝某些依賴性 - 您可以嘗試使用其他方法。請參閱 處理衝突/複雜 Python 依賴性的最佳實務
驗證已安裝的依賴性¶
您也可以隨時執行 pip check 命令來測試您的 Python 套件集是否一致且沒有衝突。
> pip check
No broken requirements found.
當您看到此訊息且 pip check 的結束代碼為 0 時，您可以確定您的環境中沒有衝突的依賴性。
使用您自己的約束¶
當您決定安裝自己的依賴性，或想要升級或降級供應商時，您可能希望繼續能夠透過單一命令保持 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 和供應商的範例。
安裝具有額外功能和供應商的 Airflow®¶
如果您需要安裝 Airflow® 的額外依賴性，您可以使用以下腳本使安裝成為單行程式碼（以下範例安裝 Postgres 和 Google 供應商，以及 async 額外功能）。
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 版本發布時可用的供應商版本。如果您想在供應商套件發布後升級它們，您需要執行單獨的、沒有約束的 pip 命令。
將 Airflow 與供應商一起升級¶
您可以將 airflow 與額外功能（在安裝的 Airflow 版本發布時可用的供應商）一起升級。這會將 apache-airflow 和所有供應商帶到當您安裝的 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 核心分開管理供應商¶
為了新增新功能、實作錯誤修復或僅僅維護向後相容性，您可能需要單獨於 Airflow 核心套件安裝、升級或降級任何供應商。我們獨立於 Airflow 核心發布供應商，因此通常在 Airflow 發布之前發布新版本的供應商，此外，如果您還不想將 Airflow 升級到最新版本，您可能希望單獨安裝一些（或全部）新發布的供應商。
如您在上面看到的，在單獨安裝供應商時，您不應使用任何約束檔案。
如果您自動構建環境，您應該在安裝 Airflow（通常帶有約束）後，將供應商的安裝作為單獨的命令執行。約束僅在與它們一起使用的 pip install 命令期間有效。
最佳實務是以與原始映像檔相同的版本安裝 apache-airflow。這樣您可以確保在安裝其他需求時，pip 不會嘗試降級或升級 apache airflow，如果您嘗試新增與您正在使用的 apache-airflow 版本衝突的依賴性，可能會發生這種情況
pip install "apache-airflow==2.10.4" "apache-airflow-providers-google==8.0.0"
注意
單獨安裝、升級、降級供應商不能保證適用於所有 Airflow 版本或其他供應商。某些供應商具有 Airflow 的最低需求版本，並且某些版本的供應商可能對依賴性有限制，這些限制與其他供應商或其他已安裝的依賴性的限制衝突。例如，10.1.0 版本之前的 google 供應商對 protobuf 函式庫有限制 <=3.20.0，而例如 google-ads 函式庫（由 google 支援）對 protobuf 函式庫有 >=4 的要求。在這種情況下，在單一環境中並排安裝這兩個依賴性將無法運作。在這種情況下，您可以嘗試使用其他方法。請參閱 處理衝突/複雜 Python 依賴性的最佳實務
僅管理 Airflow 核心而不包含供應商¶
如果您不想安裝任何供應商，只想安裝或升級 Apache Airflow，您可以簡單地安裝您需要的版本的 airflow。您可以使用特殊的 constraints-no-providers 約束檔案，它更小，並且僅將依賴性限制為 Airflow 的核心，但是，如果您的環境已經安裝了不同版本的某些依賴性，並且您安裝了其他供應商，這可能會導致衝突。但是，此命令為您提供與 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 而不是 Frameworks 安裝（例如，對於 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。