Adding a customization

As Admin or Editor of a project, you can change the name, the description, and the hardware configuration of an environment template that you created. In addition, you can customize the software configuration of Jupyter notebook environment templates by adding packages from conda, mamba, or by using pip.

The mamba package manager is compatible with conda packages and supports most of the conda commands. This means that you can use conda to install or uninstall packages that were installed with mamba and vice versa. In many cases, the performance of mamba is better than conda, especially when using large repositories such as conda-forge. All newly created software customizations use mamba by default.

You customize the software configuration of Jupyter notebook environment templates through conda or mamba channels, or by using pip. This can be done by providing a list of conda or mamba packages, a list of pip packages, or a combination of these. When using conda or mamba packages, it is also possible to provide a list of additional channel locations through which the packages can be obtained.

Remember: If you customized the software configuration of an environment or plan to install additional libraries within a notebook, but do not change the configuration of conda, mamba or pip, the runtimes that are started with a customization must have public network access.

The default environment runtimes use the time zone where they were created, which is UTC time. If you want to use your local time in notebook functions, you need to download and modify the environment runtime configuration file to use your time zone. See Notebook returns UTC time and not local time for details about how to access and change the file.

Watch the following video to see how to create a custom environment for a Jupyter notebook.

To customize an environment template that you created:

1. Under Tool runtimes on the Environments page on the Manage tab of your project, check that no runtime is active for the environment template that you want to change. If a runtime is active, you must stop it before you can change the template.
2. Under Templates on the Environments page, select the template that you want to customize and add your changes. You can't change the language of an existing environment template.
3. If the template is a Juypter notebook environment template, you can create a software customization and specify the libraries to add to the standard packages that are available by default. You can also use the customization to upgrade or downgrade packages that are part of the standard software configuration.
4. Apply your changes.

The libraries that are added to an environment template through the customization aren't persisted. They are automatically installed each time the environment runtime is started. Note that if you add a library using pip install through a notebook cell and not through the customization, only you will be able to use this library. The library is not available to someone else using the same environment template.

You can use the provided templates to add custom libraries. Different templates exist for Python and for R. The following example shows the Python template:

# Modify the following content to add a software customization to an environment.
# To remove an existing customization, delete the entire content and click Apply.

# Add conda channels below defaults, indented by two spaces and a hyphen.
channels:
    - defaults

# To add packages through conda or pip, remove the comment on the following line.
# dependencies:

# Add conda packages here, indented by two spaces and a hyphen.
# Remove the comment on the following line and replace sample package name with your package name:
#  - a_conda_package=1.0

# Add pip packages here, indented by four spaces and a hyphen.
# Remove the comments on the following lines and replace sample package name with your package name.
#  - pip:
#    - a_pip_package==1.0

Important when customizing:

• Before you customize a package, verify that the changes that you are planning have the intended effect.

  • conda can report the changes required for installing a given package, without actually installing it. You can verify the changes from your notebook. For example, for the Plotly library:
    • In a Python notebook, enter: !conda install --dry-run plotly
    • In an R notebook, enter: print(system2("conda", args=c("install","--dry-run","r-plotly"), stdout=TRUE))
  • pip does install the package. However, restarting the environment after verification will remove the package. Here too, you can verify the changes from your notebook. For example, for the Plotly library:
    • In a Python notebook, enter: !pip install plotly
    • In an R notebook, enter: print(system2("pip", args="install plotly", stdout=TRUE))

• If you can get a package through conda from the default channels and through pip from PyPI, the preferred method is through conda from the default channels.

• The conda package manager does dependency checking when installing packages. This can be memory intensive if you add many packages to the customization. Ensure that you select an environment with sufficient RAM to enable dependency checking at the time the runtime is started. Otherwise, the software customization process might not be completed because of lack of memory.

• To prevent unnecessary dependency checking if you only want packages from one conda channel, exclude the default channels by removing defaults from the channels list in the template and adding nodefaults.

• In addition to the Anaconda main channel, many packages for R can be found in Anaconda's R channel. In R environments, this channel is already part of the default channels. So it does not have to be added separately.

• If you add packages only through pip or only through conda to the customization template, you must make sure that the dependencies key is not commented out in the template. A customization with a pip package that does not start with the dependencies key will generate an error.

• Wherever possible, provide a package version number, even if the version that you want to use is the latest and you expect the package manager to select it. Providing a version number significantly reduces time and memory consumption during package installation.

• When you specify a package version, use a single = for conda packages and a double == for pip packages. If the version that you specify causes a dependency conflict that the package manager can resolve, a different or newer version might be installed. If you don't specify a version, the package manager might pick the latest version available, or keep the version that is in the package.

• You cannot add arbitrary notebook extensions as a customization because notebook extensions must be pre-installed.