Skip to content

Custom Environment

Adding Python Packages and Creating Custom Environments

Many commonly used Python packages are preinstalled in the provided images. If additional packages are needed, they can be installed manually.

The recommended installation method depends on your use case:

  • To add a package to the environment of the currently selected notebook kernel, use %pip install package_name in a notebook.
  • For project-specific dependencies or packages with complex requirements, create a dedicated Conda environment or virtual environment (venv).
  • Do not install or upgrade core Jupyter packages with pip install --user. Packages installed in your persistent home directory can override the centrally managed JupyterHub packages and cause compatibility problems.

Core Jupyter packages include jupyterlab, notebook, jupyter-server, jupyter-server-proxy, and jupyterhub.

There are three supported ways to add additional Python packages:

1. Using Pip

To install a package into the environment used by the currently selected notebook kernel, run the following command in a notebook code cell:

%pip install package_name

The %pip magic runs pip in the environment associated with the current kernel. In the default Python kernel, this environment is read-only, so pip installs into your home directory under ~/.local instead, which is the same as --user. These packages persist across server restarts and apply to every notebook using the default kernel. You may need to restart the kernel after installation.

This method is suitable for simple project packages. For isolated, reproducible, or more complex environments, use a dedicated Conda environment or venv instead.

Do not install core Jupyter packages with --user

JupyterHub provides centrally managed versions of JupyterLab, Notebook, Jupyter Server, and related packages. Installing or upgrading these packages with python -m pip install --user, or with %pip install in the default kernel, can override the managed versions and cause compatibility problems.

In particular, do not install jupyterlab, notebook, jupyter-server, jupyter-server-proxy, or jupyterhub with --user.

If you experience extension warnings, missing launcher entries, or other unexpected behavior, see Troubleshooting user-installed Jupyter packages.

2. Using Conda

Many default system directories are read-only, so you won’t be able to directly install packages into the base environment. Instead, you can create a new conda environment (see the section below for instructions) where you can install and manage your own packages.

Create new conda environment as a kernel in JupyterHub

Prerequisites

Before installing new packages, you need to initialize your shell for conda. This step ensures that conda commands work properly in your terminal. To do this, open a terminal and run the following commands:

conda init
bash
Installation

To create a new conda environment with Python 3.11 and the pandas package, follow these steps. The ipykernel package is also required to use this environment as a kernel in Jupyter. 1. Open a terminal in JupyterHub. 2. Create the environment by running:

conda create --name py311 python=3.11 ipykernel pandas -y
3. Activate the environment:
conda activate py311
4. Install the environment as a Jupyter kernel so you can use it in notebooks:
python -m ipykernel install --user --name py311 --display-name "Python (py311)"
5. Reload the JupyterHub page.

The new environment should now be available as a selectable kernel when you open or create a new notebook.

Key Points to Note:

  • Conda init is required only once to set up your shell for conda.
  • You can replace py311, pandas, or the Python version with your desired environment name, packages, or Python version.
  • The kernel name "Python (py311)" is the name that will appear in Jupyter when selecting the kernel. You can customize it to any name you prefer.

3. Using venv

Python virtual environments (venv) are a lightweight alternative to Conda environments. Create them in your home directory so that they persist across server restarts:

  1. Open a terminal in JupyterHub.
  2. Create and activate the environment. To also use the packages preinstalled in the image, add --system-site-packages to the first command:
    python -m venv ~/venvs/myenv
    source ~/venvs/myenv/bin/activate
    
  3. Install ipykernel and your packages:
    pip install ipykernel package_name
    
  4. Register the environment as a Jupyter kernel and deactivate it:
    python -m ipykernel install --user --name myenv --display-name "Python (myenv)"
    deactivate
    
  5. Reload the JupyterHub page.

"Python (myenv)" now appears in the launcher and in the kernel selector.

To remove an environment:

jupyter kernelspec uninstall -y myenv
rm -rf ~/venvs/myenv

Key Points to Note:

  • A venv sees neither the packages preinstalled in the image nor the packages in ~/.local. Packages installed in a venv therefore cannot override the centrally managed Jupyter packages.
  • A venv created with --system-site-packages also sees the preinstalled packages and your packages in ~/.local. Packages installed in the venv take precedence.
  • Virtual environments count toward your home directory storage limit.

Running Commands and GUI Applications in the Terminal

You can also run any command or script by opening a terminal in JupyterHub. As a user, you have permissions to run files with your user privileges.

JupyterHub NRW also provides an X11 terminal (Konsole) that allows you to access GUI-based applications as well. This enables you to run programs that require a graphical interface, such as scientific software, visual tools, or data visualization applications.