Working with files
Connecting to data sources
Coding and analysis tools
Security and privacy
Deepnote for education
Custom environments and install new packages
By default, Deepnote projects run in containers on Debian Buster with Python 3.9, and a number of pre-installed packages. It’s meant to "just work" for the majority of projects, and if you’re a beginner, you most likely don’t need to configure anything. However, for advanced users, Deepnote offers a large amount of flexibility.
Customizing the environment
There are 3 major ways of installing both system-level dependencies and Python packages: installing them ad-hoc, using a start-up script, and by changing the underlying image.
1. Installing new packages via ad-hoc installation (pip or apt)
pip install <package_name> or
apt install <library>, either in the terminal or with the
! prefix in a notebook.
If you are in a conda environment, you can also run
conda install <package_name>.
This will immediately install the library for you to use. Note that when the hardware restarts, the environment will revert back to the default state.
Deepnote persists everything in your work folder—the one you see in the Files section in the right sidebar. It’s mounted to
/work and sym-linked to
/root/work, and for backwards compatibility also to
/home/<username>/work. Everything outside of this folder is removed when your hardware restarts.
2. Initialization script (
Whenever your project hardware starts up, we run some initializing Python code. This code is in the
init.ipynb notebook which can be accessed from the environment tab. By default, it installs packages from
./requirements.txt. You can read more about project initialization here.
Deepnote maintains a number of supported runtime environments, including a few versions of Python and R. You can simply pick one from the dropdown in the right sidebar as shown below. The hardware will then be restarted to enable the newly selected environment.\
If you need to customize your environment further for example by installing additional libraries or binaries, you have two ways of doing so. You can either (1) use an environment defined by a local Dockerfile or (2) you can point to a hosted Docker image that you would like to use. These are explained in more detail below.
This option will use environment described by the
Dockerfile file in the root of your project. Deepnote takes care of building and hosting the Docker image. To learn more about our Anaconda Docker image, refer to the conda environment docs.
A common use-case is to extend one of the above mentioned supported images by specifying the
FROM directive at the beginning of the file (such as
FROM deepnote/python:3.7) and then adding what you need. For example, a Dockerfile that will install the dependencies needed for OpenCV would look like:
FROM deepnote/python:3.7 RUN apt update && apt install -y ffmpeg libsm6 libxext6
If you have a local Dockerfile you'd like to use, just select Local ./Dockerfile from the Environment dropdown in the right sidebar (shown above). Read more about using a local Docker file in the "Building images" section below.
Point to a hosted Docker image
You can also pull in a Docker image from somewhere else. This is an extremely powerful feature because it allows you to pick from any of the preconfigured images in public repositories such as Dockerhub.
There are some requirements that the images need to meet to run in Deepnote. Read more below in this article.
Those on the Pro plan can also use their own private image repositories (we support Docker Hub, Google Container Registry and Amazon ECR). To use a private image repository, create an integration for the respective provider and enter your credentials. Then, connect the integration to any project where you wish to use your private Docker images.
Different Python versions
Deepnote supports any Python version >= 3.6. You can pick 3.7, 3.8, 3.9, and 3.10 from the dropdown (as shown above), or use a custom Docker image for more flexibility.
In the environment section (see the right sidebar), you can pick from different versions of R; however, we recommended choosing the
deepnote/ir_with_libs image. This will install R 4.2 and many common data science libraries for you (see the image details here). To learn more about using R in Deepnote, click here.
Deepnote's R support is still in its early days. Some features don't work yet. This includes including the variable explorer, SQL cells, and input cells.
Custom Docker images
You can run Deepnote on any Docker image, as long as it satisfies a few requirements. Just add a new image from a public repository, optionally give it a name, and it’s ready to use. The initial load might take slightly longer while the image is being downloaded.
Custom image requirements
- There must be an installation of Python with version >= 3.6, which can be referenced using the
- Must be built for
linux/amd64platform. For example, if you are running M1 mac, you should build the image with
- There must be an installation of
pip, configured to install packages into a location visible to
- The image must contain
If you want to run a different kernel, read more here.
Sharing custom images
When you add a custom image to a project, you and other workspace members will be able to re-use it in other projects as well.
Building images in Deepnote
Sometimes you may wish to make modifications to the default source image. You can build in these changes directly in Deepnote, just pick the Local ./Dockerfile from the Environment dropdown in the right sidebar.
Even though the definition file is called "Dockerfile", it does not support the full syntax you might be used to. In order to stay compatible with Deepnote, you can only use the following statements:
- FROM clause. You can start from any public base image, or pick one of the Deepnote environments as a base.
- RUN clause. This allows you to run arbitrary commands, for example, install libraries or tools you are using in your project. The commands run as root, so you don't need to use sudo.
- ENV clause. You can use this to set environment variable or to define the default jupyter kernel for creating new notebook files.
The time-out for builds is 10 minutes for free projects and 60 minutes for the paid ones.
Building images locally or with automated builds
You can also use images built locally or from a different platform, like your CI/CD system. Note, the local builds allow for faster iteration thanks to layer caching. You will still need to host the image on an online registry.
Check out this guide for a quickstart on building images locally and hosting them on Docker Hub.
Duplicating projects with a custom environment
The duplicates of a project with a custom environment will retain the custom environment configuration in these cases:
- When the project is using one of the default Deepnote environments
- When the project is using the local Dockerfile built within Deepnote
- (Coming soon) When the project gets duplicated within the team space