Import & export
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.
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.
pip install <package_name> or
apt install <library>, either in the terminal or with the
! prefix in a notebook. 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.
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. Read more.
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. 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.
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.
Deepnote supports any Python version >= 3.6. You can pick 3.7, 3.8 and 3.9 from the dropdown (as shown above), or use a custom Docker image for more flexibility.
You can also pick from R 3.5.2 and 4.0.3, or use a custom Docker image for a more flexibility. 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.
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.
- 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.
When you add a custom image in your personal project, you will be able to use it in all other projects as well. When you add a custom image in a team project, all team members will be able to use it in other team projects as well.
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.
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.
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