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

Question

通常在终端中运行 jupyter notebook 或 jupyter-notebook 或 ipython notebook 到
在本地启动 Jupyter 笔记本网络服务器(并在浏览器中打开 URL)。使用 conda 时
和 conda environments 、 运行 Jupyter 笔记本的最佳方式是什么，它允许
导入安装在 conda 环境中的 Python 模块？

看起来， this is not quite 0x2518122133411542 2318122133411542 23153152152134152133415314213421342133341315213341521333341521421342
straight forward and many .

最常见的错误消息似乎是:在 conda 环境中安装包 XYZ 之后my-env 可以在以 import XYZ 启动的 python 控制台中运行 my-env ，但运行相同
Jupyter notebook 中的代码将导致 ImportError 。

这个问题已经问过很多次了，但是没有很好的地方来回答它，大多数问答和
Github 票很乱所以 users 。

Answer 1

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

Jupyter 在称为内核的单独进程中运行用户的代码。内核可以不同
Python 安装(在不同的 conda 环境或 virtualenv 或 Python 2 而不是 Python
3) 甚至是不同语言的解释器(例如 Julia 或 R)。内核由
指定解释器和名称以及其他一些参数(参见 Jupyter documentation)
并且配置可以存储在系统范围内，用于事件环境(或 virtualenv)或每个
用户。如果使用 nb_conda_kernels，除了静态配置的内核之外，每个内核都有一个单独的内核
安装了 ipykernel 的 conda 环境将在 Jupyter 笔记本中可用。
简而言之，如何使用 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 documentation 和 IPython documentation 了解更多信息。在大多数 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 环境中使用内核
安装 package 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 notebook 中:

!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

注意，安装conda包 ipykernel时，会附带一个可执行文件 jupyter，但是
没有可执行文件 jupyter-notebook 。这意味着 which jupyter 将返回 conda 的路径
环境但 jupyter notebook 将启动系统的 jupyter-nootebook (另见 here ):

 $ 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 和
calls it
启动一个新的 Python 进程。 /usr/bin/jupyter-notebook中的shebang是 #!/usr/bin/python3和 not a dynamic #!/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 二进制 /opt/miniconda3/envs/my-conda-env/bin/python 。两者都是由包生成的 ipykernel(见 here
和 here )。 ~/.local/share/jupyter/kernels/python3/kernel.json 中的用户内核规范可能会覆盖
系统范围和环境内核。如果环境内核缺失或用户内核
指向环境选项 1 之外的 python 安装(在
环境)将失败。
有关此问题和变体的出现和讨论，请参见 here ，
here ,
here
还有 here ，
here 和
here。
解决方案: 使用 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 环境
症状: 安装在 conda 环境中的模块导入错误(但未安装系统)
宽)在 Jupyter 笔记本和 Python 终端中
解释: 每个终端都有一组环境变量，终端时丢失
关闭了。为了使用 conda 环境，需要设置某些环境变量，其中
通过使用 conda activate my-conda-env 激活它来完成。如果您尝试运行 Jupyter
conda 环境中的 notebook(选项 1)，但未激活 conda 环境
在运行它之前，它可能会运行系统的 jupyter。
解决方案: 运行 Jupyter 前激活 conda 环境。

 conda activate my-conda-env
 jupyter notebook

损坏的内核配置
症状: 奇怪的事情发生了。也许与上述类似的症状，例如导入错误
解释: 如果您尝试使用选项 2，即从系统和 Jupyter 运行 Jupyter
通过使用内核的显式配置在 conda 环境中使用内核，但它确实
行为不符合您的预期，配置可能在 some way 中损坏。
解决方案: 检查 ~/.local/share/jupyter/kernels/my-kernel-name/kernel.json中的配置
并手动修复错误或删除整个目录并使用命令重新创建它
上面为选项 2 提供了。如果在那里找不到内核配置，请运行 jupyter kernelspec list。
Python 2 与 3
症状: 导入错误由于 wrong Python version of the Jupyter kernel 或 other problemswith Python 2/3
解释: 内核配置会产生各种混淆和误导的效果。
例如，默认的 Python 3 内核配置将允许我启动 Jupyter notebook
在 Python 2 上运行:

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 后，来自 conda 的 Python 2
即使 Jupyter 显示“Python 3”，也将使用环境。
解: Don't use Python 2 ;-)