與 --additional-python-modules 的主要差異選擇合適方案搭配 Amazon S3 快取使用服務產生的虛擬環境建置您自己的虛擬環境使用 Kiro 自動化遷移疑難排解

搭配 Glue 使用 Python AWS 虛擬環境

從 AWS Glue 5.0 開始，您可以在 Python 虛擬環境 (venv) 中執行 ETL 任務。虛擬環境會從任務執行中移除執行時間相依性解析，確保每次執行都使用相同的套件，並防止上游套件變更所造成的失敗。

AWS Glue 支援兩種使用虛擬環境的方式：

服務產生的虛擬環境 – 可在 AWS Glue 6.0 和更新版本中使用。您可以新增 --python-virtual-env-storage-prefix 參數，而 AWS Glue 會為您建置虛擬環境，並在 Amazon S3 中快取它以供日後任務執行。不需要本機建置。
手動建置的虛擬環境 – 適用於 AWS Glue 5.0 及更新版本。您可以在本機電腦或 CI/CD 管道中建置虛擬環境，將其上傳至 Amazon S3，並使用 --python-virtual-env 參數加以參考。

本主題說明如何將使用的任務遷移--additional-python-modules至任一方法。如需有關管理 Python 相依性的其他方法的資訊，請參閱搭配 Glue 使用 Python AWS 程式庫。

與 --additional-python-modules 的主要差異

下表--additional-python-modules與手動建置的虛擬環境進行比較。

功能	`--additional-python-modules`	`--python-virtual-env`
基本容器程式庫 (boto3、pandas、 numpy和其他）	自動提供	不可用。您必須在 venv 中包含所有必要的套件。
相依性解析	在執行時間發生	在機器上的建置時間發生
執行時間隔離	部分。套件安裝在基礎程式庫的頂端。	完整。完全取代 Python 環境。

重要

當您遷移至時--python-virtual-env，您必須在虛擬環境中包含任務所需的每個 Python 套件。這包括先前可從 Glue AWS 基礎容器取得的套件，例如 boto3、 numpy和 pandas。這些套件不再是隱含的。

選擇合適方案

使用下表來決定適合您任務的方法。

案例	建議方法
使用少量 pip 套件的簡單任務，無需建置額外負荷	服務產生的 venv （新增 `--python-virtual-env-storage-prefix`)。需要 AWS Glue 6.0 或更新版本。
建置 venv 的複雜相依性樹狀目錄、完整重現性或 CI/CD 管道	手動建置 venv (`--python-virtual-env`)。需要 AWS Glue 5.0 或更新版本。
`--additional-python-modules` 以最少的變更從遷移	服務產生的 venv （新增 `--python-virtual-env-storage-prefix`)。需要 AWS Glue 6.0 或更新版本。在 AWS Glue 5.0 和 5.1 上，請改用手動建置的虛擬環境。
具有自訂套件的私有PyPI索引	任一種方法。服務產生的 venv 需要 AWS Glue 6.0 或更新版本，並使用。 --python-modules-installer-option

搭配 Amazon S3 快取使用服務產生的虛擬環境

從 AWS Glue 6.0 開始，您可以使用 --python-virtual-env-storage-prefix 參數讓 AWS Glue 建置虛擬環境，並在 Amazon S3 中快取它。此方法結合了的簡單性--additional-python-modules與快取虛擬環境的效能優勢。

運作方式

當您提供時--python-virtual-env-storage-prefix， AWS Glue 會執行下列動作：

在第一次執行（快取遺漏） 時 – AWS Glue 會使用建立虛擬環境--system-site-packages，這會繼承容器套件，例如 numpy、和 pyarrow. AWS Gluepandas，然後使用 --additional-python-modules pip 安裝來自的套件，將虛擬環境封裝為 .tar.gz 檔案，並將其上傳至 Amazon S3 字首以供日後重複使用。
稍後執行時（快取命中） – AWS Glue 會從 Amazon S3 下載快取檔案、擷取快取.tar.gz檔案，並將 Spark 驅動程式和執行程式設定為使用虛擬環境。不會進行 pip 安裝。

與手動建置虛擬環境的差異

下表將服務產生的虛擬環境與手動建置的方法進行比較。

