Comment utiliser les cahiers Jupyter dans un environnement conda?
En général, on exécute jupyter notebook ou jupyter-notebook ou ipython notebook dans un terminal pour démarrer localement un serveur Web de bloc-notes Jupyter (et ouvrir l'URL dans le navigateur). Lors de l'utilisation de conda et environnements conda , quelle est la meilleure façon d'exécuter un bloc-notes Jupyter qui permet d'importer Python modules installés dans l'environnement conda?
Comme il semble, ceciestpastout à faitdroitavantetnombreuxtilisateursontsimilaireproblèmes .
Le message d'erreur le plus courant semble être: après l'installation d'un package XYZ dans un environnement conda my-env on peut exécuter import XYZ dans une console python démarrée dans my-env, mais l'exécution du même code dans le bloc-notes Jupyter entraînera une ImportError .
Cette question a été posée plusieurs fois, mais il n'y a pas de bon endroit pour y répondre, la plupart des Q&R et des tickets Github sont assez compliqués alors commençons une nouvelle Q&R ici .
Avertissement: testé uniquement dans Ubuntu, veuillez commenter si quelque chose est différent sous Windows/Mac OS.
Jupyter exécute le code de l'utilisateur dans un processus séparé appelé kernel. Le noyau peut être une installation Python différente (dans un environnement conda différent ou virtualenv ou Python 2 au lieu de Python 3 ) ou même un interpréteur pour une langue différente (par exemple Julia ou R). Les noyaux sont configurés en spécifiant l'interpréteur et un nom et d'autres paramètres (voir documentation Jupyter ) et la configuration peut être stockée à l'échelle du système , pour l'environnement actif (ou virtualenv) ou par utilisateur. Si nb_conda_kernels est utilisé, en plus des noyaux configurés statiques, un noyau distinct pour chaque environnement conda avec ipykernel installé sera disponible dans les blocs-notes Jupyter.
En bref, il existe trois options pour utiliser un environnement conda et Jupyter:
Option 1: exécuter le serveur et le noyau Jupyter dans l'environnement conda
Faites quelque chose comme:
conda create -n my-conda-env # creates new virtual env
conda activate my-conda-env # activate environment in terminal
conda install jupyter # install jupyter + notebook
jupyter notebook # start server + kernel
Jupyter sera complètement installé dans l'environnement conda. Différentes versions de Jupyter peuvent être utilisées pour différents environnements de conda, mais cette option peut être un peu exagérée. Il suffit d'inclure le noyau dans l'environnement, qui est l'encapsulage des composants Python qui exécute le code. Le reste du bloc-notes Jupyter peut être considéré comme un éditeur ou un visualiseur et il n'est pas nécessaire d'installer ceci séparément pour chaque environnement et l'inclure dans chaque env.yml fichier. Par conséquent, l'une des deux options suivantes pourrait être préférable, mais celle-ci est la plus simple et certainement très bien.
Option 2: créer un noyau spécial pour l'environnement conda
Faites quelque chose comme:
conda create -n my-conda-env # creates new virtual env
conda activate my-conda-env # activate environment in terminal
conda install ipykernel # install Python kernel in new conda env
ipython kernel install --user --name=my-conda-env-kernel # configure Jupyter to use Python kernel
jupyter notebook # run jupyter from system
Le nom du noyau et l'environnement conda sont indépendants l'un de l'autre, mais il peut être judicieux d'utiliser un nom similaire.
Seul le noyau Python sera exécuté dans l'environnement conda, Jupyter du système ou un autre environnement conda sera utilisé - il n'est pas installé dans l'environnement conda. En appelant ipython kernel install le jupyter est configuré pour utiliser l'environnement conda comme noyau, voir documentation Jupyter et documentation IPython pour plus d'informations. Dans la plupart des installations Linux, cette configuration est un *.json fichier dans ~/.local/share/jupyter/kernels/my-conda-env-kernel/kernel.json:
{
"argv": [
"/opt/miniconda3/envs/my-conda-env/bin/python",
"-m",
"ipykernel_launcher",
"-f",
"{connection_file}"
],
"display_name": "my-conda-env-kernel",
"language": "python"
}
Option 3: utilisez nb_conda_kernels pour utiliser un noyau dans l'environnement conda
Lorsque le package nb_conda_kernels est installé, un noyau séparé est disponible automatiquement pour chaque environnement conda contenant le package conda ipykernel ou un noyau différent (R, Julia, ...).
conda activate my-conda-env # this is the environment for your project and code
conda install ipykernel
conda deactivate
conda activate base # could be also some other environment
conda install nb_conda_kernels
jupyter notebook
Vous devriez pouvoir choisir le noyau Python [conda env:my-conda-env]. Notez que nb_conda_kernels semble être disponible uniquement via conda et non via pip ou d'autres gestionnaires de paquets comme apt.
Dépannage
En utilisant Linux/Mac, la commande which sur la ligne de commande vous indiquera quel jupyter est utilisé, si vous utilisez l'option 1 (exécutant Jupyter depuis l'intérieur de l'environnement conda), ce devrait être un exécutable de votre environnement conda:
$ which jupyter
/opt/miniconda3/envs/my-conda-env/bin/jupyter
$ which jupyter-notebook # this might be different than 'which jupyter'! (see below)
/opt/miniconda3/envs/my-conda-env/bin/jupyter-notebook
À l'intérieur du cahier, vous devriez voir que Python utilise Python chemins de l'environnement conda:
[1] !which python
/opt/miniconda3/envs/my-conda-env/bin/python
[2] import sys; sys.executable
'/opt/miniconda3/envs/my-conda-env/bin/python'
['/home/my_user',
'/opt/miniconda3/envs/my-conda-env/lib/python37.Zip',
'/opt/miniconda3/envs/my-conda-env/lib/python3.7',
'/opt/miniconda3/envs/my-conda-env/lib/python3.7/lib-dynload',
'',
'/opt/miniconda3/envs/my-conda-env/lib/python3.7/site-packages',
'/opt/miniconda3/envs/my-conda-env/lib/python3.7/site-packages/IPython/extensions',
'/home/my_user/.ipython']
Jupyter fournit la commande jupyter-troubleshoot ou dans un cahier Jupyter:
!jupyter-troubleshoot
Cela imprimera de nombreuses informations utiles sur l'inclusion des sorties mentionnées ci-dessus ainsi que sur les bibliothèques installées et autres. Lorsque vous demandez de l'aide concernant les questions d'installation de Jupyter, il peut être judicieux de fournir ces informations dans des rapports de bogues ou des questions.
Pour répertorier tous les noyaux Jupyter configurés exécutés:
jupyter kernelspec list
Erreurs et pièges courants
Ordinateur portable Jupyter non installé dans un environnement conda
Remarque: les symptômes ne sont pas propres au problème décrit ici.
Symptômes: ImportError dans les blocs-notes Jupyter pour les modules installés dans l'environnement conda (mais pas installés à l'échelle du système), mais aucune erreur lors de l'importation dans un Python
Explication: Vous avez essayé d'exécuter le cahier jupyter depuis votre environnement conda (option 1, voir ci-dessus), il n'y a pas de configuration pour un noyau pour cet environnement conda (ce serait l'option 2) et nb_conda_kernels n'est pas installé (option 3), mais le cahier jupyter n'est pas (entièrement) installé dans l'environnement conda, même si which jupyter pourrait vous le faire croire.
Sous GNU/Linux, vous pouvez taper which jupyter pour vérifier quel exécutable de Jupyter est exécuté.
Cela signifie que Jupyter du système est utilisé, probablement parce que Jupyter n'est pas installé:
(my-conda-env) $ which jupyter-notebook
/usr/bin/jupyter
Si le chemin pointe vers un fichier dans votre environnement conda, Jupyter est exécuté depuis l'intérieur de Jupyter:
(my-conda-env) $ which jupyter-notebook
/opt/miniconda3/envs/my-conda-env/bin/jupyter-notebook
Notez que lorsque le package conda ipykernel est installé, un exécutable jupyter est livré, mais aucun exécutable jupyter-notebook. Cela signifie que which jupyter renverra un chemin vers l'environnement conda mais jupyter notebook démarrera le système jupyter-nootebook (voir aussi ici ):
$ conda create -n my-conda-env
$ conda activate my-conda-env
$ conda install ipykernel
$ which jupyter # this looks good, but is misleading!
/opt/miniconda3/envs/my-conda-env/bin/jupyter
$ which jupyter-notebook # jupyter simply runs jupyter-notebook from system...
/usr/bin/jupyter-notebook
Cela se produit car jupyter notebook recherche jupyter-notebook, trouve /usr/bin/jupyter-notebook et l'appelle démarrer un nouveau Python. Le Shebang dans /usr/bin/jupyter-notebook est #!/usr/bin/python3 et pas une dynamique#!/usr/bin/env python. Par conséquent Python parvient à sortir de l'environnement conda. Je suppose que jupyter pourrait appeler python /usr/bin/jupyter-notebook à la place pour annuler le Shebang, mais le mélange des fichiers bin du système et du chemin python de l'environnement ne peut pas bien fonctionner de toute façon.
Solution: Installez le bloc-notes jupyter dans l'environnement conda:
conda activate my-conda-env
conda install jupyter
jupyter notebook
Mauvaise configuration du noyau: le noyau est configuré pour utiliser le système Python
Remarque: les symptômes ne sont pas propres au problème décrit ici.
Symptômes: ImportError dans les blocs-notes Jupyter pour les modules installés dans l'environnement conda (mais pas installés à l'échelle du système), mais aucune erreur lors de l'importation dans un Python
Explication: Généralement, le système fournit un noyau appelé python3 (nom d'affichage "Python 3") configuré pour utiliser /usr/bin/python3, voir par exemple /usr/share/jupyter/kernels/python3/kernel.json. Ceci est généralement remplacé par un noyau dans l'environnement conda, qui pointe vers les environnements python binary /opt/miniconda3/envs/my-conda-env/bin/python. Les deux sont générés par le package ipykernel (voir ici et ici ).
Une spécification du noyau utilisateur dans ~/.local/share/jupyter/kernels/python3/kernel.json peut remplacer le noyau du système et de l'environnement. Si le noyau d'environnement est manquant ou si le noyau d'utilisateur pointe vers une python en dehors de l'option d'environnement 1 (installation de jupyter dans l'environnement) échouera.
Pour les occurrences et les discussions sur ce problème et ses variantes, voir ici , ici , ici et aussi ici , ici et ici .
Solution: Utilisez jupyter kernelspec list pour répertorier les emplacements du noyau actif.
$ conda activate my-conda-env
$ jupyter kernelspec list
Available kernels:
python3 /opt/miniconda3/envs/my-conda-env/share/jupyter/kernels/python3
Si le noyau de l'environnement est manquant, vous pouvez essayer de le créer manuellement à l'aide de ipython kernel install --sys-prefix dans l'environnement activé, mais il est probablement préférable de vérifier votre installation, car conda install ipykernel aurait dû créer l'environnement (peut-être essayer de recréer l'environnement et de réinstaller tous les packages?).
Si une spécification du noyau utilisateur bloque la spécification du noyau d'environnement, vous pouvez la supprimer ou utiliser un chemin d'accès relatif python qui utilisera $PATH pour savoir quelle python utiliser. Donc, quelque chose comme ça, devrait être totalement bien:
$ cat ~/.local/share/jupyter/kernels/python3/kernel.json
{
"argv": [
"python",
"-m",
"ipykernel_launcher",
"-f",
"{connection_file}"
],
"display_name": "Python 3",
"language": "python"
}
Environnement de conda correct non activé
Symptômes: ImportError pour les modules installés dans l'environnement conda (mais non installés à l'échelle du système) dans les blocs-notes Jupyter et les terminaux Python
Explication: Chaque terminal possède un ensemble de variables d'environnement, qui sont perdues lorsque le terminal est fermé. Pour utiliser un environnement conda, certaines variables d'environnement doivent être définies, ce qui se fait en l'activant à l'aide de conda activate my-conda-env. Si vous avez tenté d'exécuter le bloc-notes Jupyter à partir de l'environnement conda (option 1), mais que vous n'avez pas activé l'environnement conda avant de l'exécuter, il peut exécuter le jupyter du système.
Solution: Activez l'environnement conda avant d'exécuter Jupyter.
conda activate my-conda-env
jupyter notebook
Configuration du noyau cassée
Symptômes: Des choses étranges se produisent. Peut-être des symptômes similaires à ceux ci-dessus, par exemple ImportError
Explication: Si vous avez essayé d'utiliser l'option 2, c'est-à-dire exécuter Jupyter à partir du système et du noyau Jupyter à l'intérieur de l'environnement conda en utilisant une configuration explicite pour le noyau, mais il ne se comporte pas comme prévu, la configuration peut être corrompue dans d'une certaine manière .
Solution: Vérifiez la configuration dans ~/.local/share/jupyter/kernels/my-kernel-name/kernel.json et corrigez les erreurs manuellement ou supprimez le répertoire entier et recréez-le à l'aide de la commande fournie ci-dessus pour l'option 2. Si vous ne trouvez pas la configuration du noyau, exécutez jupyter kernelspec list.
Python 2 contre 3
Symptômes: ImportError due à incorrect Python du noyau Jupyter ou autres problèmes avec Python 2/
Explication: La configuration du noyau peut avoir toutes sortes d'effets déroutants et trompeurs. Par exemple, la configuration par défaut du noyau Python 3 me permettra de lancer un bloc-notes Jupyter fonctionnant sur Python 2:
conda create -n my-conda-env
conda activate my-conda-env
conda install python=2
conda install jupyter
jupyter notebook
Le noyau par défaut Python 3:
$ cat ~/.local/share/jupyter/kernels/python3/kernel.json
{
"argv": [
"python",
"-m",
"ipykernel_launcher",
"-f",
"{connection_file}"
],
"display_name": "Python 3",
"language": "python"
}
Après avoir créé un nouveau bloc-notes Jupyter avec le noyau Python 3, Python 2 de l'environnement conda sera utilisé même si "Python 3" est affiché par Jupyter).
Solution: N'utilisez pas Python 2; -)