How to Use Custom Containers in Gradient Notebooks

Gradient uses containers to create consistent, reproducible environments for your workloads. Containers define the runtime and dependencies that Gradient uses when running your code.

You can use one of Gradient’s preconfigured containers, a public container image, or your own private image.

Add a Container Registry

You can store credentials for private container registries in Gradient so they can be reused across your environment.

In the Gradient console, in the top-right corner, click your profile image, select Team Settings, and then click the Containers tab.

From the Containers page, you can add, edit, or delete registry connections.

Create a Container Registry Connection

To create a registry connection, click Add Registry, select the registry type, and then type the required credentials for that registry.

After saving, you can reference the registry by name in your configuration file or container spec.

Configure Container Registry

The following examples show how to connect different container registries to Gradient. Each example outlines the credentials required for that registry and how to reference the registry name in your container configuration.

image: registry.digitalocean.com/your-registry-name/image:tag
containerRegistry: My-Example-DO-Registry

image: example-repository/streamlit-app:latest
containerRegistry: My-Example-DockerHub-Repository

image: us-west1-docker.pkg.dev/project-name/repo-name/image:tag
containerRegistry: My-Example-GCR

image: ghcr.io/example-org/streamlit-app:latest
containerRegistry: My-Example-GHCR

image: example-registry.azurecr.io/streamlit-app:latest
containerRegistry: My-Example-ACR

See Notebook Runtimes for available options and templates.

Build a Custom Container

You can build a custom Docker container and push it to a container registry, such as Docker Hub, DigitalOcean Container Registry, or NGC, for use in Gradient. Custom containers let you define the exact runtime, dependencies, and environment needed for your workloads.

Before you use a custom container, you need to create a machine with Docker CE, NVIDIA Docker, and NVIDIA drivers installed. These tools ensure your image is compatible with the GPU runtimes and dependencies that Gradient uses when running containers.

If your local environment doesn’t meet these requirements, you can use a Paperspace Linux-based machine instead.

Access Your Docker Hub

To access your Docker Hub, run the following command with your Docker Hub credentials like this:

docker login -u <username> -p <password>

Create a Dockerfile

After accessing your Docker Hub, create a Dockerfile to define your container’s environment, dependencies, and startup commands like this:

git clone https://github.com/gradient-ai/tensorflow-python
cd tensorflow-python

In this example, the image is a Paperspace-built TensorFlow 2.0 container optimized for GPU workloads.

You can modify the Dockerfile to include any additional dependencies or setup steps your application requires.

Build the Image

In the same directory as your Dockerfile, build your image with the following command:

docker build -t test-container .

Then, tag your image before pushing it to a registry like this:

docker tag test-container <docker-username>/test-container:latest

Push the Image

To push the image to your container registry, run the following command:

docker push <docker-username>/test-container:latest

Reference Your Custom Container

After your container is pushed to a registry, reference it in your configuration file or container spec like this:

image: <docker-username>/test-container:latest
containerRegistry: <your-registry-name>

Gradient then automatically pulls and runs the container in your environment.

Bring Your Custom Container to Notebooks

You can run custom containers in Gradient Notebooks to define your own runtime environment and dependencies.

To use a custom container, in the Gradient console, go to the Notebook Create page, and then click the Advanced options toggle.

In the Container field, specify the path to your container image (for example, paperspace/gradient-sdk), and then complete the remaining creation steps.

For more details on configuring Notebook environments, see Notebook Runtimes.

Run a Custom Container in Gradient Notebooks

To run a custom container in a Gradient Notebook, the image must include Python and JupyterLab. These components are required for the Notebook to launch and function properly.

Add the following commands to your Dockerfile to ensure compatibility:

# Install Python
RUN apt-get update && apt-get install -y python3 python3-pip

# Install JupyterLab
RUN pip install jupyterlab

For more information, see the Jupyter installation guide.