功能	服務產生的 venv	手動建置的 venv
建立責任	AWS Glue 會自動建置 venv	您可以在中建置 venv Docker
容器套件	透過繼承 `--system-site-packages`	您必須明確包含所有套件
初次執行延遲	pip 安裝、封裝和 Amazon S3 上傳的額外時間	無，因為 venv 是預先建置的
稍後執行延遲	Amazon S3 下載和擷取的額外時間	Amazon S3 下載和擷取的額外時間
確定性	我們建議您鎖定套件版本	完全確定，因為版本在建置時已鎖定
PyPI 存取	第一次執行時需要	不需要，因為 venv 已離線建置

設定服務產生的虛擬環境

--python-virtual-env-storage-prefix 參數指定 Amazon S3 位置，其中 AWS Glue 存放其建置的虛擬環境，格式為 s3://path/。 AWS Glue 會在第一次任務執行時在此字首快取虛擬環境，並在稍後執行時重複使用。

若要啟用服務產生的虛擬環境，請將 --python-virtual-env-storage-prefix 參數新增至您的任務，並保留現有的 --additional-python-modules 參數。


"--additional-python-modules": "requests==2.32.3,scikit-learn==1.5.0"
"--python-virtual-env-storage-prefix": "s3://amzn-s3-demo-bucket/venv-cache/"

您也可以使用下列選用參數：

--python-virtual-env-version – 快取虛擬環境的版本識別符。變更此值使快取失效，並強制 AWS Glue 重建虛擬環境。值是字串，因此您可以使用任何適合您工作流程的版本控制方案，例如遞增數字、日期或組建識別符。預設值為 0。
--python-modules-installer-option – 將選項傳遞至 pip，例如 --no-deps或 --index-url。

若要啟用現有任務的快取，請新增儲存字首參數。第一次執行需要更長的時間，因為 AWS Glue 會建置和上傳虛擬環境，但稍後執行會使用快取的虛擬環境，且不執行 pip 解析度。


# Before
"--additional-python-modules": "requests==2.32.3"

# After
"--additional-python-modules": "requests==2.32.3"
"--python-virtual-env-storage-prefix": "s3://amzn-s3-demo-bucket/venv-cache/"

Glue AWS 如何快取虛擬環境

AWS Glue 會依您的任務組態來鎖定快取。組態包含來自的模組--additional-python-modules、的值--python-modules-installer-option、Glue AWS 版本和的值--python-virtual-env-version。

未變更的組態會導致快取命中。如果您變更任何這些值， AWS Glue 會建立新的虛擬環境並建立新的快取項目。

AWS Glue 會將每個快取的虛擬環境存放在儲存字首中的個別金鑰下。使用相同模組和安裝程式選項的任務會共用相同的快取項目。

限制

需要 AWS Glue 6.0 或更新版本。
第一次執行需要存取 PyPI或您的私有索引，才能解析相依性。
numpy 和等容器套件pandas會繼承，但不會以版本鎖定。如果您的任務需要確切版本的容器套件，請--python-virtual-env改用。
快取會依組態輸入索引鍵。變更任何模組或版本都會建立新的快取項目，而舊版項目會保留在 Amazon S3 中，直到您將其移除為止。

建置您自己的虛擬環境

在 AWS Glue 5.0 和更新版本中，您可以自行建置虛擬環境，並使用 --python-virtual-env 參數加以參考。當您需要完整重現性、容器套件的確切版本，或在 CI/CD 管道中執行的建置時，請使用此方法。

先決條件

開始前，請確定您有下列項目：

Docker 從安裝在本機機器上的 Docker網站，讓您可以在 AWS 與 Glue 相容的環境中建置虛擬環境
用於上傳封裝虛擬環境的 Amazon S3 儲存貯體
設定的 AWS CLI 具有上傳到 Amazon S3 和更新 AWS Glue 任務參數的許可

如需每個 Glue 版本的 Python AWS 版本和平台相容性詳細資訊，請參閱附錄 B： AWS Glue 環境詳細資訊。

步驟 1：建立您的需求檔案

建立兩個定義虛擬環境套件的需求檔案。

