Selecting a Starter Environment

Click the /environment folder to open the Environment Editor. Code Ocean uses Docker as the underlying tool to build and preserve the environment. When adding a package, the Environment Editor writes the information to a Dockerfile in the /environment folder.

Any edit made in the /environment folder triggers a change in the Dockerfile, which could result in a complete rebuild of the Docker image during a subsequent Reproducible Run or Cloud Workstation session. The wait time for the Docker image rebuild varies according to the number and complexity of packages installed.

Selecting a Starter Environment

The first thing to do when setting up the computation environment is to select a Starter Environment, which is also called the base image. The Environment Editor lists all the base images available and allows you to search by name, version, language, and tags.

In addition to determining the base software and package managers that will be available in the Capsule, the Starter Environment also determines if GPU or CPU compute resources will be available from within the Capsule. You can learn more about Compute Resources here.

Click Select to choose the base image. If the Starter Environment has multiple versions, you'll be able to choose a specific version.

You can view all of the packages installed in a Starter Environment along with their specific versions by clicking the drop-down menu to expand/fold the package managers that were installed.

Once you've selected a Starter Environment, clicking on a specific package manager icon as shown below will open an information box listing the packages installed via that package manager along with their versions.

Considerations When Choosing a Starter Environment

  • When not using a pre-installed language, use a base Ubuntu (16.04,18.04,20.04) environment.

  • When proprietary software, such as MATLAB or Stata is required, begin from an environment with the proprietary language.

  • When using a GPU, select an environment with GPU access. These are labeled accordingly, or will reference CUDA or a deep learning framework. You can filter for GPU machines by typing GPU in the search box.

Starter Environments for Specific Cloud Workstations

A helpful guide to selecting a Starter Environment could be choosing a relevant image associated with the Cloud Workstation you would like to work in. You can find the Cloud Workstation and the compatible language below.

Cloud WorkstationCompatible LanguageNote



Jupyter Lab/ Jupyter Notebook

mostly Python

You can install other kernels and use different languages





View the information box below for more detail.

Code-Server (VSCode)


Ubuntu Desktop (IGV,

Pytorch Desktop, etc.)


Requires use of Ubuntu Desktop Starter Environment





Requires use of Starter Environment with IGV installed (i.e. Ubuntu Desktop)



The MATLAB Cloud Workstation is a MATLAB interface that requires specific licenses and configurations set up in a MATLAB Starter Environment. To use the Matlab Cloud Workstation, you must choose MATLAB as your Starter Environment.

You need MATLAB credentials for executing Reproducible Runs and entering the Cloud Workstation. Visit this article for more details.

Dockerfiles In Code Ocean

When you first select your Starter Environment, a Dockerfile will be created in your environment folder. This file contains all the necessary commands that will be used to build your custom environment in your Capsule during computations. As more packages are added via the Environment Editor they will be synchronously added to the Dockerfile.

To manually customize your Capsule environment you can open the Dockerfile and unlock it. This is not recommended as it will permanently disable the environment editor and all subsequent changes to the environment will need to be made through the Dockerfile.