Package for managing conda environment-based kernels inside of Jupyter
Clone or download
Latest commit a34d4b4 Sep 6, 2018

README.md

Travis Status AppVeyor status Anaconda-Server Badge
conda install jupycon/label/dev::nb_conda_kernels Anaconda-Server Badge
conda install defaults::nb_conda_kernels Anaconda-Server Badge
conda install conda-forge::nb_conda_kernels Anaconda-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 then 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.

Limitations

This extension works only with Jupyter notebooks and JupyterLab. Unfortunately, it does not currently work with Jupyter Console, nbconvert, and other tools. This is because these tools were not designed to allow for the use of custom KernelSpecs.

A new kernel discovery system is being developed for Jupyter 6.0 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.

Configuration

This package introduces two additional configuration options:

  • env_filter: Regex to filter environment path matching it. Default: None (i.e. no filter)
  • name_format: String name format; '{0}' = Language, '{1}' = Kernel. Default: '{0} [conda env:{1}]'

Development

  1. Install Anaconda or Miniconda.

  2. Create a development environment. Node.JS packages PhantomJS and CasperJS are used for testing, so installation requires both conda and npm:

    conda create -n nb_conda_kernels python=YOUR_FAVORITE_PYTHON
    # Linux / Mac
    conda activate nb_conda_kernels
    # Windows
    activate nb_conda_kernels
    # Install the package and test dependencies
    conda install --file requirements.txt
    # Install PhantomJS and CasperJS
    npm install
  3. Install the source package in development mode.

    python setup.py develop
    python -m nb_conda_kernels.install --enable

    Note: there is no longer any need to supply a --prefix argument to the installer.

  4. In order to properly exercise the package, the tests assume the existence of ipykernel in the base/root conda environment, and at least one conda environment with the R kernel. For example:

    conda install -n root ipykernel
    conda create -n nbrtest r-irkernel
  5. To run all of the tests, the Node environment must be activated. The easiest way to do this is to use our npm test command:

    npm run test

    If you prefer to skip the Node-based tests, you can run nose directly, skipping the test_notebook module:

    nosetests --exclude=test_notebook
    

Changelog

2.2.0 (in development)

  • Perform full activation of kernel conda environments
  • Discover kernels from their kernel specs, enabling the use of kernels besides Python and R
  • Support for spaces and accented characters in environment paths, with properly validating kernel names
  • Configurable format for kernel display names

2.1.1

  • move to a full conda-based approach to build and test
  • add support for conda 4.4 and later, which can remove conda from the PATH

2.1.0

  • add support for regex-based filtering of conda environments that should not appear in the list

2.0.0

  • change kernel naming scheme to leave default kernels in place

1.0.3

  • ignore build cleanup on windows due to poorly-behaved PhantomJS processes

1.0.2

1.0.1

  • minor build changes

1.0.0

  • update to notebook 4.2