

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Utilisation d'environnements virtuels Python avec AWS Glue
<a name="aws-glue-programming-python-virtual-environments"></a>

 À partir de AWS Glue 5.0, vous pouvez exécuter vos tâches ETL dans un environnement virtuel Python (venv). Les environnements virtuels suppriment la résolution des dépendances d'exécution de vos tâches, garantissent que chaque exécution utilise les mêmes packages et évitent les défaillances causées par les modifications apportées en amont aux packages. 

 AWS Glue propose deux manières d'utiliser un environnement virtuel : 
+ **Service-generated environnement virtuel ** — Disponible dans AWS Glue 6.0 et versions ultérieures. Vous ajoutez le `--python-virtual-env-storage-prefix` paramètre, puis AWS Glue crée l'environnement virtuel pour vous et le met en cache dans Amazon S3 pour les exécutions ultérieures des tâches. Aucune construction locale n'est requise.
+ **Environnement virtuel créé manuellement ** — Disponible dans AWS Glue 5.0 et versions ultérieures. Vous créez l'environnement virtuel sur votre machine locale ou dans un CI/CD pipeline, vous le chargez sur Amazon S3 et vous le référencez à l'aide du `--python-virtual-env` paramètre.

 Cette rubrique décrit comment migrer les tâches qui utilisent l'une ou `--additional-python-modules` l'autre approche. Pour plus d'informations sur les autres méthodes de gestion des dépendances Python, consultez[Utilisation des bibliothèques Python avec AWS Glue](aws-glue-programming-python-libraries.md). 

## Principales différences par rapport à --additional-python-modules
<a name="python-venv-key-differences"></a>

Le tableau suivant présente une comparaison `--additional-python-modules` avec un environnement virtuel créé manuellement.


| Fonctionnalité | `--additional-python-modules` | `--python-virtual-env` | 
| --- | --- | --- | 
| Bibliothèques de conteneurs de base (boto3numpypandas,, et autres) | Disponible automatiquement | Indisponible. Vous devez inclure tous les packages requis dans le venv. | 
| Résolution des dépendances | Se produit au moment de l'exécution | Se produit au moment de la construction sur votre machine | 
| Isolation de l'exécution | Partiel. Les packages s'installent au-dessus des bibliothèques de base. | Plein Remplace entièrement l'environnement Python. | 

**Important**  
Lorsque vous migrez vers`--python-virtual-env`, vous devez inclure tous les packages Python dont votre travail a besoin dans l'environnement virtuel. Cela inclut les packages qui étaient auparavant disponibles dans le conteneur de base de AWS Glueboto3, tels quenumpy, etpandas. Ces packages ne sont plus implicitement disponibles.

## Choix d’une approche
<a name="python-venv-choosing-an-approach"></a>

Utilisez le tableau suivant pour choisir l'approche qui convient le mieux à votre travail.


