This page outlines how to configure and start the notebook environment.

## Manage the notebook environment {: #manage-the-notebook-environment }

Before you create and execute code, click the environment icon to configure the notebook's environment. The [environment image](#built-in-environment-images) determines the coding language, dependencies, and open-source libraries used in the notebook. The default image for the DataRobot Notebooks is a pre-built Python image. To see the list of all packages available in the default image, hover over that image in the **Environment** tab:

{% if section(page, "dr-notebooks") %}

![](images/nb-8.png)

{% else %}

![](images/wb-nb-8.png)

{% endif %}

The screenshot and table below outline the configuration options available for a notebook environment.

{% if section(page, "dr-notebooks") %}

![](images/nb-6.png)

|  | Element | Description |
|---|---|---|
| ![](images/icon-1.png) | Start environment toggle | Starts or stops the notebook environment's kernel, which allows you to execute the notebook's code cells. |
| ![](images/icon-2.png) | Resource type | Represents a machine preset, specifying the CPU and RAM you have on your machine where the environment's kernel runs. |
| ![](images/icon-3.png) | Image | Determines the coding language and associated libraries that the notebook uses.  |
| ![](images/icon-4.png) | Runtime | Indicates the CPU usage, RAM usage, and elapsed runtime for the notebook's environment during an active session. |
| ![](images/icon-5.png) | Session timeout | Limits the amount of inactivity time allowed before the environment stops running and the underlying machine is shut down. The default timeout on inactivity is 60 minutes, and the maximum configurable timeout is 180 minutes. |

{% else %}

![](images/wb-nb-6.png)

|  | Element | Description |
|---|---|---|
| ![](images/icon-1.png) | Start environment toggle | Starts or stops the notebook environment's kernel, which allows you to execute the notebook's code cells. |
| ![](images/icon-2.png) | Resource type | Represents a machine preset, specifying the CPU and RAM you have on your machine where the environment's kernel runs. |
| ![](images/icon-3.png) | Environment | Determines the coding language and associated libraries that the notebook uses.  |
| ![](images/icon-4.png) | Runtime | Indicates the CPU usage, RAM usage, and elapsed runtime for the notebook's environment during an active session. |
| ![](images/icon-5.png) | Session timeout | Limits the amount of inactivity time allowed before the environment stops running and the underlying machine is shut down. The default timeout on inactivity is 60 minutes, and the maximum configurable timeout is 180 minutes. |

{% endif %}

To begin a notebook session where you create and run code, start the environment by toggling it on in the toolbar.

{% if section(page, "dr-notebooks") %}

![](images/nb-49.png)

{% else %}

![](images/wb-nb-49.png)

{% endif %}

Wait a moment for the environment to initialize, and once it displays the **Started** status, you can begin editing.

{% if section(page, "dr-notebooks") %}

![](images/nb-50.png)

{% else %}

![](images/wb-nb-50.png)

{% endif %}

If you upgrade any of the existing packages in the notebook environment during your session and want the upgraded version to be recognized, you need to restart the kernel. To do so, click the circular arrow icon in the toolbar.

Note that restarting the kernel is different than restarting the environment session: when you stop the environment session (using the session toggle), this will stop the container your notebook is running in. The notebook state and any packages installed at runtime will be lost, as the next time you start the session, a new container will be spun up.

{% if section(page, "dr-notebooks") %}

![](images/nb-51.png)

{% else %}

![](images/wb-nb-51.png)

{% endif %}

Note that the session will automatically shut down on inactivity when the timeout is reached. The session is considered inactive when the notebook has no running cells and no changes have been made to the notebook contents in the time set by the session timeout value.

{% if section(page, "dr-notebooks") %}

From the notebook dashboard, you can view the status of all notebook environments.

![](images/nb-7.png)

!!! note
    Note that you can only run up to two active notebook sessions at the same time.

{% endif %}

## Custom environment images {: #custom-environment-images }

DataRobot Notebooks is integrated with [DataRobot custom environments](custom-model-environments/index), allowing you to define reusable custom Docker images for running notebook sessions. You can create a custom environment to use for your notebook sessions if you want full control over the environment, and to leverage reproducible dependencies beyond those available in the built-in images.

!!! info "Availability information"
    Custom environments for notebooks is off by default. Contact your DataRobot representative or administrator for information on enabling this feature.

    <b>Feature flag:</b> Enable Notebooks Custom Environments

