Skip to main content

Container Management

This guide explains how to manage containers in Gradient to ensure reproducible results when using Notebooks, Workflows, and Deployments.


Whether you are using Notebooks, Workflows, or Deployments, Gradient uses containers to provide a reproducible code execution environment.

In the case of notebooks, you can either use a preconfigured container or bring your own container. To learn more about that see the Notebook Runtimes page.

For Workflows and Deployments, you can either use public containers or private containers to set up your environment. With public containers (for example tensorflow/tensorflow:2.7.0-gpu-jupyter if you wanted to use a generic Tensorflow environment) then Gradient takes care of everything once you specify that in the image for your Workflow. Learn more about Workflow specs on the Workflow specs page.

You can also use a private container in your Workflows and Deployments. Gradient makes it easy for you to store and manage your private registry credentials which you can learn more about below.

Container Registries​

You can store credentials for future use in Gradient Resources through the Containers tab in your team settings. Access your team settings by clicking on your user image in the top right of the console.

Within the Containers tab you can add new container registries as well as edit or delete your existing registries.

Container Tab

Creating a new Container Registry Entry​

To create a new container registry, simply click the Add a New Container Registry button to get the entry form that will allow you to enter in the following information:

New Container Registry

  • name - This field is used to identify your registry in Paperspace resources and must be unique to your team.
  • url - The url associated with the registry hosting the container. For example, If you host your containers on Docker Hub your url would be This supports an entire base url so you can use self-hosted options or cloud registries like GoogleContainerRegistry (GCR) that path mount your registry endpoint like
  • namespace - This is the unique location within your registry outlining the loaction of your repository inclusive of namespace, sub-namespaces and tag.

Registry url and Namespace Example

  • username - This is your username login credential for the registry.
  • password - This is your password login credential for the registry. It is suggested you use an Access Token as your password.

Check this out to learn more about docker registries.

Google Container Registry Example​

This is an example of how to register a google container within Gradient. If the container that is trying to be a registered is then the following would need to be entered into each field:

Custom containers​

In Gradient, we can pull our own image from a container registry such as DockerHub. In this section we'll prepare a custom Docker container and bring that Container into Gradient by creating either a notebook, workflow, or deployment.


ProTip! Using a Custom Container does not require building one from scratch. See this article to access many freely available and up-to-date containers hosted on various container registries like Docker Hub, NGC, etc.

Build a Custom Container Locally​

Getting started​

A computer with DockerCE, NVIDIA-docker, and NVIDIA Drivers installed (if you don’t have a Linux machine, use a Paperspace Linux machine!).

From that machine, you'll need to be logged into your Docker Hub account in the terminal. docker login -u <username> -p <password>

You can make your own Docker file from scratch (see "Requirements for for Custom Notebooks" below) or use another as a basis, such as this example. For now, let's follow along this provided sample.

Adding a Docker file to a working directory on your system​

First, clone the repo to your local computer, and navigate to the corresponding directory in your terminal.

Open the Docker file into your IDE of choice, and make edits as necessary. The provided Docker file sampled above pulls from DockerHub a Paperspace-made TensorFlow image designed to run TensorFlow 2.0 for GPUs on Gradient. You can do so with the FROM instruction.

Example: FROM

Once your Dockerfile is written, save it, and navigate back to the terminal.

Building the Docker image​

Now that the Docker file is written, we can build the image by running:

docker build -t <Name of image>

For the example file above, you could enter:

docker build test-container

Once you have created the image, you need to tag it so that it can be added to Docker Hub. Tag the image using the image id, your Docker Hub username, and a name for the image in the following format:

docker tag <Image id> <Docker username>/test-container:<Tag>

Pushing to Docker Hub​

Now that we have created and tagged out container, we can push it to Docker Hub for use with our Gradient resources. Use the following docker push command to do so:

docker push <Docker username>/test-container:<tag>

Requirements to use with Custom Notebooks ​

The following should be included in your Docker file to ensure the Notebook will set up and run properly.

  • Python: RUN apt-get update && apt-get install -y python3 python3-pip
  • Jupyter and all of Jupyter's dependencies: RUN pip install jupyterlab (For more details, see
  • Jupyter must be run on port 8888 and connections from ip address must be allowed.
  • If running jupyter notebook, the following flags must be included in the Command field to support the Gradient Notebooks IDE:
    • --no-browser --NotebookApp.trust_xheaders=True --NotebookApp.disable_check_xsrf=False --NotebookApp.allow_remote_access=True --NotebookApp.allow_origin='*'
  • If running jupyter lab, these flags should be used in the Command field instead:
    • --no-browser --LabApp.trust_xheaders=True --LabApp.disable_check_xsrf=False --LabApp.allow_remote_access=True --LabApp.allow_origin='*'

Bringing your Custom Container to Gradient​

After you've pushed your custom container to Docker Hub, NGC, etc., or you found a public container that is already there, it's time to pull it into Gradient!

Notebooks ​

Click the advanced options toggle on the notebook create a notebook page. Follow the rest of the steps here to create your Notebook by selecting your machine type, naming your notebook, and clicking Create.


Just specify the path of the container e.g., paperspace/gradient-sdk from within a Workflow step using image. Learn more here. Click the advanced options toggle on the notebook create a notebook page. Follow the rest of the steps here to create your Notebook by selecting your machine type, naming your notebook, and clicking Create.


On the Choose Container step, navigate to the custom container tab and fill out the form. Note: A username and password must be provided for private Docker images.