| Scénario | Approche recommandée | 
| --- | --- | 
| Des tâches simples avec quelques packages pip, pour lesquelles vous ne voulez pas de frais de construction | Service-generated venv (ajouter`--python-virtual-env-storage-prefix`). Nécessite AWS Glue 6.0 ou version ultérieure. | 
| Des arbres de dépendance complexes, une reproductibilité totale ou un CI/CD pipeline qui construit le venv | Venv (`--python-virtual-env`) construit manuellement. Nécessite AWS Glue 5.0 ou version ultérieure. | 
| Migrer depuis `--additional-python-modules` avec un minimum de modifications | Service-generated venv (ajouter`--python-virtual-env-storage-prefix`). Nécessite AWS Glue 6.0 ou version ultérieure. Sur AWS Glue 5.0 et 5.1, utilisez plutôt un environnement virtuel créé manuellement. | 
| PyPIIndex privé avec packages personnalisés | L'une ou l'autre approche. Le venv généré par le service nécessite AWS Glue 6.0 ou version ultérieure et fonctionne avec. [--python-modules-installer-option](aws-glue-programming-etl-glue-arguments.md#python-modules-installer-option) | 

## Utilisation d'un environnement virtuel généré par un service avec la mise en cache d'Amazon S3
<a name="python-venv-service-generated"></a>

À partir de AWS Glue 6.0, vous pouvez utiliser le `--python-virtual-env-storage-prefix` paramètre pour que AWS Glue crée l'environnement virtuel et le mette en cache dans Amazon S3. Cette approche combine la simplicité et les avantages `--additional-python-modules` en termes de performances d'un environnement virtuel mis en cache.

### Comment ça marche
<a name="python-venv-service-generated-how-it-works"></a>

Lorsque vous fournissez`--python-virtual-env-storage-prefix`, AWS Glue effectue les opérations suivantes :
+ **Lors de la première exécution (échec du cache) ** : AWS Glue crée un environnement virtuel avec`--system-site-packages`, qui hérite des packages de conteneurs tels que numpypandas, etpyarrow. AWS Glue installe ensuite les packages à partir de [--additional-python-modules](aws-glue-programming-etl-glue-arguments.md#additional-python-modules) pip, empaquette l'environnement virtuel sous forme de `.tar.gz` fichier et le télécharge dans votre préfixe Amazon S3 pour une réutilisation ultérieure.
+ **Lors d'exécutions ultérieures (accès au cache) ** : AWS Glue télécharge le `.tar.gz` fichier mis en cache depuis Amazon S3, l'extrait et configure le pilote et les exécuteurs Spark pour utiliser l'environnement virtuel. Aucune installation de pip n'a lieu.

### Différences par rapport à un environnement virtuel créé manuellement
<a name="python-venv-service-generated-comparison"></a>

Le tableau suivant compare l'environnement virtuel généré par le service à l'approche créée manuellement.


| Fonctionnalité | Service-generated venv | Venv construit manuellement | 
| --- | --- | --- | 
| Renforcer la responsabilité | AWS La colle crée le venv automatiquement | Vous construisez le venv dans Docker | 
| Emballages de conteneurs | Hérité par `--system-site-packages` | Vous devez inclure tous les packages de manière explicite | 
| First-run latence | Temps supplémentaire pour l'installation de pip, l'empaquetage et le chargement d'Amazon S3 | Aucun, car le venv est pré-construit | 
| Later-run latence | Temps supplémentaire pour le téléchargement et l'extraction d'Amazon S3 | Temps supplémentaire pour le téléchargement et l'extraction d'Amazon S3 | 
| Déterminisme | Nous vous recommandons d'épingler les versions des paquets | Entièrement déterministe, car les versions sont verrouillées au moment de la construction | 
| Accès à PyPI | Obligatoire lors de la première course | Non obligatoire, car le venv est créé hors ligne | 

### Configuration d'un environnement virtuel généré par un service
<a name="python-venv-service-generated-usage"></a>

Le `--python-virtual-env-storage-prefix` paramètre spécifie l'emplacement Amazon S3 où AWS Glue stocke l'environnement virtuel qu'il crée, dans le formulaire`s3://{{path}}/`. AWS Glue met en cache l'environnement virtuel à ce préfixe lors de la première exécution de la tâche et le réutilise lors des exécutions suivantes.

Pour activer un environnement virtuel généré par un service, ajoutez le `--python-virtual-env-storage-prefix` paramètre à votre tâche et conservez votre paramètre existant`--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/"
```

Vous pouvez également utiliser les paramètres facultatifs suivants :
+ `--python-virtual-env-version`— Un identifiant de version pour l'environnement virtuel mis en cache. Modifiez cette valeur pour invalider le cache et forcer AWS Glue à reconstruire l'environnement virtuel. La valeur est une chaîne. Vous pouvez donc utiliser le schéma de version adapté à votre flux de travail, tel qu'un numéro d'incrémentation, une date ou un identifiant de génération. La valeur par défaut est `0`.
+ [--python-modules-installer-option](aws-glue-programming-etl-glue-arguments.md#python-modules-installer-option)— Transmettez des options à pip, telles que `--no-deps` ou`--index-url`.

Pour activer la mise en cache pour une tâche existante, ajoutez le paramètre de préfixe de stockage. La première exécution prend plus de temps car AWS Glue crée et télécharge l'environnement virtuel, mais les exécutions ultérieures utilisent l'environnement virtuel mis en cache et n'effectuent aucune résolution 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/"
```

### Comment ? AWS Glue met en cache l'environnement virtuel
<a name="python-venv-service-generated-caching"></a>

AWS Glue verrouille le cache en fonction de la configuration de votre tâche. La configuration inclut les modules de`--additional-python-modules`, la valeur de`--python-modules-installer-option`, la version de AWS Glue et la valeur de`--python-virtual-env-version`.

Une configuration inchangée entraîne un accès au cache. Si vous modifiez l'une de ces valeurs, AWS Glue crée un nouvel environnement virtuel et crée une nouvelle entrée de cache.

AWS Glue stocke chaque environnement virtuel mis en cache sous une clé distincte dans votre préfixe de stockage. Les tâches qui utilisent les mêmes modules et options d'installation partagent la même entrée de cache.

### Limitations
<a name="python-venv-service-generated-limitations"></a>
+ Nécessite AWS Glue 6.0 ou version ultérieure.
+ La première exécution nécessite l'accès à PyPI ou à votre index privé pour résoudre les dépendances.
+ Les packages de conteneurs tels que numpy et pandas sont hérités mais ne sont pas épinglés dans la version. Si votre travail nécessite des versions exactes des packages de conteneurs, utilisez-les `--python-virtual-env` plutôt.
+ Le cache est défini par configuration. La modification d'un module ou d'une version crée une nouvelle entrée de cache, et les entrées précédentes restent dans Amazon S3 jusqu'à ce que vous les supprimiez.

## Création de votre propre environnement virtuel
<a name="python-venv-migration-procedure"></a>

Dans AWS Glue 5.0 et versions ultérieures, vous pouvez créer vous-même un environnement virtuel et le référencer à l'aide du `--python-virtual-env` paramètre. Utilisez cette approche lorsque vous avez besoin d'une reproductibilité totale, de versions exactes de packages de conteneurs ou d'une version qui s'exécute dans un pipeline. CI/CD 

### Conditions préalables
<a name="python-venv-prerequisites"></a>

Avant de commencer, assurez-vous de disposer des éléments suivants :
+ [Docker](https://docs.docker.com/get-docker/)depuis le Docker site Web, installé sur votre machine locale, afin que vous puissiez créer l'environnement virtuel dans un AWS Glue-compatible environnement
+ Un compartiment Amazon S3 pour télécharger l'environnement virtuel packagé
+ L' AWS interface de ligne de commande est configurée avec les autorisations nécessaires pour charger sur Amazon S3 et mettre à jour les paramètres des tâches AWS Glue

Pour plus de détails sur la compatibilité entre les versions de Python et les plates-formes pour chaque version de AWS Glue, consultez[Annexe B : AWS Détails de l'environnement Glue](aws-glue-programming-python-libraries.md#glue-python-libraries-environment-details).

### Étape 1 : Créez vos fichiers de besoins
<a name="python-venv-step-1"></a>

Créez deux fichiers d'exigences qui définissent les packages de votre environnement virtuel.

1. Téléchargez `base-requirements.txt` votre version de AWS Glue depuis le aws-glue-libs référentiel du GitHub site Web. Ce fichier répertorie les packages fournis par le conteneur AWS Glue standard. Pour obtenir la même liste dans ce guide, consultez[Modules Python déjà fournis dans AWS Glue](aws-glue-programming-python-libraries.md#glue-modules-provided).
   + AWS Glue 5.0 — [ base-requirements.txt ](https://raw.githubusercontent.com/awslabs/aws-glue-libs/glue-5.0/base-requirements.txt) sur le GitHub site
   + AWS Glue 5.1 — [ base-requirements.txt ](https://raw.githubusercontent.com/awslabs/aws-glue-libs/glue-5.1/base-requirements.txt) sur le GitHub site
   + AWS Glue 6.0 — [ base-requirements.txt ](https://raw.githubusercontent.com/awslabs/aws-glue-libs/main/base-requirements.txt) sur le GitHub site

1. Créer `additional-requirements.txt`. Ajoutez les packages à partir de votre `--additional-python-modules` paramètre existant, un par ligne. Par exemple :

   ```
   cryptography
   requests-oauthlib
   sqlalchemy
   ```

**Important**  
Si votre travail utilise la bibliothèque Python de AWS Glue, telle que `GlueContext` ou`DynamicFrame`, vous devez également inclure le [ AWSGlueDataplanePython ](https://pypi.org/project/AWSGlueDataplanePython/) package depuis le PyPI site Web. Utilisez la version qui correspond à votre version de AWS Glue, comme indiqué dans le tableau suivant.


| AWS Version à colle | Version du package | 
| --- | --- | 
| 5.0 | `AWSGlueDataplanePython==5.0.0` | 
| 5.1 | `AWSGlueDataplanePython==5.1.0` | 
| 6.0 | `AWSGlueDataplanePython==6.0.0` | 

### Étape 2 : créer un Dockerfile
<a name="python-venv-step-2"></a>

Créez un environnement Dockerfile qui correspond à l'environnement de votre version cible de AWS Glue. Pour plus de détails sur la plate-forme et la version de Python, consultez[Annexe B : AWS Détails de l'environnement Glue](aws-glue-programming-python-libraries.md#glue-python-libraries-environment-details).

AWS Glue 5.0 et 5.1 utilisent Python 3.11 sur Amazon Linux 2023.

```
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 utilise Python 3.13 sur Amazon Linux 2023.

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

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

WORKDIR /build
```

### Étape 3 : Construire et démarrer le conteneur
<a name="python-venv-step-3"></a>

Créez l'Dockerimage. Démarrez ensuite un conteneur avec vos fichiers d'exigences et votre script de tâche monté.

```
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
```

Cette commande monte vos fichiers d'exigences et votre répertoire de scripts de tâches AWS Glue. L'étape suivante utilise le répertoire de scripts pour l'analyse des importations.

### Étape 4 : Créez un venv temporaire et découvrez les packages requis
<a name="python-venv-step-4"></a>

À l'intérieur du conteneur, créez un venv temporaire qui reflète le runtime de AWS Glue. Utilisez ensuite l'analyse statique pour trouver l'ensemble minimal de packages dont votre travail a besoin.

Pour AWS Glue 5.0 et 5.1, qui utilisent Python 3.11, exécutez les commandes suivantes.

```
# 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
```

Pour AWS Glue 6.0, qui utilise Python 3.13, exécutez les commandes suivantes.

```
# 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
```

**Note**  
Passez `final-requirements.txt` en revue pour vérifier qu'il semble correct. Si votre tâche utilise des importations dynamiques ou conditionnelles, il est possible qu'elles ne pipreqs soient pas détectées. Ajoutez ces packages au fichier manuellement.

### Étape 5 : Création de l'usine de production
<a name="python-venv-step-5"></a>

Créez le venv final avec uniquement les packages dont votre travail a besoin. Emballez-le ensuite sous forme d'archive tar.

Pour AWS Glue 5.0 et 5.1, qui utilisent Python 3.11, exécutez les commandes suivantes.

```
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
```

Pour AWS Glue 6.0, qui utilise Python 3.13, exécutez les commandes suivantes.

```
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
```

### Étape 6 : Chargement sur Amazon S3
<a name="python-venv-step-6"></a>

Téléchargez l'environnement virtuel packagé dans votre compartiment Amazon S3.

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

### Étape 7 : Mettre à jour les paramètres de la tâche
<a name="python-venv-step-7"></a>

Mettez à jour la configuration de votre tâche AWS Glue pour l'utiliser à la `--python-virtual-env` place de`--additional-python-modules`.

Supprimez le `--additional-python-modules` paramètre et ajoutez le `--python-virtual-env` paramètre pointant vers votre archive tar téléchargée.

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

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

## Automatiser la migration avec Kiro
<a name="python-venv-kiro-migration"></a>

Si vous préférez une approche automatisée, vous pouvez utiliser [Kiro](https://kiro.dev), disponible sur le Kiro site Web, pour exécuter la migration décrite dans [Création de votre propre environnement virtuel](#python-venv-migration-procedure) depuis la ligne de commande. À l'aide d'une Kiro compétence, il Kiro analyse la configuration de vos tâches AWS Glue, crée l'Dockerenvironnement virtuel et produit l'archive tar packagée.

### Comment ça marche
<a name="python-venv-kiro-how-it-works"></a>

Lorsque vous demandez à Kiro de migrer votre tâche AWS Glue depuis `--additional-python-modules` vers`--python-virtual-env`, Kiro effectue les opérations suivantes :

1. Extrait la version de AWS Glue, la valeur de `--additional-python-modules` et votre script de tâche à partir de votre demande.

1. Extrait la liste des modules de conteneurs de base pour votre version de AWS Glue à partir de la documentation de AWS Glue.

1. Crée les artefacts de génération dans un répertoire de travail`base-requirements.txt`, comprenant`additional-requirements.txt`,Dockerfile, a et un script de génération.

1. Construit l'Dockerimage d'un AWS Glue-compatible environnement.

1. Exécute le flux de travail de découverte et d'empaquetage dans un conteneur non interactif.

1. Produit`pyspark_venv.tar.gz`, vous invite à indiquer une destination Amazon S3 et télécharge l'archive tar.

1. Affiche les paramètres de tâche mis à jour.

### Exemple de demande
<a name="python-venv-kiro-example"></a>

Indiquez votre version de AWS Glue, vos modules Python supplémentaires et votre script de travail. Par exemple :

```
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.
```

### Acquérir la compétence Kiro
<a name="python-venv-kiro-skill"></a>

Le dossier de `venv-migration` compétences est conservé dans le aws-glue-libs référentiel plutôt que dans ce guide. Pour le fichier de compétences et les instructions d'installation, consultez la compétence [ venv-migration ](https://github.com/awslabs/aws-glue-libs/blob/main/.kiro/skills/venv-migration/skill.md) sur le GitHub site Web.

### Limitations
<a name="python-venv-kiro-limitations"></a>
+ Kiro doit Docker être disponible dans l'environnement de ligne de commande.
+ Les importations dynamiques et conditionnelles qui ne sont pas visibles dans la source de votre script ne sont pas détectées automatiquement. Passez en revue le `final-requirements.txt` fichier généré et ajoutez les packages manquants manuellement.
+ Si votre tâche utilise un index pip privé avec`--index-url`, vous devez configurer l'accès réseau à cet index dans le Docker conteneur.
+ Les conflits de pip pendant la génération peuvent nécessiter une résolution manuelle. Pour de plus amples informations, veuillez consulter [Résolution des problèmes](#python-venv-troubleshooting).

## Résolution des problèmes
<a name="python-venv-troubleshooting"></a>

Consultez les sections suivantes pour résoudre les problèmes courants liés à l'utilisation d'environnements virtuels Python avec AWS Glue.

### Résolution des conflits de version de pip
<a name="python-venv-troubleshooting-pip-conflicts"></a>

Un conflit de version pip signifie que deux packages nécessitent des versions incompatibles de la même dépendance. Pour rechercher et résoudre le conflit, procédez comme suit :

1. Lisez la sortie d'erreur pip. Lorsque la résolution échoue purement et simplement, la sortie nomme chaque exigence en conflit et le package qui l'a introduite.

1. Prévisualisez ce que pip résoudrait sans rien installer. Ajoutez `--dry-run --report install-report.json` à votre commande d'installation, comme dans l'exemple suivant.

   ```
   pip install -r additional-requirements.txt --dry-run --report install-report.json
   ```

1. Inspectez`install-report.json`. Le rapport répertorie tous les packages sélectionnés par pip, ce qui révèle des rétrogradations silencieuses.

1. Assouplissez les épingles de version sur les packages non critiques ou supprimez les contraintes.

### Résoudre ModuleNotFoundError
<a name="python-venv-troubleshooting-module-not-found"></a>

Cette erreur indique que votre environnement virtuel n'inclut aucun package requis. Les causes courantes sont les suivantes :
+ Vous n'avez pas inclus de bibliothèque de conteneurs de base requise pour votre travail. Un environnement virtuel créé manuellement n'hérite pas des packages du conteneur AWS Glue.
+ Votre tâche utilise une importation dynamique qui n'a pas pipreqs pu être détectée lors de l'analyse statique.
+ Votre travail nécessite de PySpark dépendre des nœuds exécuteurs.

Pour résoudre ce problème, ajoutez le package manquant et reconstruisez l'environnement virtuel. Les étapes dépendent de l'approche utilisée pour votre travail.
+ **Venv créé manuellement ** : ajoutez le package à`final-requirements.txt`, reconstruisez l'environnement virtuel et téléchargez-le à nouveau.
+ **Service-generated venv ** — Ajoutez le package à. `--additional-python-modules` La nouvelle liste de modules modifie la clé de cache, de sorte que AWS Glue crée un nouvel environnement virtuel lors de la prochaine exécution de la tâche.

### Réduire la taille de l'archive venv
<a name="python-venv-troubleshooting-large-tarball"></a>

Si votre environnement virtuel packagé est trop volumineux, réduisez-le en appliquant les méthodes suivantes :
+ Supprimez les packages inutiles que votre script n'importe pas, tels que les frameworks de test et les outils de développement.
+ `pip install --no-deps`À utiliser pour les packages pour lesquels vous souhaitez contrôler manuellement les dépendances transitives.
+ Incluez uniquement les packages que votre script importe directement et pip-compile résolvez les dépendances transitives minimales requises.

### Résolution des erreurs de compatibilité des plateformes
<a name="python-venv-troubleshooting-platform-errors"></a>

Ces erreurs se produisent lorsque les packages du venv ont été créés pour un système d'exploitation ou une architecture différent. Pour éviter ces erreurs :
+ Créez toujours l'environnement virtuel à l'intérieur d'un Docker conteneur à l'aide du `--platform linux/amd64` drapeau.
+ Vérifiez que les étiquettes de plate-forme de roue correspondent à votre version cible AWS de Glue. Par exemple, AWS Glue 5.0 et 5.1 nécessitent des balises de plateforme `manylinux2014_x86_64` ou sont compatibles.
+ Ne créez pas l'environnement virtuel directement sur macOS ou Windows sansDocker.