### Create a custom environment {: #create-a-custom-environment }

When [creating a custom environment](custom-environments#create-the-environment), note that only Python and R custom environments are supported for DataRobot Notebooks. Additionally, in the **Environment type** field, select the **Notebooks** option to use the environment with DataRobot Notebooks.

![](images/nb-custom-env-1.png)

DataRobot strongly recommends accessing the [notebook built-in environment templates](https://github.com/datarobot/datarobot-user-models/tree/master/public_dropin_notebook_environments){ target=_blank } to reference the requirements needed to create a Docker context that is compatible with running DataRobot Notebooks.

After you create a custom environment, you can click the **Current Notebooks** tab to view a list of any DataRobot notebooks that are configured to use versions of the custom environment as the notebook container image.

### Use a custom environment for a notebook session {: #use-a-custom-environment-for-a-notebook-session }

To use a custom environment as the image to run for a notebook container session, open the notebook you want to use and navigate to the **Environment** tab (![](images/icon-env.png)) in the notebook sidebar.

In the **Environment** field dropdown, you can see all of the custom environments that you have access to that are compatible with DataRobot Notebooks. Select the custom environment you’d like to use. In the **Version** field, you can select the version of the environment to use. By default, the latest version of the environment is selected. Once you’ve configured your environment selection, you can start the notebook session.

![](images/nb-custom-env-2.png)

### Built-in environment images {: #built-in-environment-images }

DataRobot maintains a set of built-in Docker images that you can select from to use as the container image for a given notebook.

DataRobot provides the following images:

* Python 3.9 image: Contains Python version 3.9, the [DataRobot Python client](https://datarobot-public-api-client.readthedocs-hosted.com/en/latest/index.html){ target=_blank }, and suite of common data science libraries.

* Python 3.8 image: Contains Python version 3.8, the DataRobot Python client, and suite of common data science libraries. Previously, this image was needed to work with Snowflake as certain included libraries [Snowflake Python Connector](https://docs.snowflake.com/en/user-guide/python-connector.html) and [Snowpark](https://docs.snowflake.com/en/developer-guide/snowpark/index.html) required Python 3.8. These libraries now support later versions of Python so this image is being considered for deprecation

* R 4.3 image: Contains R version 4.3, the [DataRobot R client](https://cran.r-project.org/web/packages/datarobot/index.html){ target=_blank }, and a suite of common data science libraries.

## Environment variables {: #environment-variables }

If you need to reference sensitive strings in a notebook, rather than storing them in plain text within the notebook you can use environment variables to securely store the values. These values are stored encrypted by DataRobot. Environment variables are useful if you need to specify credentials for connecting to an external data source within your notebook, for instance.

Whenever you start a notebook session, DataRobot sets the notebook's associated environment variables in the container environment, so you can reference them from your notebook code using the following code:

=== "Python"

    ```
    import os
    KEY = os.environ['KEY']  # KEY variable now references your VALUE
    ```

=== "R"

    ```
    KEY = Sys.getenv("KEY")
    ```

To access environment variables, click the lock icon in the sidebar.

{% if section(page, "dr-notebooks") %}

![](images/nb-15.png)

{% else %}

![](images/wb-nb-15.png)

{% endif %}

Click **Create new entry**.

In the dialog box, enter the key and value for a single entry, and provide an optional description.

{% if section(page, "dr-notebooks") %}

![](images/nb-16.png)

{% else %}

![](images/wb-nb-16.png)

{% endif %}

If you want to add multiple variables, select **Bulk import**. Use the following format on each line in the field:

`KEY=VALUE # DESCRIPTION`

{% if section(page, "dr-notebooks") %}

![](images/nb-17.png)

{% else %}

![](images/wb-nb-17.png)

{% endif %}

!!! note
    Any existing environment variable with the same key will have its value overwritten by the new value specified.

When you have finished adding environment variables, click **Save**.

## Edit existing variables {: #edit-existing-variables }

You can also edit and delete a notebook’s associated environment variables from the **Environment variables** panel:

{% if section(page, "dr-notebooks") %}

![](images/nb-18.png)

{% else %}

![](images/wb-nb-18.png)

{% endif %}

* Click the pencil icon on a variable to edit it.
* Select the eye icon to view a hidden value.
* Click the trash can icon to delete a variable.
* Click **Insert all** to insert a code snippet that retrieves all of the notebook's environment variables and includes them in the notebook.
