如何在conda环境中使用Jupyter笔记本?

134
通常情况下,人们在终端中运行jupyter notebookjupyter-notebookipython notebook来启动本地Jupyter笔记本Web服务器(并在浏览器中打开URL)。当使用condaconda环境时,最好的方法是运行Jupyter笔记本,从而允许导入安装在conda环境中的Python模块。似乎这个问题不太直接明确很多问题也是如此用户 遇到了 类似的 问题

最常见的错误信息是:在conda环境中安装了一个包XYZ后,可以在Python控制台中启动my-env并运行import XYZ,但在Jupyter notebook中运行相同的代码会导致 ImportError。

这个问题已经被问过很多次,但没有一个好的地方来回答它,大多数的Q&A和Github票据都相当混乱,所以让我们在这里开始一个新的Q&A


我被这个问题困扰了多年!感谢您解决它 - 正如您所说 - 这个问题的 Git 跟踪是一团糟。 - Shawn
4个回答

222

注意: 该ATM仅在Ubuntu和Windows上进行过测试(请参见对此答案的评论)。


Jupyter在名为“kernel”的独立进程中运行用户的代码。Kernel可以是不同的Python安装(在不同的conda环境或virtualenv中或者Python 2而不是Python 3),甚至可以是其他语言的解释器(例如Julia或R)。通过指定解释器、名称和一些其他参数来配置内核(参见Jupyter文档),并且可以将配置存储系统范围内、对于活动环境(或virtualenv)或每个用户进行存储。如果使用nb_conda_kernels,除了静态配置的内核外,在Jupyter笔记本中还将提供每个安装了ipykernel的conda环境的单独内核。
简而言之,有三种使用conda环境和Jupyter的选项:
选项1:在conda环境内运行Jupyter服务器和内核
做以下操作:
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 inside my-conda-env

Jupyter将在conda环境中完全安装。可以为不同的conda环境使用不同版本的Jupyter,但这可能有点过度。只需在环境中包含内核即可,该内核是包装Python并运行代码的组件。可以将Jupyter笔记本的其余部分视为编辑器或查看器,并且没有必要为每个环境单独安装它并将其包含在每个env.yml文件中。因此,下面两个选项中的一个可能更可取,但这个选项是最简单的,肯定可以。

选项2:为conda环境创建特殊内核

像这样做:

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

然后从系统安装或不同的conda环境中运行jupyter:

conda deactivate          # this step can be omitted by using a different terminal window than before
conda install jupyter     # optional, might be installed already in system e.g. by 'apt install jupyter' on debian-based systems
jupyter notebook          # run jupyter from system

内核和conda环境的名称是相互独立的,但使用类似的名称可能是有意义的。

只有Python内核将在conda环境中运行,Jupyter来自系统或不同的conda环境 - 它未安装在conda环境中。通过调用ipython kernel install,可以配置jupyter使用conda环境作为内核,请参阅Jupyter文档IPython文档以获取更多信息。在大多数Linux安装中,此配置是位于~/.local/share/jupyter/kernels/my-conda-env-kernel/kernel.json中的*.json文件:

{
 "argv": [
  "/opt/miniconda3/envs/my-conda-env/bin/python",
  "-m",
  "ipykernel_launcher",
  "-f",
  "{connection_file}"
 ],
 "display_name": "my-conda-env-kernel",
 "language": "python"
}

选项3:使用nb_conda_kernels在conda环境中使用内核

安装nb_conda_kernels后,每个包含conda软件包ipykernel或其他内核(R,Julia等)的conda环境都会自动提供一个单独的内核。

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

您应该能够选择内核Python [conda env:my-conda-env]。请注意,nb_conda_kernels似乎仅通过conda而不是pip或其他软件包管理器(如apt)提供。

故障排除

在Linux/Mac上,命令行中的which命令将告诉您使用哪个jupyter,如果您正在使用选项1(从conda环境内部运行Jupyter),则应该是来自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

在笔记本中,您应该看到Python使用来自conda环境的Python路径:

