Examples of environment template customizations

Follow the examples that show how to add custom libraries through pip when you create an environment template, by using the provided templates for Python.

Note:
  • Starting with RT 25.1 and GenAI 25-A, customizations of Python environments use the requirements file format of pip.
  • From Runtime 25.1, customizing R-based environments is not supported any more. It is still possible to install packages directly from notebook code and create a custom image.
  • The process of creating custom Watson Machine Learning deployment runtimes might be different.

Adding pip packages

To add packages from the Python Package Index (PyPI), write the name of each package in a separate line. This instructs pip to install the latest versions of the packages which are missing in the environment. By default, packages that are pre-installed in the environment remain at the pre-installed version.

Example:

ibm-watsonx-ai
seawater
sklearn-pandas

As a result:

  • The latest versions of seawater and sklearn-pandas are installed
  • The pre-installed ibm-watsonx-ai package remains unchanged

Optionally, you can specify a package version by using ==, or version constraints by using >, >=, <, or <=. This syntax instructs pip to install a matching version, even if a different version is pre-installed.

Example:

ibm-watsonx-ai>=1.5.1
seawater==3.3.5
sklearn-pandas<2

As a result:

  • The ibm-watsonx-ai package is udated, if necessary
  • Version 3.3.5 of seawater is installed
  • The latest 1.x version of sklearn-pandas is installed

When applying a customization, pip considers the version constraints of the listed packages, and all of the dependencies of those packages. However, pip does not consider dependency constraints of other, pre-installed packages. As a result, it might overwrite pre-installed packages with versions that violate dependency constraints. In that case, pip prints an error message about incompatible dependencies, but considers the installation successful anyway.

Example:

pandas-profiling

When this line is added to requirements and applied to Runtime 25.1 for Python, pip installs pandas-profiling 3.2.0 and replaces several pre-installed packages with older versions. The installation process completes successfully but returns an error message.

Here's an example of the error message:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
autoai-ts-libs 5.0.5 requires joblib<1.5,>=1.4.2, but you have joblib 1.1.1 which is incompatible.
scikit-learn 1.6.1 requires joblib>=1.2.0, but you have joblib 1.1.1 which is incompatible.

The scikit-learn package is a dependency of many pre-installed packages, so your code might be affected, even if you're not using the package directly.

Customizing dependencies that are installed from pip in an air-gapped system

You might want to customize an environment in an air-gapped system that has no access to a repository server either locally or on the Internet. In this case, you can store the pip package in your project and specify the dependency as an absolute file path or a file:// URL.

Example:

/project_data/data_asset/your-package-1.7-py3-none-any.whl

Best practices

To avoid problems with missing packages and conflicting dependencies, start by manually installing the packages that you need through a notebook in a test environment. This way you can interactively check if packages can be installed without errors and dependency conflicts. Check the installation log output for messages such as:

Attempting uninstall: <package>

and

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.

followed by

<package version> requires <dependency constraint>, but you have ... <dependency version> which is incompatible.

If you are not using the reported packages with incompatible dependencies, either directly or indirectly, ignore the messages. Keep in mind that it is not always obvious whether you are using a package indirectly. For example, scikit-learn is a dependency of many pre-installed packages, even if you are not using it directly in your code.

If in doubt, revise the planned installation to resolve conflicts. After you verify that the packages install correctly and without problematic dependency violations, create a customization for your development or production environment and add the packages to the customization template.

Note: If you do not specify exact versions for all packages, and for all dependencies that they pull in, your customization might be affected by new versions getting published to PyPI. However, if you do specify exact versions, you will not automatically benefit from bug fixes in new versions.