從 GitHub 網站上的儲存aws-glue-libs庫下載 base-requirements.txt AWS Glue 版本。此檔案列出標準 Glue AWS 容器提供的套件。如需本指南中的相同清單，請參閱 Python 模組已在 Glue AWS 中提供。
- AWS GitHub網站 Glue 5.0 – base-requirements.txt
- AWS GitHub網站 Glue 5.1 – base-requirements.txt
- AWS GitHub網站 Glue 6.0 – base-requirements.txt
建立 additional-requirements.txt。從現有--additional-python-modules參數新增套件，每行一個。例如：
```
cryptography
requests-oauthlib
sqlalchemy
```

重要

如果您的任務使用 AWS Glue Python 程式庫，例如 GlueContext或 DynamicFrame，您還必須包含來自 PyPI網站的 AWSGlueDataplanePython 套件。使用符合您 Glue AWS 版本的版本，如下表所示。

AWS Glue 版本	套件版本
5.0	`AWSGlueDataplanePython==5.0.0`
5.1	`AWSGlueDataplanePython==5.1.0`
6.0	`AWSGlueDataplanePython==6.0.0`

步驟 2：建立Dockerfile

建立Dockerfile符合您目標 Glue AWS 版本環境的。如需平台和 Python 版本的詳細資訊，請參閱附錄 B： AWS Glue 環境詳細資訊。

AWS Glue 5.0 和 5.1 在 Amazon Linux 2023 上使用 Python 3.11。


FROM --platform=linux/amd64 public.ecr.aws/amazonlinux/amazonlinux:2023-minimal

RUN dnf install -y python3.11 zip && \
    dnf clean all

WORKDIR /build

AWS Glue 6.0 在 Amazon Linux 2023 上使用 Python 3.13。


FROM --platform=linux/amd64 public.ecr.aws/amazonlinux/amazonlinux:2023-minimal

RUN dnf install -y python3.13 zip && \
    dnf clean all

WORKDIR /build

步驟 3：建置和啟動容器

建置Docker映像。然後啟動已掛載需求檔案和任務指令碼的容器。


docker build --platform linux/amd64 -t glue-venv-builder .

docker run --platform linux/amd64 \
  -v $(pwd)/base-requirements.txt:/working_dir/base-requirements.txt:ro \
  -v $(pwd)/additional-requirements.txt:/working_dir/additional-requirements.txt:ro \
  -v $(pwd)/my_glue_script/:/working_dir/my_glue_script/:ro \
  -v $(pwd):/output \
  -w /working_dir \
  -it glue-venv-builder bash

此命令會掛載您的需求檔案和 Glue AWS 任務指令碼目錄。下列步驟使用指令碼目錄進行匯入分析。

步驟 4：建置臨時 venv 並探索必要的套件

在容器內，建置可鏡射 AWS Glue 執行時間的暫時 venv。然後使用靜態分析來尋找任務所需的最小套件集。

對於使用 Python 3.11 的 AWS Glue 5.0 和 5.1，請執行下列命令。


# Create a temporary venv to reproduce the AWS Glue runtime environment
python3.11 -m venv temp_venv
source temp_venv/bin/activate

python3.11 -m pip install --upgrade pip

# Install base container libraries (mirrors what the AWS Glue container provides)
python3.11 -m pip install -r base-requirements.txt

# Install additional Python modules on top (mirrors how AWS Glue installs them at runtime)
python3.11 -m pip install -r additional-requirements.txt

# Freeze the full resolved environment
pip freeze > full-requirements.txt

# Install analysis tools
python3.11 -m pip install pipreqs pip-tools

# Use pipreqs to discover what the script actually imports
# --mode no-pin outputs package names without versions
pipreqs --mode no-pin --savepath discovered-requirements.txt /working_dir/my_glue_script

# Remove packages provided by the Spark runtime
sed -i '/pyspark/d' discovered-requirements.txt
sed -i '/py4j/d' discovered-requirements.txt

# Remove awsglue - install AWSGlueDataplanePython in Step 5 instead
sed -i '/awsglue/d' discovered-requirements.txt

# Use pip-compile to resolve the full dependency tree of the discovered packages,
# constrained to the versions from the temporary venv
pip-compile discovered-requirements.txt -c full-requirements.txt -o final-requirements.txt