[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提供命令jupyter-troubleshoot或在Jupyter笔记本中使用:

!jupyter-troubleshoot

这将打印出关于输出、安装的库和其他信息的大量有用信息。当询问有关Jupyter安装问题的帮助时,最好在错误报告或问题中提供此信息。
要列出所有配置的Jupyter内核,请运行:
jupyter kernelspec list

常见错误和陷阱

在conda环境中未安装Jupyter Notebook

注意:症状不一定唯一。

症状:在Jupyter笔记本中导入已在conda环境中安装(但未在系统范围内安装)的模块时出现ImportError,但在Python终端中导入时没有错误。

解释:您尝试从conda环境内运行jupyter notebook(选项1,请参见上文),但此conda环境没有配置内核(这将是选项2),并且未安装nb_conda_kernels(选项3),但jupyter notebook并未在conda环境中完全安装,即使which jupyter可能会让您相信已经安装了。

在GNU/Linux中,您可以输入which jupyter来检查运行的Jupyter可执行文件。

这意味着使用的是系统的Jupyter,可能是因为Jupyter未安装:

(my-conda-env) $ which jupyter-notebook
/usr/bin/jupyter

如果路径指向conda环境中的文件,则Jupyter将在Jupyter内部运行:

(my-conda-env) $ which jupyter-notebook
/opt/miniconda3/envs/my-conda-env/bin/jupyter-notebook

请注意,安装conda包ipykernel时,会提供可执行文件jupyter,但不提供可执行文件jupyter-notebook。这意味着which jupyter将返回conda环境的路径,但jupyter notebook将启动系统的jupyter-nootebook(也可参见此处)。
 $ 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

这是因为jupyter notebook会寻找jupyter-notebook,并在/usr/bin/jupyter-notebook中找到它进行调用,从而启动一个新的Python进程。在/usr/bin/jupyter-notebook文件中的shebang是#!/usr/bin/python3不是动态shebang#!/usr/bin/env python。因此,Python成功地跳出了conda环境。我想jupyter可以调用python /usr/bin/jupyter-notebook来覆盖shebang,但混合系统的bin文件和环境的python路径也无法正常工作。 解决方案:在conda环境内安装jupyter notebook:
 conda activate my-conda-env
 conda install jupyter
 jupyter notebook

内核配置错误:内核配置为使用系统Python

注意:症状并不唯一适用于此处描述的问题。

症状:在Jupyter笔记本中,对于在conda环境中安装的模块(但未在系统范围内安装),会出现ImportError错误,但在Python终端导入时不会出错。

解释:通常,系统提供了一个称为python3(显示名称为“Python 3”)的内核,其配置为使用/usr/bin/python3,例如/usr/share/jupyter/kernels/python3/kernel.json。这通常被conda环境中的内核覆盖,该内核指向环境中的python二进制文件/opt/miniconda3/envs/my-conda-env/bin/python。两者都由软件包ipykernel生成(请参见herehere)。

~/.local/share/jupyter/kernels/python3/kernel.json中的用户内核规范可能会覆盖系统范围和环境内核。如果缺少环境内核或用户内核指向环境外的python安装,则选项1(在环境中安装jupyter)将失败。

对于这个问题和变种的出现和讨论,请参见此处, 此处, 此处 以及此处, 此处此处

解决方案: 使用jupyter kernelspec list列出活动内核位置。

$ conda activate my-conda-env
$ jupyter kernelspec list
Available kernels:
  python3 /opt/miniconda3/envs/my-conda-env/share/jupyter/kernels/python3

如果环境中缺少内核,您可以尝试手动创建它,使用ipython kernel install --sys-prefix在激活的环境中,但最好检查您的安装,因为conda install ipykernel应该已经创建了环境(也许尝试重新创建环境并重新安装所有软件包?)。
如果用户内核规范阻止环境内核规范,则可以删除它或使用相对Python路径,该路径将使用$PATH来确定要使用哪个python。因此,像这样的东西应该完全没问题:
$ cat ~/.local/share/jupyter/kernels/python3/kernel.json
{
 "argv": [
  "python",
  "-m",
  "ipykernel_launcher",
  "-f",
  "{connection_file}"
 ],
 "display_name": "Python 3",
 "language": "python"
}

正确的conda环境未激活

症状:在Jupyter笔记本和Python终端中,导入在conda环境中安装(但未在整个系统中安装)的模块时出现ImportError。

解释:每个终端都有一组环境变量,当终端关闭时,这些变量会丢失。为了使用conda环境,需要设置某些环境变量,这可以通过使用conda activate my-conda-env来完成。如果您尝试从conda环境内部运行Jupyter笔记本(选项1),但在运行之前没有激活conda环境,则可能会运行系统的jupyter。

解决方案:在运行Jupyter之前激活conda环境。

 conda activate my-conda-env
 jupyter notebook

内核配置损坏

症状:出现奇怪的事情。可能与上述症状相似,例如 ImportError。

解释:如果您尝试使用选项 2,即从系统运行 Jupyter 并在 conda 环境中使用 Jupyter 内核,但它的行为不符合您的预期,则配置可能已经以 某种方式 损坏。

解决方案:检查 ~/.local/share/jupyter/kernels/my-kernel-name/kernel.json 中的配置,并手动修复错误或删除整个目录并使用上面提供的选项 2 命令重新创建它。如果您找不到内核配置,请运行 jupyter kernelspec list

Python 2 vs 3

症状:由于 Jupyter 内核的 Python 版本错误其他 Python 2/3 的问题导致 ImportError

解释:内核配置可能会产生各种混乱和误导性的影响。例如,默认的 Python 3 内核配置将允许我启动运行在 Python 2 上的 Jupyter 笔记本:

conda create -n my-conda-env
conda activate my-conda-env
conda install python=2
conda install jupyter
jupyter notebook

默认的Python 3内核:

$ cat ~/.local/share/jupyter/kernels/python3/kernel.json
{
 "argv": [
  "python",
  "-m",
  "ipykernel_launcher",
  "-f",
  "{connection_file}"
 ],
 "display_name": "Python 3",
 "language": "python"
}

在使用Python 3内核创建新的Jupyter Notebook后,即使Jupyter显示“Python 3”,也会使用conda环境中的Python 2。

解决方案:不要使用Python 2;-)


