- À propos du dossier venv et de Git
- Pourquoi ne faut-il généralement pas ajouter venv dans Git ?
- Ignorer venv avec le fichier .gitignore
- Vérifier que Git ignore bien l'environnement virtuel
- Que faut-il enregistrer à la place du dossier venv ?
- Recréer l'environnement virtuel après un clone Git
- Retirer venv de Git s'il a déjà été ajouté
- Organiser correctement un projet Python avec Git et venv
- Bonnes pratiques pour partager un projet Python avec Git
- À retenir !
1. À propos du dossier venv et de Git
Lorsqu'un projet Python utilise un environnement virtuel, un dossier nommé venv, .venv, env ou portant un autre nom est créé. Ce dossier contient notamment un interpréteur Python associé à l'environnement, les packages installés et différents fichiers nécessaires à son fonctionnement.
Lorsqu'on commence à utiliser Git pour versionner le projet, une question importante apparaît : faut-il ajouter ce dossier à Git ? Dans la grande majorité des projets, la réponse est non. L'environnement virtuel est généralement considéré comme un élément local et recréable, contrairement au code source et aux fichiers décrivant les dépendances.
Commençons par créer un environnement virtuel nommé .venv afin d'observer ce qui est généré dans notre projet.
1 | python -m venv .venv |
Sortie :
1 2 | Aucun message n'est généralement affiché. Le dossier .venv est créé dans le projet. |
Sous Windows, nous pouvons afficher une partie du contenu de l'environnement avec la commande suivante.
1 | dir .venv |
Sortie possible :
1 2 3 4 | Include Lib Scripts pyvenv.cfg |
Ce dossier n'est donc pas simplement un fichier de configuration : il contient tout un environnement d'exécution local qu'il est généralement inutile d'enregistrer dans le dépôt Git.
2. Pourquoi ne faut-il généralement pas ajouter venv dans Git ?
Un dossier venv peut contenir un grand nombre de fichiers provenant de Python et des packages installés. Les ajouter à Git alourdit inutilement le dépôt et peut produire des milliers de fichiers suivis alors que ces éléments peuvent être recréés automatiquement.
Nous pouvons par exemple installer requests dans notre environnement afin de constater que de nouveaux packages sont ajoutés au dossier de l'environnement.
1 | .venv\Scripts\python.exe -m pip install requests |
Sortie possible :
1 2 3 | Collecting requests ... Successfully installed certifi-... charset-normalizer-... idna-... requests-... urllib3-... |
Ces bibliothèques se retrouvent dans le dossier site-packages de l'environnement. Il n'est normalement pas nécessaire de les recopier dans Git, car pip peut les télécharger et les réinstaller à partir d'une description des dépendances.
Un environnement virtuel contient également des informations liées à l'installation Python et au système sur lequel il a été créé. Nous pouvons par exemple consulter son fichier pyvenv.cfg.
1 | type .venv\pyvenv.cfg |
Sortie possible :
1 2 3 4 | home = C:\Python314 include-system-site-packages = false version = 3.14.x ... |
Le chemin et le contenu exact varient selon la machine et la version de Python. Un environnement créé sous Windows n'est donc pas un moyen approprié de distribuer un environnement destiné à être utilisé tel quel sous Linux ou macOS.
En résumé, conserver venv dans Git pose plusieurs problèmes : taille inutile du dépôt, grand nombre de fichiers, informations dépendantes de la machine et duplication de packages qui peuvent être réinstallés.
3. Ignorer venv avec le fichier .gitignore
Git permet d'indiquer les fichiers et dossiers qui ne doivent pas être suivis grâce au fichier .gitignore. Pour un projet dont l'environnement virtuel s'appelle .venv, il suffit généralement d'ajouter ce dossier au fichier .gitignore.
Le contenu minimal suivant demande à Git d'ignorer le dossier .venv placé à la racine ou correspondant à ce motif dans le projet.
1 | .venv/ |
Sortie :
1 | Le dossier .venv correspondant est ignoré par Git s'il n'est pas déjà suivi. |
Si nous utilisons plutôt le nom venv, nous pouvons également l'ajouter au fichier .gitignore.
1 | venv/ |
Sortie :
1 | Le dossier venv correspondant est ignoré par Git s'il n'est pas déjà suivi. |
Un projet peut également prévoir plusieurs noms courants d'environnements virtuels. Le fichier .gitignore peut alors contenir les règles suivantes.
1 2 3 4 | .venv/ venv/ env/ ENV/ |
Sortie :
1 | Git ignore les dossiers correspondant à ces règles lorsqu'ils ne sont pas déjà suivis. |
Il est préférable d'ajouter la règle concernant l'environnement virtuel dès la création du dépôt, avant d'exécuter git add sur l'ensemble du projet.
4. Vérifier que Git ignore bien l'environnement virtuel
Après avoir configuré .gitignore, il est important de vérifier que Git ne propose pas les fichiers de l'environnement virtuel parmi les fichiers à enregistrer.
La commande git status affiche l'état du dépôt et permet de voir les fichiers non suivis ou modifiés.
1 | git status |
Sortie possible :
1 2 3 4 5 6 7 | On branch main Untracked files: .gitignore main.py requirements.txt nothing added to commit but untracked files present |
Si .venv n'apparaît pas dans cette liste alors qu'il existe dans le projet, la règle d'exclusion fonctionne probablement comme prévu.
Git fournit également la commande git check-ignore, très pratique pour savoir quelle règle ignore précisément un fichier. Nous pouvons tester un fichier de l'environnement sous Windows.
1 | git check-ignore -v .venv/Scripts/python.exe |
Sortie possible :
1 | .gitignore:1:.venv/ .venv/Scripts/python.exe |
Cette sortie indique que la règle présente à la première ligne du fichier .gitignore est responsable de l'exclusion du fichier.
5. Que faut-il enregistrer à la place du dossier venv ?
Ne pas enregistrer le dossier venv ne signifie pas qu'il faut perdre les informations nécessaires à la reconstruction du projet. Il faut versionner le code source ainsi que les fichiers décrivant les dépendances.
Dans un projet utilisant venv et pip, nous pouvons générer un fichier requirements.txt contenant les distributions installées dans l'environnement.
1 | python -m pip freeze > requirements.txt |
Sortie :
1 2 | Aucun message n'est normalement affiché. Le fichier requirements.txt est créé ou remplacé. |
Nous pouvons ensuite afficher son contenu sous Windows.
1 | type requirements.txt |
Sortie possible :
1 2 3 4 5 | certifi==... charset-normalizer==... idna==... requests==... urllib3==... |
Le fichier requirements.txt est beaucoup plus léger que le dossier .venv et permet de reconstruire les dépendances du projet.
Nous pouvons maintenant demander à Git d'ajouter le code source, requirements.txt et .gitignore sans ajouter l'environnement virtuel.
1 | git add main.py requirements.txt .gitignore |
Sortie :
1 2 | Aucun message n'est généralement affiché. Les fichiers sont placés dans la zone de préparation de Git. |
Cette approche permet de versionner ce qui est nécessaire pour reproduire le projet plutôt que de stocker directement l'environnement local.
6. Recréer l'environnement virtuel après un clone Git
L'un des principaux avantages de cette organisation est qu'un développeur peut récupérer le projet avec git clone, créer son propre environnement virtuel et réinstaller les dépendances. Il n'a donc pas besoin de recevoir le dossier .venv créé sur l'ordinateur d'un autre développeur.
Après avoir récupéré un dépôt, nous pouvons nous placer dans le dossier du projet puis créer un nouvel environnement.
1 | python -m venv .venv |
Sortie :
1 2 | Aucun message n'est généralement affiché. Un nouvel environnement .venv est créé localement. |
Sous Windows avec CMD, nous activons ensuite ce nouvel environnement.
1 | .venv\Scripts\activate.bat |
Sortie possible :
1 | (.venv) C:\mon_projet> |
Les dépendances enregistrées dans requirements.txt peuvent alors être réinstallées.
1 | python -m pip install -r requirements.txt |
Sortie possible :
1 2 3 4 5 6 7 | Collecting certifi==... Collecting charset-normalizer==... Collecting idna==... Collecting requests==... Collecting urllib3==... ... Successfully installed ... |
Nous pouvons finalement contrôler la cohérence des dépendances installées avec pip check.
1 | python -m pip check |
Sortie possible :
1 | No broken requirements found. |
Chaque développeur possède ainsi son propre environnement local tout en travaillant sur le même code versionné.
7. Retirer venv de Git s'il a déjà été ajouté
Une situation fréquente consiste à créer le dépôt, exécuter git add ., puis constater que le dossier venv a déjà été ajouté à l'index Git. Ajouter ensuite venv dans .gitignore ne suffit pas à arrêter le suivi des fichiers déjà enregistrés par Git.
Nous pouvons vérifier si des fichiers du dossier .venv sont suivis avec la commande suivante.
1 | git ls-files .venv |
Sortie possible :
1 2 3 4 5 6 | .venv/Lib/site-packages/... .venv/Scripts/activate.bat .venv/Scripts/Activate.ps1 .venv/Scripts/python.exe .venv/pyvenv.cfg ... |
Si ces fichiers apparaissent, le dossier est déjà suivi. Après avoir ajouté .venv/ dans .gitignore, nous pouvons le retirer de l'index Git tout en conservant les fichiers sur l'ordinateur grâce à l'option --cached.
1 | git rm -r --cached .venv |
Sortie possible :
1 2 3 4 | rm '.venv/...' rm '.venv/...' rm '.venv/...' ... |
Cette commande retire les fichiers de l'index Git, mais l'option --cached permet de conserver le dossier local sur le disque.
Nous pouvons ensuite vérifier l'état du dépôt.
1 | git status |
Sortie possible :
1 2 3 | Changes to be committed: deleted: .venv/... modified: .gitignore |
Il faut ensuite enregistrer cette modification dans un commit pour que le dépôt cesse de suivre l'environnement.
1 2 | git add .gitignore git commit -m "Ignore l'environnement virtuel" |
Sortie possible :
1 2 3 | [main ...] Ignore l'environnement virtuel ... files changed ... |
Attention : cette opération empêche le suivi futur du dossier, mais elle ne supprime pas automatiquement les anciennes copies de ces fichiers présentes dans l'historique Git. Si des informations sensibles ont été commitées par erreur, une procédure spécifique de nettoyage de l'historique et de rotation des secrets peut être nécessaire.
8. Organiser correctement un projet Python avec Git et venv
Une bonne organisation permet de distinguer clairement les fichiers du projet, qui doivent être versionnés, et les fichiers locaux ou générés, qui doivent être ignorés.
Une structure simple peut par exemple être organisée de la manière suivante.
1 2 3 4 5 6 7 8 9 | mon_projet/ ├── .git/ ├── .gitignore ├── .venv/ ├── main.py ├── requirements.txt ├── README.md └── src/ └── application.py |
Sortie :
1 2 3 4 5 6 | .gitignore : à versionner .venv/ : à ignorer main.py : à versionner requirements.txt : à versionner README.md : à versionner src/ : à versionner |
Le fichier .gitignore peut également exclure d'autres fichiers Python générés automatiquement, comme les dossiers __pycache__ et les fichiers compilés .pyc.
1 2 3 4 | .venv/ venv/ __pycache__/ *.pyc |
Sortie :
1 2 | Git ignore les environnements virtuels correspondants, les dossiers __pycache__ et les fichiers .pyc. |
Nous pouvons vérifier les fichiers qui seront réellement suivis avant de réaliser un commit.
1 | git status |
Sortie possible :
1 2 3 4 5 6 7 | On branch main Changes to be committed: new file: .gitignore new file: README.md new file: main.py new file: requirements.txt new file: src/application.py |
L'environnement .venv n'apparaît pas : il reste local à la machine de développement.
9. Bonnes pratiques pour partager un projet Python avec Git
Pour qu'un projet Python soit facilement récupérable par un autre développeur, il est utile de fournir non seulement le code source et les dépendances, mais également des instructions expliquant comment recréer l'environnement.
Le fichier README.md peut par exemple indiquer les principales commandes nécessaires après le clonage du dépôt.
1 2 3 4 | python -m venv .venv .venv\Scripts\activate.bat python -m pip install -r requirements.txt python main.py |
Sortie possible :
1 2 3 | (.venv) C:\mon_projet> ... Application démarrée. |
Sous Linux ou macOS, seule la commande d'activation change principalement dans ce workflow.
1 2 3 4 | python3 -m venv .venv source .venv/bin/activate python -m pip install -r requirements.txt python main.py |
Sortie possible :
1 2 3 | (.venv) utilisateur@ordinateur:~/mon_projet$ ... Application démarrée. |
Avant chaque commit, git status constitue une vérification simple mais très utile pour éviter d'ajouter accidentellement des fichiers locaux.
1 | git status |
Sortie possible :
1 2 | On branch main nothing to commit, working tree clean |
Pour un projet utilisant Poetry, Pipenv ou d'autres gestionnaires, le principe reste comparable : on versionne les fichiers de configuration et de verrouillage nécessaires au projet plutôt que le dossier contenant l'environnement virtuel lui-même.
10. À retenir !
Dans la grande majorité des projets, il ne faut pas ajouter le dossier venv dans Git. Un environnement virtuel Python est un élément local et recréable qui peut contenir de nombreux fichiers et des informations dépendantes de la machine. Git doit principalement conserver le code source et les fichiers nécessaires à la reconstruction de l'environnement.
- Le dossier venv ou .venv ne doit généralement pas être versionné.
- Ajoutez .venv/ ou venv/ au fichier .gitignore selon le nom utilisé.
- git status permet de vérifier quels fichiers Git considère comme modifiés ou non suivis.
- git check-ignore -v permet de vérifier quelle règle .gitignore exclut un fichier.
- Avec venv et pip, requirements.txt peut servir à enregistrer les dépendances nécessaires à la reconstruction de l'environnement.
- Après un clone, chaque développeur peut recréer son propre environnement avec python -m venv .venv.
- Les dépendances peuvent ensuite être réinstallées avec python -m pip install -r requirements.txt.
- Si venv est déjà suivi par Git, git rm -r --cached .venv permet de le retirer de l'index sans supprimer le dossier local.
- Ajouter une règle à .gitignore ne retire pas automatiquement les fichiers déjà suivis et ne nettoie pas l'historique Git existant.
- Le principe essentiel consiste à versionner les informations permettant de reconstruire l'environnement plutôt que l'environnement lui-même.
Pour un nouveau projet Python utilisant venv et Git, nous pouvons commencer par créer l'environnement virtuel.
1 | python -m venv .venv |
Sortie :
1 | Le dossier .venv est créé. |
Nous ajoutons ensuite une règle dans .gitignore afin que Git ne suive pas ce dossier.
1 2 3 | .venv/ __pycache__/ *.pyc |
Sortie :
1 | L'environnement virtuel et les fichiers Python temporaires correspondants sont ignorés par Git. |
Après installation des dépendances, nous pouvons créer requirements.txt puis vérifier l'état du dépôt.
1 2 | python -m pip freeze > requirements.txt git status |
Sortie possible :
1 2 3 4 5 6 | Untracked files: .gitignore main.py requirements.txt Le dossier .venv n'apparaît pas parmi les fichiers à ajouter. |
Un autre développeur pourra alors reconstruire son propre environnement à partir du projet récupéré.
1 2 3 | python -m venv .venv .venv\Scripts\activate.bat python -m pip install -r requirements.txt |
Sortie possible :
1 2 3 4 | (.venv) C:\mon_projet> Collecting ... ... Successfully installed ... |
Auteur : Younes Derfoufi
Lieu de travail : CRMEF OUJDA
Site Web : www.tresfacile.net
Chaine YouTube : https://www.youtube.com/user/InformatiquesFacile
Me contacter : https://www.tresfacile.net/me-contacter/
