Home

Awesome

Build and test the packageAnaconda-Server Badge
conda install jupycon/label/dev::nb_conda_kernelsAnaconda-Server Badge
conda install defaults::nb_conda_kernelsAnaconda-Server Badge
conda install conda-forge::nb_conda_kernelsAnaconda-Server Badge

nb_conda_kernels

This extension enables a Jupyter Notebook or JupyterLab application in one conda environment to access kernels for Python, R, and other languages found in other environments. When a kernel from an external environment is selected, the kernel conda environment is automatically activated before the kernel is launched. This allows you to utilize different versions of Python, R, and other languages from a single Jupyter installation.

The package works by defining a custom KernelSpecManager that scans the current set of conda environments for kernel specifications. It dynamically modifies each KernelSpec so that it can be properly run from the notebook environment. When you create a new notebook, these modified kernels will be made available in the selection list.

Installation

This package is designed to be managed solely using conda. It should be installed in the environment from which you run Jupyter Notebook or JupyterLab. This might be your base conda environment, but it need not be. For instance, if the environment notebook_env contains the notebook package, then you would run

conda install -n notebook_env nb_conda_kernels

Any other environments you wish to access in your notebooks must have an appropriate kernel package installed. For instance, to access a Python environment, it must have the ipykernel package; e.g.

conda install -n python_env ipykernel

To utilize an R environment, it must have the r-irkernel package; e.g.

conda install -n r_env r-irkernel

For other languages, their corresponding kernels must be installed.

Use with nbconvert, voila, papermill,...

This extension works out of the box only with Jupyter notebooks and JupyterLab.

A new kernel discovery system is being developed that should enable the wider Jupyter ecosystem to take advantage of these external kernels. This package will require modification to function properly in this new system.

But you can activate a workaround for it to work with Jupyter Console, nbconvert, and other tools. As these tools were not designed to allow for the use of custom KernelSpecs, you can set the configuration parameter kernelspec_path to tell this extension to add dynamically the conda environment to the kernel list. To set it up:

  1. Create a configuration file for jupyter named jupyter_config.json in the folder returned by jupyter --config-dir.
  2. Add the following configuration to install all kernel spec for the current user:
{
  "CondaKernelSpecManager": {
    "kernelspec_path": "--user"
  }
}
  1. Execute the command (or open the classical Notebook or JupyterLab UI):
python -m nb_conda_kernels list
  1. Check that the conda environment kernels are discovered by jupyter:
jupyter kernelspec list

The previous command should list the same kernel than nb_conda_kernels.

You are now all set. nbconvert, voila, papermill,... should find the conda environment kernels.

Configuration

This package introduces two additional configuration options:

In order to pass a configuration option in the command line use python -m nb_conda_kernels list --CondaKernelSpecManager.env_filter="regex" where regex is the regular expression for filtering envs "this|that|and|that" works. To set it in jupyter config file, edit the jupyter configuration file (py or json) located in your jupyter --config-dir

{
  "CondaKernelSpecManager": {
    "env_filter": "regex"
}

Development

  1. Install Anaconda or Miniconda. If you are on Windows, make sure you have a Bash shell on your path.

  2. Create and activate the testbed environment by running

    source testbed/build.sh

    This performs the following steps:

    • Builds a new root conda environment in ../nbckdev, or in CONDA_ROOT if that environment variable is defined. (Note that the default directory ../nbckdev is at the same level as your copy of the repository. This is because we do not want conda build to try to capture the entire testbed into the build workspace.)
    • Installs conda-build and the necessary dependencies to locally test the package
    • Installs the package in development mode
    • Creates a set of environments that the test scripts require to fully exercise the package.
    • Activates the environment, including a deliberate scrubbing of variables and paths from your primary conda environment.

    If the environment already exists, testbed/build.sh will quickly exit, so it is safe to run it if you are not sure.

  3. Run pytest to test the package.

    pytest tests

  4. The root environment of our testbed uses Python 3.7. If you would like to test nb_conda_kernels with a different Python version, create a new child environment:

    conda create -n ptest python=... notebook pytest pytest-cov requests mock
conda install backports.functools_lru_cache # python 2 only
conda activate ptest
pip install -e .
python -m nb_conda_kernels.install --enable
pytest tests

Changelog

2.3.2

2.3.1

2.3.0

2.2.4

2.2.3

2.2.2

2.2.1

2.2.0

2.1.1

2.1.0

2.0.0

1.0.3

1.0.2

1.0.1

1.0.0