2
选项3有一个错误:nb_conda之所以有效,是因为它将nb_conda_kernels作为依赖项安装。nb_conda_kernels是在环境中自动识别任何已安装ipykernel的env所需的唯一要求(请参阅文档)。nb_conda软件包是用于Jupyter扩展的,它向Jupyter添加了一个“Conda”选项卡,提供类似于Anaconda Navigator的GUI来管理envs。 - merv
2
@merv 嗯,是的!非常感谢你指出这个问题,我已经修复了错误。 - lumbric
2
选项1中的代码:conda install juypter应该是conda install jupyter - Chuck
1
@HolmesQueen 是的,你说得对。带有命令的代码片段有点误导人。基本上,对于选项2,您需要在(a)系统安装,(b)conda基本环境和(c)不同的conda env之间进行选择。对于(a),您可以在没有conda的情况下安装jupyter(例如使用apt)。对于(b),您可以在激活环境之前安装jupyter,或者通过停用它或打开新终端来安装jupyter。对于(c),您可以在激活新的不同环境后安装jupyter。无论哪种情况,您都需要在选择的正确环境中运行jupyter notebook。我稍微更新了说明。 - lumbric
2
作为警告 - 如果您依赖于 conda 来使所有安装了 ipykernel 的环境在 Jupyter 中可用,则 jupyter kernelspec list 将会是误导性的。jupyter kernelspec list 不知道 conda 环境,因此可能只显示当前环境,但您可能会在 Jupyter 中看到更多的内核。 - magiclantern
显示剩余20条评论

3
以下命令也可作为一行代码,用于创建Conda环境并运行最新版本的Python和Jupyter Notebooks。
conda create -n <env-name> python jupyter

如果你想安装特定版本的Python或Jupyter,你可以这样做:

conda create -n <env-name> python=<version> jupyter=<version>

例如,
conda create -n <env-name> python=3.10.4 jupyter=1.0.0

如果你想在这个环境中的笔记本中使用其他软件包,你可以按照以下步骤进行操作:

conda create -n <env-name> python jupyter <another-package> <another-package> ...

例如,

conda create -n <env-name> python jupyter scikit-learn

请注意,与之前类似,这些命令将安装最新版本的Python和相关包。如果您想要特定版本,可以使用“=”语法。
此外,一旦创建了环境,您仍然可以使用“pip install”或“conda install”安装所需的任何包。
创建环境后(使用上述任何一种方法),您只需要运行以下命令来激活您的环境并运行Jupyter Notebooks。
conda activate <env-name>
jupyter notebook 

1
这基本上是我答案中的选项1,但使用conda install的快捷方式。如果您想少输入一个命令,可以这样做。如果包可以通过conda获得,我会建议不要使用pip。 - lumbric

1
我在这个问题上遇到了很多困扰,因为它没有明确的文档说明。很多人会建议在每个conda环境中安装Jupyter,也有很多人会告诉你在(base) conda环境中安装Jupyter。不幸的是,这两种建议都是可能的,但是错误的,并且最终会导致奇怪的行为。
我通过试错学到了这一点,现在我相信我知道如何正确地进行操作和推荐的方式(2023年11月!)。这适用于本地机器,也为你提供了适用于远程计算的工作流程。
以下是我学到的一些要点:
- Conda不鼓励在基本环境中安装任何东西。 - Conda鼓励为每个应用程序创建一个环境,包括Jupyter。 - Jupyter确实显示了我用ipykernel install …创建的内核,但我从未能使其实际使用正确的环境。 - 当我最终切换到nb_conda_kernels(lumbric的第三种解决方案,但不在基本环境中!)时,一切都自动正常工作了!你只需要在你的Jupyter环境中安装nb_conda_kernels和任何你想在Jupyter中使用的conda环境的ipykernel。

