# AWS Glue에서 Python 가상 환경 사용
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 종속성을 관리하는 다른 방법에 대한 자세한 내용은 [AWS Glue와 함께 Python 라이브러리 사용](aws-glue-programming-python-libraries.md) 섹션를 참조하세요.
## --additional-python-modules와의 주요 차이점
다음 표는 `--additional-python-modules`와 수동 빌드 가상 환경을 비교합니다.
| 기능 | `--additional-python-modules` | `--python-virtual-env` |
| --- | --- | --- |
| 기본 컨테이너 라이브러리(boto3, numpy, pandas 등) | 자동으로 제공됨 | 해당 사항 없음. 필요한 모든 패키지를 venv에 포함해야 합니다. |
| 종속성 해결 | 런타임 시 발생 | 시스템의 빌드 시 발생 |
| 런타임 격리 | 부분적입니다. 패키지는 기본 라이브러리 위에 설치됩니다. | 전체 Python 환경을 완전히 대체합니다. |
**중요**
`--python-virtual-env`로 마이그레이션할 때는 작업에 필요한 모든 Python 패키지를 가상 환경에 포함해야 합니다. 여기에는 boto3, numpy, pandas 등 이전에 AWS Glue 기본 컨테이너에서 사용할 수 있었던 패키지가 포함됩니다. 이러한 패키지는 더 이상 암시적으로 사용할 수 없습니다.
## 접근 방식 선택
다음 표를 사용하여 작업에 적합한 접근 방식을 선택하세요.
| 시나리오 | 권장 접근 방식 |
| --- | --- |
| 빌드 부담이 적고 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](aws-glue-programming-etl-glue-arguments.md#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, pandas, pyarrow와 같은 컨테이너 패키지를 상속합니다. AWS 이어서 Glue는 [--additional-python-modules](aws-glue-programming-etl-glue-arguments.md#additional-python-modules)의 패키지를 pip로 설치하고 가상 환경을 `.tar.gz` 파일로 패키징한 다음 나중에 재사용할 수 있도록 Amazon S3 접두사에 업로드합니다.
+ **이후 실행 시(캐시 적중)** – AWS Glue는 Amazon S3에서 캐시된 `.tar.gz` 파일을 다운로드해 압축을 풀고, 가상 환경을 사용하도록 Spark 드라이버와 실행기를 구성합니다. pip 설치는 수행되지 않습니다.
### 수동 빌드 가상 환경과의 차이점
다음 표에서는 서비스 생성 가상 환경을 수동 빌드 접근 방식과 비교합니다.
| 기능 | 서비스 생성 venv | 수동 빌드 venv |
| --- | --- | --- |
| 빌드 책임 | AWS Glue가 venv를 자동으로 빌드합니다. | Docker에서 직접 venv를 빌드합니다. |
| 컨테이너 패키지 | `--system-site-packages`를 통해 상속됨 | 모든 패키지를 명시적으로 포함해야 합니다. |
| 최초 실행 지연 시간 | pip 설치, 패키징 및 Amazon S3 업로드를 위한 추가 시간 | venv가 사전 빌드되어 있으므로, 없음. |
| 이후 실행 지연 시간 | Amazon S3 다운로드 및 압축 해제를 위한 추가 시간 | Amazon S3 다운로드 및 압축 해제를 위한 추가 시간 |
| 결정성 | 패키지 버전을 고정시키는 것이 좋습니다. | 빌드 시점에 버전이 고정되므로 완전히 결정적입니다. |
| PyPI 액세스 | 첫 실행에서 필요 | venv를 오프라인으로 빌드하므로 필요 없음 |
### 서비스 생성 가상 환경 구성
`--python-virtual-env-storage-prefix` 파라미터는 AWS Glue가 빌드하는 가상 환경을 저장하는 Amazon S3 위치를 `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](aws-glue-programming-etl-glue-arguments.md#python-modules-installer-option) – `--no-deps` 또는 `--index-url`와 같은 옵션을 pip에 전달합니다.
기존 작업에서 캐싱을 활성화하려면 스토리지 접두사 파라미터를 추가합니다. 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/"
```
### AWS Glue가 가상 환경을 캐싱하는 방식
AWS Glue는 작업 구성을 기준으로 캐시에 키를 지정합니다. 해당 구성에는 `--additional-python-modules`의 모듈, `--python-modules-installer-option`의 값, AWS Glue 버전 및 `--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](https://docs.docker.com/get-docker/)를 로컬 시스템에 설치해 AWS Glue 호환 환경에서 가상 환경을 빌드할 수 있도록 합니다.
+ 패키징된 가상 환경을 업로드할 Amazon S3 버킷
+ Amazon S3에 업로드하고 AWS Glue 작업 파라미터를 업데이트할 수 있는 권한으로 구성된 AWS CLI
각 AWS Glue 버전에 대한 Python 버전 및 플랫폼 호환성 세부 정보는 [부록 B: AWS Glue 환경 세부 정보](aws-glue-programming-python-libraries.md#glue-python-libraries-environment-details)를 참조하세요.
### 1단계: 요구 사항 파일 생성
가상 환경에 대한 패키지를 정의하는 두 개의 요구 사항 파일을 생성합니다.
1. GitHub 웹 사이트의 aws-glue-libs 리포지토리에서 AWS Glue 버전에 맞는 `base-requirements.txt`를 다운로드합니다. 이 파일에는 표준 AWS Glue 컨테이너가 제공하는 패키지가 나열됩니다. 이 안내서의 동일한 목록은 [AWS Glue에서 이미 제공되는 Python 모듈](aws-glue-programming-python-libraries.md#glue-modules-provided)을 참조하세요.
+ AWS Glue 5.0 – GitHub 웹 사이트의 [base-requirements.txt](https://raw.githubusercontent.com/awslabs/aws-glue-libs/glue-5.0/base-requirements.txt)
+ AWS Glue 5.1 – GitHub 웹 사이트의 [base-requirements.txt](https://raw.githubusercontent.com/awslabs/aws-glue-libs/glue-5.1/base-requirements.txt)
+ AWS Glue 6.0 – GitHub 웹 사이트의 [base-requirements.txt](https://raw.githubusercontent.com/awslabs/aws-glue-libs/main/base-requirements.txt)
1. `additional-requirements.txt` 생성. 기존 `--additional-python-modules` 파라미터의 패키지를 한 줄에 하나씩 추가합니다. 예제:
```
cryptography
requests-oauthlib
sqlalchemy
```
**중요**
작업이 `GlueContext` 또는 `DynamicFrame`과 같은 AWS Glue Python 라이브러리를 사용하는 경우 PyPI 웹 사이트의 [AWSGlueDataplanePython](https://pypi.org/project/AWSGlueDataplanePython/) 패키지도 포함해야 합니다. 다음 표와 같이 사용 중인 AWS Glue 버전과 일치하는 버전을 사용하세요.
| AWS Glue 버전 | 패키지 버전 |
| --- | --- |
| 5.0 | `AWSGlueDataplanePython==5.0.0` |
| 5.1 | `AWSGlueDataplanePython==5.1.0` |
| 6.0 | `AWSGlueDataplanePython==6.0.0` |
### 2단계: Dockerfile 생성
대상 AWS Glue 버전의 환경과 일치하는 Dockerfile을 생성합니다. 플랫폼 및 Python 버전에 대한 자세한 내용은 [부록 B: AWS Glue 환경 세부 정보](aws-glue-programming-python-libraries.md#glue-python-libraries-environment-details) 섹션을 참조하세요.
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
```
이 명령은 요구 사항 파일과 AWS Glue 작업 스크립트 디렉터리를 마운트합니다. 다음 단계에서는 이 스크립트 디렉터리를 가져오기 분석에 사용합니다.
### 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단계: 작업 파라미터 업데이트
`--additional-python-modules` 대신 `--python-virtual-env`를 사용하도록 AWS Glue 작업 구성을 업데이트합니다.
`--additional-python-modules` 파라미터를 제거하고 업로드된 tarball을 가리키는 `--python-virtual-env` 파라미터를 추가합니다.
```
# 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](https://kiro.dev)를 사용하여 명령줄에서 [자체 가상 환경 빌드](#python-venv-migration-procedure)에 설명된 마이그레이션을 실행할 수 있습니다. Kiro 스킬을 사용하여 Kiro는 AWS Glue 작업 구성을 분석하고, Docker에서 가상 환경을 빌드하고, 패키징된 tarball을 생성합니다.
### 작동 방식
Kiro에 AWS Glue 작업을 `--additional-python-modules`에서 `--python-virtual-env`로 마이그레이션하도록 요청하면 Kiro는 다음을 수행합니다.
1. 요청에서 AWS Glue 버전, `--additional-python-modules` 값 및 작업 스크립트를 추출합니다.
1. AWS Glue 설명서에서 AWS Glue 버전의 기본 컨테이너 모듈 목록을 검색합니다.
1. 작업 디렉터리에 `base-requirements.txt`, `additional-requirements.txt`, Dockerfile 및 빌드 스크립트를 포함한 빌드 아티팩트를 생성합니다.
1. AWS Glue 호환 환경을 위한 Docker 이미지를 빌드합니다.
1. 비대화형 컨테이너에서 검색 및 패키징 워크플로를 실행합니다.
1. `pyspark_venv.tar.gz`를 생성하고, Amazon S3 대상을 입력하라는 메시지를 표시하고, tarball을 업로드합니다.
1. 업데이트된 작업 파라미터를 표시합니다.
### 요청 예
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 스킬](https://github.com/awslabs/aws-glue-libs/blob/main/.kiro/skills/venv-migration/skill.md)을 참조하세요.
### 제한 사항
+ Kiro를 사용하려면 명령줄 환경에서 Docker를 사용할 수 있어야 합니다.
+ 스크립트 소스에 표시되지 않는 동적 가져오기와 조건부 가져오기는 자동으로 감지되지 않습니다. 생성된 `final-requirements.txt` 파일을 검토하고 누락된 패키지를 직접 추가합니다.
+ 작업이 `--index-url`과 함께 프라이빗 pip 인덱스를 사용하는 경우 Docker 컨테이너에서 해당 인덱스에 대한 네트워크 액세스를 구성해야 합니다.
+ 빌드 중 발생하는 pip 충돌은 수동 해결이 필요할 수 있습니다. 자세한 내용은 [문제 해결](#python-venv-troubleshooting) 섹션을 참조하세요.
## 문제 해결
다음 섹션을 참고해 AWS Glue에서 Python 가상 환경을 사용할 때 발생하는 일반적인 문제를 해결하세요.
### pip 버전 충돌 해결
pip 버전 충돌은 두 패키지가 동일한 종속성에 대해 서로 호환되지 않는 버전을 요구하는 상황을 의미합니다. 충돌을 찾아 해결하려면 다음을 수행하세요.
1. pip 오류 출력을 확인합니다. 해결에 완전히 실패하면 출력에 충돌하는 각 요구 사항과 이를 유발한 패키지의 이름이 표시됩니다.
1. 아무것도 설치하지 않고 pip가 해결할 내용을 미리 봅니다. 다음 예제에 표시된 대로 설치 명령에 `--dry-run --report install-report.json`을 추가합니다.
```
pip install -r additional-requirements.txt --dry-run --report install-report.json
```
1. `install-report.json` 검사 보고서에는 pip가 선택한 모든 패키지가 나열되며, 자동 다운그레이드가 표시됩니다.
1. 중요하지 않은 패키지는 버전 고정을 완화하거나 제약 조건을 제거합니다.
### ModuleNotFoundError 해결
이 오류는 가상 환경에 필요한 패키지가 포함되어 있지 않음을 나타냅니다. 일반적인 원인은 다음과 같습니다.
+ 작업에 필요한 기본 컨테이너 라이브러리를 포함하지 않았습니다. 수동 빌드된 가상 환경이 AWS Glue 컨테이너에서 패키지를 상속하지 않습니다.
+ 작업은 정적 분석 중에 pipreqs가 감지할 수 없는 동적 가져오기를 사용합니다.
+ 작업에는 실행기 노드에 대한 PySpark 종속성이 필요합니다.
이 문제를 해결하려면 누락된 패키지를 추가하고 가상 환경을 다시 빌드하세요. 단계는 작업에서 사용하는 접근 방식에 따라 달라집니다.
+ **수동 빌드 venv** – 패키지를 `final-requirements.txt`에 추가한 다음 가상 환경을 다시 빌드하고 업로드합니다.
+ **서비스 생성 venv** – 패키지를 `--additional-python-modules`에 추가합니다. 새 모듈 목록은 캐시 키를 변경하므로 다음 작업 실행 시 AWS Glue가 새 가상 환경을 빌드합니다.
### venv tarball 크기 축소
패키징된 가상 환경이 너무 큰 경우 다음 접근 방식을 사용하여 크기를 줄입니다.
+ 테스트 프레임워크 및 개발 도구와 같이 스크립트가 가져오지 않는 불필요한 패키지를 제거합니다.
+ 전이적 종속성을 수동으로 제어하려는 패키지에 `pip install --no-deps`를 사용합니다.
+ 스크립트가 직접 가져오는 패키지만 포함하고 pip-compile이 최소 필수 전이적 종속성을 확인하도록 합니다.
### 플랫폼 호환성 오류 해결
이러한 오류는 venv의 패키지가 다른 운영 체제 또는 아키텍처용으로 빌드되었을 때 발생합니다. 해당 오류를 방지하려면 다음을 참고하세요.
+ 가상 환경은 항상 Docker 컨테이너 내부에 `--platform linux/amd64` 플래그를 사용하여 빌드합니다.
+ 휠 플랫폼 태그가 대상 AWS Glue 버전과 일치하는지 확인합니다. 예를 들어 AWS Glue 5.0 및 5.1에는 `manylinux2014_x86_64` 또는 호환되는 플랫폼 태그가 필요합니다.
+ Docker를 사용하지 않고 macOS 또는 Windows에서 직접 가상 환경을 빌드하지 마세요.