echo "=== Final requirements.txt ==="
cat final-requirements.txt

# Deactivate and discard the temporary venv
deactivate
rm -rf temp_venv

對於使用 Python 3.13 的 AWS Glue 6.0，請執行下列命令。


# Create a temporary venv to reproduce the AWS Glue runtime environment
python3.13 -m venv temp_venv
source temp_venv/bin/activate

python3.13 -m pip install --upgrade pip

# Install base container libraries (mirrors what the AWS Glue container provides)
python3.13 -m pip install -r base-requirements.txt

# Install additional Python modules on top (mirrors how AWS Glue installs them at runtime)
python3.13 -m pip install -r additional-requirements.txt

# Freeze the full resolved environment
pip freeze > full-requirements.txt

# Install analysis tools
python3.13 -m pip install pipreqs pip-tools

# Use pipreqs to discover what the script actually imports
# --mode no-pin outputs package names without versions
pipreqs --mode no-pin --savepath discovered-requirements.txt /working_dir/my_glue_script

# Remove packages provided by the Spark runtime
sed -i '/pyspark/d' discovered-requirements.txt
sed -i '/py4j/d' discovered-requirements.txt

# Remove awsglue - install AWSGlueDataplanePython in Step 5 instead
sed -i '/awsglue/d' discovered-requirements.txt

# Use pip-compile to resolve the full dependency tree of the discovered packages,
# constrained to the versions from the temporary venv
pip-compile discovered-requirements.txt -c full-requirements.txt -o final-requirements.txt

echo "=== Final requirements.txt ==="
cat final-requirements.txt

# Deactivate and discard the temporary venv
deactivate
rm -rf temp_venv

注意

檢閱final-requirements.txt以確認其看起來正確。如果您的任務使用動態匯入或條件式匯入， pipreqs可能不會偵測到它們。手動將這些套件新增至檔案。

步驟 5：建置生產 venv

僅使用任務所需的套件來建立最終 venv。然後將其封裝為 tarball。

對於使用 Python 3.11 的 AWS Glue 5.0 和 5.1，請執行下列命令。


python3.11 -m venv pyspark_venv
source pyspark_venv/bin/activate

python3.11 -m pip install --upgrade pip
python3.11 -m pip install -r final-requirements.txt

# Install the AWS Glue Python library that matches your AWS Glue version (see the version
# table in Step 1). Use 5.0.0 for AWS Glue 5.0, or 5.1.0 for AWS Glue 5.1.
python3.11 -m pip install AWSGlueDataplanePython==5.0.0

python3.11 -m pip install venv-pack
venv-pack -f -o pyspark_venv.tar.gz

cp pyspark_venv.tar.gz /output/
exit

對於使用 Python 3.13 的 AWS Glue 6.0，請執行下列命令。


python3.13 -m venv pyspark_venv
source pyspark_venv/bin/activate

python3.13 -m pip install --upgrade pip
python3.13 -m pip install -r final-requirements.txt

# Install the AWS Glue Python library (see version table in Step 1)
python3.13 -m pip install AWSGlueDataplanePython==6.0.0

python3.13 -m pip install venv-pack
venv-pack -f -o pyspark_venv.tar.gz

cp pyspark_venv.tar.gz /output/
exit

步驟 6：上傳至 Amazon S3

將封裝的虛擬環境上傳至 Amazon S3 儲存貯體。


aws s3 cp pyspark_venv.tar.gz s3://amzn-s3-demo-bucket/path/pyspark_venv.tar.gz

步驟 7：更新任務參數

更新您的 AWS Glue 任務組態以使用 --python-virtual-env而非 --additional-python-modules。

移除 --additional-python-modules 參數，並將 --python-virtual-env 參數新增至您上傳的 tarball。


# Before
"--additional-python-modules": "cryptography"

# After (remove --additional-python-modules entirely)
"--python-virtual-env": "s3://amzn-s3-demo-bucket/path/pyspark_venv.tar.gz"

使用 Kiro 自動化遷移

如果您偏好自動化方法，您可以使用 Kiro 網站上Kiro提供的，建置您自己的虛擬環境從命令列執行中所述的遷移。透過Kiro技能，會Kiro分析您的 AWS Glue 任務組態、在中建置虛擬環境Docker，並產生封裝的 tarball。

