如何在 conda 环境中使用 Jupyter notebooks？

Question

典型地，一个运行jupyter notebook或jupyter-notebook或ipython notebook在终端局部地启动一个Jupyter笔记本网络服务器（和打开的浏览器中的URL）。使用conda 和conda 环境时，运行允许导入安装在 conda 环境中的 Python 模块的 Jupyter notebook 的最佳方法是什么？

因为它似乎，这 是 不是 很 直 向前 并 不少 用户 都有 类似的 烦恼。

最常见的错误信息似乎是：在康达环境中安装包后，XYZ my-env一个可以运行import XYZ在开始一个python控制台my-env中，但在运行相同的代码Jupyter笔记本将导致一个ImportError。

这个问题已经问过很多次了，但是没有很好的地方来回答它，大多数问答和Github门票都很混乱，所以让我们在这里开始新的问答。

Answer 1

*免责声明：仅在 Ubuntu 和 Windows 中测试（请参阅对此答案的评论），如果在使用不同的操作系统时发生了变化，请发表评论。

Jupyter 在一个名为kernel的单独进程中运行用户的代码。内核可以是不同的 Python 安装（在不同的 conda 环境或 virtualenv 或 Python 2 而不是 Python 3 中），甚至可以是不同语言（例如 Julia 或 R）的解释器。内核是通过指定解释器和名称以及一些其他参数（请参阅Jupyter 文档）来配置的，并且配置可以存储在系统范围内，用于活动环境（或 virtualenv）或每个用户。如果nb_conda_kernels使用，除了静态配置的内核之外，ipykernelJupyter 笔记本中将为每个安装的 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

Jupyter 将完全安装在 conda 环境中。不同版本的 Jupyter 可用于不同的 conda 环境，但此选项可能有点矫枉过正。在环境中包含内核就足够了，内核是运行代码的封装 Python 的组件。Jupyter notebook 的其余部分可以被视为编辑器或查看器，并且没有必要为每个环境单独安装它并将其包含在每个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
jupyter notebook                                           # run jupyter from system

内核和 conda 环境的名称彼此独立，但使用相似的名称可能更有意义。

只有 Python 内核会在 conda 环境中运行，系统中的 Jupyter 或不同的 conda 环境将被使用——它没有安装在 conda 环境中。通过调用ipython kernel install将 jupyter 配置为使用 conda 环境作为内核，请参阅 Jupyter 文档和IPython 文档以获取更多信息。在大多数 Linux 安装中，此配置是以下*.json文件中的文件 ~/.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"
}

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

当包nb_conda_kernels被安装，一个单独的内核可自动为包含康达包的每个康达环境ipykernel或不同的内核（R，朱，...）。

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

您应该可以选择 Kernel 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

注意：症状并非此处描述的问题所独有。

症状：对于安装在 conda 环境中的模块（但未在系统范围内安装）的 Jupyter notebooks 中的 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

请注意，ipykernel安装conda 包时，会提供可执行文件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就是#!/usr/bin/python3 和不是动态 #!/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

注意：症状并非此处描述的问题所独有。

症状：对于安装在 conda 环境中的模块（但未在系统范围内安装）的 Jupyter notebooks 中的 ImportError，但在 Python 终端中导入时没有错误

说明：通常系统会提供一个名为 python3（显示名称“Python 3”）的内核，配置为使用/usr/bin/python3，例如参见/usr/share/jupyter/kernels/python3/kernel.json。这通常被 conda 环境中的内核覆盖，该内核指向环境 python binary /opt/miniconda3/envs/my-conda-env/bin/python。两者都是由包生成的 ipykernel（见这里 和这里）。

用户内核规范~/.local/share/jupyter/kernels/python3/kernel.json可能会覆盖系统范围和环境内核。如果环境内核缺失或者用户内核指向环境选项1之外的python安装（环境中安装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 环境中（但未安装在系统范围内）的模块出现导入错误

说明：每个终端都有一组环境变量，当终端关闭时会丢失。为了使用 conda 环境，需要设置某些环境变量，这是通过使用conda activate my-conda-env. 如果您尝试从 conda 环境（选项 1）内部运行 Jupyter notebook，但在运行之前未激活 conda 环境，则它可能会运行系统的 jupyter。

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

 conda activate my-conda-env
 jupyter notebook

损坏的内核配置

症状：奇怪的事情发生。可能与上述类似的症状，例如 ImportError

说明：如果您尝试使用选项 2，即通过使用内核的显式配置从系统和 conda 环境中的 Jupyter 内核运行 Jupyter，但它的行为与您预期的不一样，则该配置可能会以某种方式损坏。

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

Python 2 与 3

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

说明：内核配置可能会产生各种令人困惑和误导的效果。例如，默认的 Python 3 内核配置将允许我启动在 Python 2 上运行的 Jupyter notebook：

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 ;-)