创建Jupyter环境

请注意并检查conda install ...命令。我添加了一些有用的扩展,但您应该安装您想要的内容。 在创建新环境之前,请确保处于正确的conda路径下。如果您在不同的目录中创建新环境,可能会遇到命名环境消失的问题。

cd ~/<miniconda>
conda create -n jupyter python=3.11
conda activate jupyter

conda install --channel=conda-forge jupyterlab jupyterlab-favorites jupyterlab-system-monitor nb_conda_kernels

现在你将拥有一个带有Python 3.11的Jupyter环境。如果你想启动Jupyter,只需打开终端并输入以下命令: jupyter lab 只要这个终端窗口保持打开状态,Jupyter就会运行。

创建项目环境

cd ~/<my_project>
conda create -n my_project python=3.9
conda activate my_project
conda install <…> #(whatever you want to install for your project; use conda first and only if n/a then pip, then brew, then compile)**
# install support for this env kernel in Jupyter:
conda install ipykernel

**让我们在这里重复一下警告:

  • 如果你使用conda,请不要使用pip、brew等(尽可能避免使用)。
  • 首先尝试使用conda install --channel=conda-forge mypackage
  • 如果不可用,请尝试使用conda install mypackage
  • 如果不可用,可以使用pip install mypackage
  • 如果不可用,可以尝试使用brew installapt-get …等等
  • 如果不可用,您必须自己编译该库。

启动Jupyter:

conda activate jupyter
jupyter lab

选择环境

...现在你可以在Jupyter中选择你的环境内核。通常你会在笔记本的右上角找到它。你应该能看到任何安装了nb_conda_kernels的环境,看起来像这样:

Python [conda env:my_project]


使用基本环境有什么不利之处吗?请注意,您无需安装nb_conda_kernels,只需安装ipykernel。如果您在my_project中安装了nb_conda_kernels,那么没有真正需要第二个conda环境,因为nb_conda_kernels依赖于jupyterlab,所以最终您会在两个环境中都安装jupyterlab。 - undefined
是的,确实有一些问题 - 这里有一个很好的解释:(https://stackoverflow.com/a/56504279/388412),而且[conda文档](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-envs)也明确指出“您不希望将程序放入基本环境中”。另一方面,将Jupyter放在自己的环境中意味着我有一个独立的shell窗口,可以启动/停止,有Jupyter自己的Python版本等等。我认为这比将Jupyter和许多依赖项放在基本环境中更加清洁,因为这可能会与其他环境发生冲突。 - undefined
是的,你说得对,我刚刚查了一下,只要在环境中安装了ipykernel,就可以将其作为Jupyter内核使用。谢谢你提供的信息! - undefined
官方文档并没有明确说明为什么不要在基础环境中安装任何东西,以及为什么首先允许这样做,但是SO的回答提出了一个很好的观点。不过,最终是否要在您的计算机上安装多个Jupyter版本,这取决于您个人的需求。 - undefined
这个答案可以通过遵循更好的做法来改进,即在conda create命令中指定所有的包,而不是进行一系列的conda create-conda activate-conda install操作。后者只会给用户更多犯错误的机会,并且由于需要多次运行求解过程,会消耗更多的计算时间。更好的做法是从一开始就采用将环境定义为YAML文件的习惯,并使用conda env create命令。 - undefined

0

以下方法适用于我:

  1. 激活您想要使用的环境:conda activate <env_name>

  2. pip install ipykernel(如果您还没有安装它)

  3. python -m ipykernel install --user --name=<env_name>


3
我想这基本上就是我在上面第二个选项中回答的内容,只是使用了稍微不同的命令。 - lumbric
1
我只觉得答案太长了,没有读到那个地方...从我的搜索中,我找到了这三个命令,对于寻求快速答案而非整篇文章的人会很有帮助。 - Siddharth Shakya
这是更广受赞同的回答的精简版。一个改进建议:如果你已经在使用conda,为什么不使用conda install ipykernel呢?如果你使用conda安装了ipykernel,第三步就可以省去(尽管你仍然可以执行它)。 - magiclantern

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接