運作方式

當您要求 Kiro AWS 將 Glue 任務從遷移--additional-python-modules至時--python-virtual-env，Kiro 會執行下列動作：

從請求中擷取 AWS Glue 版本--additional-python-modules、的值和任務指令碼。
從 AWS Glue 文件擷取 Glue AWS 版本的基本容器模組清單。
在工作目錄中建立建置成品，包括 base-requirements.txt、Dockerfile、 additional-requirements.txt和建置指令碼。
為 AWS Glue 相容環境建置Docker映像。
在非互動式容器中執行探索和封裝工作流程。
產生 pyspark_venv.tar.gz、提示您輸入 Amazon S3 目的地，並上傳 tarball。
顯示更新的任務參數。

範例請求

提供您的 AWS Glue 版本、其他 Python 模組和任務指令碼。例如：


I have a Glue 5.1 job with the following:
--additional-python-modules: ephem, awscli

Glue job script:
import awscli
import ephem

Help me migrate to using --python-virtual-env.

取得 Kiro 技能

venv-migration 技能檔案會保存在aws-glue-libs儲存庫中，而不是在本指南中。如需技能檔案和安裝說明，請參閱 GitHub 網站上的 venv-migration 技能。

限制

Kiro Docker 需要在命令列環境中可用。
不會自動偵測指令碼來源中看不到的動態匯入和條件式匯入。檢閱產生的final-requirements.txt檔案，並手動新增任何遺失的套件。
如果您的任務搭配使用私有 pip 索引--index-url，您必須在 Docker 容器中設定該索引的網路存取權。
建置期間的 Pip 衝突可能需要手動解析。如需詳細資訊，請參閱疑難排解。

疑難排解

使用下列各節來解決搭配 Glue 使用 Python AWS 虛擬環境時的常見問題。

解決 pip 版本衝突

pip 版本衝突表示兩個套件需要相同相依性的不相容版本。若要尋找並修正衝突，請執行下列動作：

讀取 pip 錯誤輸出。當解析度完全失敗時，輸出會命名每個衝突的需求，以及引入它的套件。
預覽哪些 pip 無需安裝任何項目即可解析。將 --dry-run --report install-report.json新增至您的安裝命令，如下列範例所示。
```
pip install -r additional-requirements.txt --dry-run --report install-report.json
```
檢查 install-report.json。報告會列出 pip 選取的每個套件，顯示無提示降級。
在非關鍵套件上放寬版本接腳，或移除限制條件。

解決 ModuleNotFoundError

此錯誤表示您的虛擬環境不包含必要的套件。常見原因包括下列項目：

您未包含任務所需的基礎容器程式庫。手動建置的虛擬環境不會繼承來自 Glue AWS 容器的套件。
您的任務使用靜態分析期間pipreqs無法偵測的動態匯入。
您的任務需要PySpark相依於執行器節點。

若要解決此問題，請新增缺少的套件，並重新建置虛擬環境。步驟取決於您的任務使用的方法。

手動建置 venv – 將套件新增至 final-requirements.txt，然後重建虛擬環境並重新上傳。
服務產生的 venv – 將套件新增至 --additional-python-modules。新的模組清單會變更快取金鑰，因此 AWS Glue 會在下次任務執行時建立新的虛擬環境。

減少 venv tarball 大小

如果您的封裝虛擬環境太大，請使用下列方法縮減其大小：

移除指令碼未匯入的不必要套件，例如測試架構和開發工具。
pip install --no-deps 用於您想要手動控制傳輸相依性的套件。
僅包含指令碼直接匯入的套件，並讓 pip-compile解析所需的最低傳輸相依性。

解決平台相容性錯誤

當 venv 中的套件為不同的作業系統或架構建置時，就會發生這些錯誤。若要避免這些錯誤：

一律使用 --platform linux/amd64旗標在Docker容器內建置虛擬環境。
確認車輪平台標籤符合您的目標 Glue AWS 版本。例如， AWS Glue 5.0 和 5.1 需要 manylinux2014_x86_64或相容的平台標籤。
如果沒有，請勿直接在 macOS 或 Windows 上建置虛擬環境Docker。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

Python 程式庫

Python 範例