- À propos des environnements virtuels avec Jupyter Notebook
- Créer et activer un environnement virtuel Python
- Installer Jupyter Notebook et ipykernel dans l'environnement
- Ajouter l'environnement virtuel comme noyau Jupyter
- Lancer Jupyter Notebook depuis l'environnement virtuel
- Sélectionner et vérifier le noyau de l'environnement virtuel
- Installer et utiliser des packages dans le notebook
- Gérer plusieurs environnements virtuels dans Jupyter
- Supprimer un noyau Jupyter et résoudre les problèmes courants
- À retenir !
1. À propos des environnements virtuels avec Jupyter Notebook
Jupyter Notebook permet d'exécuter du code Python de manière interactive dans des cellules. Lorsqu'un projet utilise des bibliothèques particulières, il est recommandé de l'associer à un environnement virtuel Python afin d'isoler ses packages et leurs versions des autres projets présents sur l'ordinateur.
Avec Jupyter, une notion supplémentaire intervient : le noyau, également appelé kernel. Le noyau est le processus qui exécute le code des cellules du notebook. Pour utiliser correctement un environnement virtuel avec Jupyter Notebook, il faut donc s'assurer que le notebook utilise un noyau associé à l'interpréteur Python de cet environnement.
Le code suivant, exécuté dans une cellule Jupyter, permet d'afficher l'interpréteur Python réellement utilisé par le noyau du notebook.
1 2 3 4 | import sys print("Interpréteur :", sys.executable) print("Environnement virtuel :", sys.prefix != sys.base_prefix) |
Sortie possible :
1 2 | Interpréteur : C:\mon_projet\.venv\Scripts\python.exe Environnement virtuel : True |
Lorsque le chemin de sys.executable appartient au dossier .venv, le notebook utilise bien l'interpréteur de cet environnement virtuel.
2. Créer et activer un environnement virtuel Python
La première étape consiste à créer un environnement virtuel pour le projet. Depuis le dossier du projet, la commande suivante utilise le module standard venv pour créer un environnement nommé .venv.
1 | python -m venv .venv |
Sortie :
1 2 | Aucun message n'est généralement affiché. Le dossier .venv est créé dans le projet. |
Activer l'environnement sous Windows avec CMD
Avec l'invite de commandes Windows, le script activate.bat permet d'activer l'environnement nouvellement créé.
1 | .venv\Scripts\activate.bat |
Sortie possible :
1 | (.venv) C:\mon_projet> |
Activer l'environnement sous Windows avec PowerShell
Dans PowerShell, l'activation s'effectue à l'aide du script Activate.ps1 contenu dans le dossier Scripts de l'environnement.
1 | .venv\Scripts\Activate.ps1 |
Sortie possible :
1 | (.venv) PS C:\mon_projet> |
Activer l'environnement sous Linux et macOS
Sous Linux et macOS, le script activate se trouve dans le dossier bin de l'environnement virtuel.
1 | source .venv/bin/activate |
Sortie possible :
1 | (.venv) utilisateur@ordinateur:~/mon_projet$ |
La présence de (.venv) dans l'invite du terminal indique généralement que l'environnement est actif dans cette session.
3. Installer Jupyter Notebook et ipykernel dans l'environnement
Une fois l'environnement virtuel activé, nous pouvons y installer Jupyter Notebook. L'utilisation de python -m pip permet de s'assurer que pip est exécuté avec l'interpréteur Python actuellement sélectionné.
La commande suivante installe Jupyter Notebook dans l'environnement virtuel.
1 | python -m pip install notebook |
Sortie possible :
1 2 3 4 5 | Collecting notebook Collecting jupyter-server Collecting jupyterlab ... Successfully installed notebook ... |
Pour enregistrer explicitement l'environnement comme noyau Python utilisable dans Jupyter, nous avons également besoin du package ipykernel.
1 | python -m pip install ipykernel |
Sortie possible :
1 2 3 | Collecting ipykernel ... Successfully installed ipykernel ... |
Nous pouvons ensuite vérifier que les deux packages sont disponibles dans l'environnement.
1 2 | python -m pip show notebook python -m pip show ipykernel |
Sortie possible :
1 2 3 4 5 6 | Name: notebook Version: ... ... Name: ipykernel Version: ... ... |
L'environnement virtuel dispose maintenant des composants nécessaires pour fonctionner avec Jupyter Notebook et pour être enregistré comme noyau.
4. Ajouter l'environnement virtuel comme noyau Jupyter
La création d'un environnement virtuel ne suffit pas toujours pour qu'il apparaisse comme noyau sélectionnable dans Jupyter. Le module ipykernel permet d'enregistrer explicitement l'environnement dans la liste des noyaux disponibles.
Avec l'environnement .venv activé, la commande suivante crée un noyau nommé mon_projet. L'option --display-name définit le nom qui sera affiché dans l'interface de Jupyter.
1 | python -m ipykernel install --user --name mon_projet --display-name "Python (mon_projet)" |
Sortie possible :
1 | Installed kernelspec mon_projet in C:\Users\Utilisateur\AppData\Roaming\jupyter\kernels\mon_projet |
Nous pouvons ensuite afficher les noyaux enregistrés avec la commande jupyter kernelspec list.
1 | jupyter kernelspec list |
Sortie possible :
1 2 3 | Available kernels: python3 C:\mon_projet\.venv\share\jupyter\kernels\python3 mon_projet C:\Users\Utilisateur\AppData\Roaming\jupyter\kernels\mon_projet |
Le noyau mon_projet est maintenant enregistré et peut être sélectionné dans Jupyter sous le nom Python (mon_projet).
5. Lancer Jupyter Notebook depuis l'environnement virtuel
Après avoir activé l'environnement virtuel et installé Jupyter Notebook, nous pouvons démarrer le serveur depuis le terminal. L'utilisation de python -m notebook permet de lancer le module notebook avec l'interpréteur de l'environnement actif.
1 | python -m notebook |
Sortie possible :
1 2 3 | [I ... ServerApp] Jupyter Server ... is running at: [I ... ServerApp] http://localhost:8888/tree?token=... [I ... ServerApp] Use Control-C to stop this server |
Jupyter ouvre généralement son interface dans le navigateur. Nous pouvons alors créer un nouveau notebook ou ouvrir un fichier .ipynb existant.
Dans une cellule du notebook, le code suivant permet de vérifier la version de Python utilisée par le noyau actuellement sélectionné.
1 2 3 | import sys print(sys.version) |
Sortie possible :
1 | 3.14.1 (main, ...) |
Le fait d'avoir lancé Jupyter depuis un environnement virtuel est utile, mais il reste important de vérifier le noyau sélectionné lorsque plusieurs kernels sont disponibles.
6. Sélectionner et vérifier le noyau de l'environnement virtuel
Dans l'interface de Jupyter Notebook, le noyau peut être sélectionné ou changé à partir des commandes consacrées aux kernels. Selon la version de l'interface utilisée, la présentation exacte peut varier. Il faut sélectionner le noyau enregistré précédemment, par exemple Python (mon_projet).
Après avoir sélectionné le noyau, le moyen le plus fiable de vérifier l'environnement réellement utilisé consiste à afficher sys.executable.
1 2 3 | import sys print(sys.executable) |
Sortie possible sous Windows :
1 | C:\mon_projet\.venv\Scripts\python.exe |
Sous Linux ou macOS, le résultat peut prendre la forme suivante.
1 2 3 | import sys print(sys.executable) |
Sortie possible :
1 | /home/utilisateur/mon_projet/.venv/bin/python |
Nous pouvons effectuer un diagnostic plus complet en affichant simultanément l'exécutable, le préfixe de l'environnement et le préfixe de l'installation Python de base.
1 2 3 4 5 6 | import sys print("Exécutable :", sys.executable) print("Environnement :", sys.prefix) print("Python de base :", sys.base_prefix) print("Environnement virtuel :", sys.prefix != sys.base_prefix) |
Sortie possible :
1 2 3 4 | Exécutable : C:\mon_projet\.venv\Scripts\python.exe Environnement : C:\mon_projet\.venv Python de base : C:\Python314 Environnement virtuel : True |
Cette vérification évite une erreur fréquente : croire que le notebook utilise un environnement virtuel simplement parce que celui-ci est actif dans un terminal, alors que le kernel Jupyter sélectionné peut utiliser un autre interpréteur.
7. Installer et utiliser des packages dans le notebook
Lorsqu'un notebook utilise un environnement virtuel, les bibliothèques nécessaires au projet doivent être installées dans l'environnement correspondant au noyau actif. Dans un terminal où cet environnement est activé, nous pouvons par exemple installer requests avec pip.
1 | python -m pip install requests |
Sortie possible :
1 2 3 | Collecting requests ... Successfully installed certifi-2025.8.3 charset-normalizer-3.4.3 idna-3.10 requests-2.32.5 urllib3-2.5.0 |
Dans une cellule Jupyter, la commande magique %pip permet également d'installer un package dans l'environnement associé au noyau en cours d'utilisation.
1 | %pip install requests |
Sortie possible :
1 2 | Requirement already satisfied: requests in ...\site-packages ... ... |
Après l'installation, nous pouvons importer requests et vérifier sa version directement dans le notebook.
1 2 3 | import requests print("Version de requests :", requests.__version__) |
Sortie possible :
1 | Version de requests : 2.32.5 |
L'utilisation de %pip dans un notebook est particulièrement pratique, car cette commande est conçue pour installer les packages dans le contexte du kernel actuel, ce qui réduit les risques d'installer une bibliothèque dans un autre environnement Python.
8. Gérer plusieurs environnements virtuels dans Jupyter
Un des avantages de Jupyter est la possibilité d'enregistrer plusieurs environnements virtuels comme noyaux différents. Un projet de science des données peut par exemple utiliser NumPy et Pandas dans un environnement tandis qu'un autre projet utilise des versions ou des bibliothèques différentes.
Supposons qu'un premier environnement soit destiné à l'analyse de données. Après son activation et l'installation d'ipykernel, nous pouvons l'enregistrer avec un nom spécifique.
1 | python -m ipykernel install --user --name data_env --display-name "Python - Data" |
Sortie possible :
1 | Installed kernelspec data_env in C:\Users\Utilisateur\AppData\Roaming\jupyter\kernels\data_env |
Un second environnement destiné à un autre projet peut être enregistré sous un autre nom.
1 | python -m ipykernel install --user --name web_env --display-name "Python - Web" |
Sortie possible :
1 | Installed kernelspec web_env in C:\Users\Utilisateur\AppData\Roaming\jupyter\kernels\web_env |
Nous pouvons afficher les kernels disponibles afin de vérifier que les deux environnements sont enregistrés.
1 | jupyter kernelspec list |
Sortie possible :
1 2 3 4 | Available kernels: python3 ... data_env ... web_env ... |
Dans Jupyter, l'utilisateur peut alors choisir Python - Data pour les notebooks d'analyse de données et Python - Web pour le second projet. Chaque kernel peut ainsi utiliser son propre ensemble de dépendances.
9. Supprimer un noyau Jupyter et résoudre les problèmes courants
Lorsqu'un environnement virtuel a été supprimé, son kernelspec peut rester enregistré dans Jupyter. Il peut alors apparaître dans la liste des noyaux alors que l'interpréteur auquel il faisait référence n'existe plus.
Avant toute suppression, la commande suivante permet de consulter la liste des noyaux enregistrés et leurs emplacements.
1 | jupyter kernelspec list |
Sortie possible :
1 2 3 4 | Available kernels: python3 ... mon_projet ... ancien_env ... |
Si ancien_env n'est plus nécessaire, la commande suivante permet de supprimer son kernelspec. Jupyter demande généralement une confirmation.
1 | jupyter kernelspec uninstall ancien_env |
Sortie possible :
1 2 3 4 | Kernel specs to remove: ancien_env Remove 1 kernel specs [y/N]: y Removed ...\jupyter\kernels\ancien_env |
Un autre problème fréquent se produit lorsqu'une bibliothèque est installée mais que le notebook retourne ModuleNotFoundError. Il faut alors vérifier l'interpréteur utilisé par le kernel.
1 2 3 | import sys print(sys.executable) |
Sortie possible :
1 | C:\mon_projet\.venv\Scripts\python.exe |
Nous pouvons ensuite vérifier les packages visibles depuis le noyau en utilisant la commande magique suivante.
1 | %pip list |
Sortie possible :
1 2 3 4 5 6 7 | Package Version ------------------ ------- ipykernel ... notebook ... pip ... requests 2.32.5 ... |
Si le chemin de sys.executable ne correspond pas à l'environnement attendu, il faut sélectionner le bon kernel ou enregistrer à nouveau l'environnement avec ipykernel.
10. À retenir !
L'utilisation d'un environnement virtuel avec Jupyter Notebook permet d'isoler les dépendances de chaque projet tout en conservant la souplesse de l'exécution interactive. La notion essentielle à comprendre est la distinction entre l'environnement virtuel et le noyau Jupyter utilisé pour exécuter les cellules.
- python -m venv .venv permet de créer un environnement virtuel.
- L'environnement doit être activé avant d'y installer les outils nécessaires depuis le terminal.
- python -m pip install notebook permet d'installer Jupyter Notebook dans l'environnement.
- python -m pip install ipykernel installe le composant permettant d'utiliser Python comme kernel Jupyter.
- python -m ipykernel install permet d'enregistrer l'environnement comme noyau Jupyter.
- --name définit l'identifiant interne du kernel.
- --display-name définit le nom visible dans l'interface Jupyter.
- sys.executable permet de vérifier l'interpréteur réellement utilisé par le notebook.
- %pip install permet d'installer un package dans le contexte du noyau Jupyter actif.
- jupyter kernelspec uninstall permet de supprimer un kernelspec devenu inutile.
Le processus suivant résume la création d'un environnement virtuel sous Windows avec CMD, l'installation de Jupyter et son enregistrement comme kernel.
1 2 3 4 5 6 | python -m venv .venv .venv\Scripts\activate.bat python -m pip install notebook ipykernel python -m ipykernel install --user --name mon_projet --display-name "Python (mon_projet)" jupyter kernelspec list python -m notebook |
Sortie possible :
1 2 3 4 5 6 7 | Successfully installed notebook ... ipykernel ... Installed kernelspec mon_projet in ... Available kernels: python3 ... mon_projet ... Jupyter Server ... is running at: http://localhost:8888/tree?token=... |
Une fois le notebook ouvert avec le kernel Python (mon_projet), le code suivant permet d'effectuer une dernière vérification.
1 2 3 4 5 6 7 | import sys print("Version Python :", sys.version.split()[0]) print("Interpréteur :", sys.executable) print("Environnement :", sys.prefix) print("Python de base :", sys.base_prefix) print("Environnement virtuel :", sys.prefix != sys.base_prefix) |
Sortie possible :
1 2 3 4 5 | Version Python : 3.14.1 Interpréteur : C:\mon_projet\.venv\Scripts\python.exe Environnement : C:\mon_projet\.venv Python de base : C:\Python314 Environnement virtuel : True |
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/
