> ## Documentation Index
> Fetch the complete documentation index at: https://anaconda.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtimes

In Anaconda Notebooks, a runtime is what powers your code execution. You can think of a runtime as a conda environment connected to a language-specific kernel. Anaconda Notebooks provides several pre-configured runtimes that include the `ipykernel` package and all the packages from the latest Anaconda Distribution release, giving you immediate access to a comprehensive data science toolkit.

## Environments, kernels, and runtimes

### What is an environment?

An environment is a folder or directory that contains a specific collection of conda packages and their dependencies.

Working in separate environments allows you to maintain and run packages without interference from other collections of packages. For example, you might require separate conda environments to maintain distinct versions of Python based on distinct package dependencies.

### What is a kernel?

A kernel is a programming-language-specific process that interprets your code, runs it, and gives you the results. In Jupyter Notebooks, kernels allow users to run code in cells and receive immediate output. For example, `ipykernel` enables interactive computing in Python.

### What is a runtime?

A runtime in Anaconda Notebooks is a conda environment that has been associated with a specific kernel, enabling it to execute code. For an environment to be usable in JupyterLab, it must contain a kernel package (such as `ipykernel` for Python). Without this kernel association, JupyterLab cannot recognize the environment as an available option for running notebooks.

The default runtimes provided in Anaconda Notebooks come with the `ipykernel` package already installed, making them immediately available for your Python notebooks.

To add a kernel package to a custom environment and create your own runtime, see [creating custom runtimes](#creating-custom-runtimes).

## Using default runtimes

Custom runtimes often use large amounts of your limited Anaconda Notebooks storage space. Because of this, Anaconda provides a number of *read-only* default runtimes that contain all the packages from the latest release of Anaconda Distribution.

The default runtime naming convention is typically `anaconda-<YEAR>.<MONTH>-py<PYTHON_VERSION>`, which maps to Anaconda Distribution releases:

| Environment Name | Status | Description |
| :- | :- | :- |
| anaconda-2025.12-py312 | Live | Latest Anaconda Packages (stable & recommended) |
| anaconda-ai-2025.12-py312 | Live | Latest Anaconda Packages + AI Packages (stable & recommended) |

To list all available runtimes, run the following in a notebook cell:

```sh theme={null}
!conda info --envs
```

To list the current runtime's available packages, run the following in a notebook cell:

```sh theme={null}
!conda list
```

To search for a specific package in the current runtime environment, run the following in a notebook cell:

```sh theme={null}
!conda list <PACKAGE>
```

Comments

Replace \<PACKAGE> with the name of the package you'd like to search for.

## Creating custom runtimes

If you need a specific set of packages that are not included in one of our default runtimes, you can create your own runtime to customize to your needs.

> [!NOTE]
>
> Custom runtimes are stored using your dedicated, persistent Anaconda Notebooks cloud storage. This ensures the custom runtime remains available after your current session ends. Custom runtimes use your personal storage space and can easily get quite large, so *only include the packages you need*.

To create a new runtime:

1. Open a terminal from the Launcher, which you can access by selecting the  blue plus in the top-left corner of the  **File Browser**.

   ![The Anaconda Notebooks Launcher page with an arrow pointing to the Terminal option](https://mintcdn.com/anaconda-29683c67/ghAcs1Rv_eiLtpni/images/anaconda-platform/notebook_open_terminal.png?fit=max\&auto=format\&n=ghAcs1Rv_eiLtpni\&q=85\&s=277123c98f983352792bc3d585db87bb)

2. Create a new runtime by running the following command:

   ```sh theme={null}
   conda create --name <ENV_NAME> <PACKAGE> ipykernel
   ```

   Comments

   Replace \<ENV\_NAME> with a new name for your runtime environment.\\

   Replace \<PACKAGE> with the name of a package you want to install in your runtime environment.

   > [!NOTE]
   >
   > Adding `ipykernel` creates a Python runtime.

For more information about creating conda environments, see the [official conda docs](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).

### Creating a custom runtime from an environment.yml file

> [!NOTE]
>
> This feature is only available for the [local version of Toolbox](https://anaconda.com/docs/anaconda-platform/notebooks/anaconda-toolbox/local-toolbox.md).

If you have an existing `environment.yml` file, you can create a custom runtime by uploading it to an [Anaconda Toolbox project](https://anaconda.com/docs/anaconda-platform/notebooks/anaconda-toolbox/using-projects.md) and installing it directly from there.

#### Uploading an `environment.yml` file

1. Launch Anaconda Notebooks and select the left-side  **Anaconda Toolbox** icon.

2. Select **Manage Projects**.

3. Select  actions beside the project where you want to add your `environment.yml` file, then select  *Upload*.

4. Select the `environment.yml` file you want to create a custom runtime from. You can use any filename, but the file extension must be `.yml`.

   > [!WARNING]
   >
   > The dependencies list must include the `ipykernel` package.
   >
   > ***
   >
   > The `environment.yml` file must be in valid YAML format.
   >
   > ***
   >
   > If your `environment.yml` file includes a `name:` key, it will be removed during upload. You'll name your environment during installation.
   >
   > See the official [conda docs](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually) for more information on creating an `environment.yml` file.

5. Select **Upload to Project**.

See [Anaconda Projects](https://anaconda.com/docs/anaconda-platform/notebooks/anaconda-toolbox/using-projects.md) for more details on creating projects and uploading files.

#### Installing the custom runtime

1. Navigate to the project where you uploaded the `environment.yml` file.

2. Click **Install** beside the `environment.yml` filename.

   ![](https://mintcdn.com/anaconda-29683c67/ghAcs1Rv_eiLtpni/images/anaconda-platform/notebooks_install_button.png?fit=max\&auto=format\&n=ghAcs1Rv_eiLtpni\&q=85\&s=a71808fd6baa6056ba31614e19e9bc89)

3. In the modal that appears, choose a unique name for your environment, then select **Install**.

Once installation is complete, an  **Edit environment** button appears beside the filename.

Selecting  **Edit environment** lets you edit your environment with the [Gator environment manager](https://anaconda.com/docs/anaconda-platform/notebooks/anaconda-toolbox/toolbox-environments.md#editing-environments-with-gator).

Follow the steps in [Activating a runtime](#activating-runtimes) to activate your custom runtime.

If installation fails, select  **Copy error logs** beside the filename to troubleshoot. The most common issue is missing the required `ipykernel` package in your dependencies list.

> [!NOTE]
>
> It might take a minute for your custom runtime to be created and available for use. You might need to close and reopen your active notebook or refresh the browser for your new runtime to appear.

## Activating runtimes

There are a few locations from which you can activate a runtime:

> [tab] Terminal
>
> 1. Open a terminal from the Launcher.
>
> 2. Run the following command:
>
> ```sh theme={null}
> conda activate <ENV_NAME>
> ```
>
> Comments
>
> Replace \<ENV\_NAME> with the name of your runtime environment.

> [tab] Launcher
>
> Select the notebook displaying your custom runtime name.
>
> ![](https://mintcdn.com/anaconda-29683c67/ghAcs1Rv_eiLtpni/images/anaconda-platform/notebook_launcher-env.png?fit=max\&auto=format\&n=ghAcs1Rv_eiLtpni\&q=85\&s=fd27a9d12fef6855734b0a0f838b084b)

> [tab] Notebook
>
> Click the runtime in the top right, then switch to your desired runtime in the Select Runtime modal.
>
> ![](https://mintcdn.com/anaconda-29683c67/ghAcs1Rv_eiLtpni/images/anaconda-platform/notebook_kernel.png?fit=max\&auto=format\&n=ghAcs1Rv_eiLtpni\&q=85\&s=639991f5bb8abbb446bd37df211a2a38)

## Shutting down runtimes

It is best practice to shut down a runtime when you are finished working in it. To shut down a runtime, click **Kernels** in the top menu, then select the specific runtime you want to shut down or **Shut Down All**.

## Managing packages in a runtime

### Installing additional packages

Even after you've created a runtime, you can continue to add packages as needed. To add a package to a custom runtime:

1. Open a terminal from the Launcher.

2. Activate the runtime environment where you want to add the package by running the following command:

   ```sh theme={null}
   conda activate <ENV_NAME>
   ```

   Comments

   Replace \<ENV\_NAME> with the name of the runtime environment.

3. Install the packages you want to add to the environment:

   ```sh theme={null}
   conda install <PACKAGE>
   ```

   Comments

   Replace \<PACKAGE> with the name of the package you want to install.

Verify the package was installed by [activating the runtime](#activating-runtimes) and running the following command in a notebook cell:

```sh theme={null}
!conda list
```

### Updating packages

To update packages in your runtime:

1. Open a terminal from the Launcher.

2. Activate the runtime environment with the package you want to update by running the following command:

   ```sh theme={null}
   conda activate <ENV_NAME>
   ```

   Comments

   Replace \<ENV\_NAME> with the name of the runtime environment.

3. Update the package:

   ```sh theme={null}
   conda update <PACKAGE>
   ```

   Comments

   Replace \<PACKAGE> with the name of the package you want to update.

### Removing packages

To remove packages in your runtime:

1. Open a terminal from the Launcher.

2. Activate the environment with the package you want to remove by running the following command:

   ```sh theme={null}
   conda activate <ENV_NAME>
   ```

   Comments

   Replace \<ENV\_NAME> with the name of the runtime environment.

3. Remove the package:

   ```sh theme={null}
   conda remove <PACKAGE>
   ```

   Comments

   Replace \<PACKAGE> with the name of the package you want to remove.

## Removing custom runtimes

To remove a custom runtime:

1. Open a terminal from the Launcher.

2. Run the following command to remove the custom runtime:

```sh theme={null}
conda env remove --name <ENV_NAME>
```

Comments

Replace \<ENV\_NAME> with a the name of runtime environment you want to remove.

The custom runtime no longer appears in the kernel selector or Launcher.

## Troubleshooting

Troubleshoot

### "Missing ipykernel dependency" error

***

<details>
  <summary>Cause</summary>

  A `missing ipykernel dependency` error is caused by an environment dependency list not including the required `ipykernel` package.
</details>

***

<details>
  <summary>Solution</summary>

  To resolve this issue, add the `ipykernel` package to your environment's dependency list. For example:

  ```yml highlight {7} theme={null}
      channels:
      - defaults
      dependencies:
      - python=3.11
      - numpy
      - pandas
      - ipykernel
  ```
</details>

Troubleshoot

### Error when importing packages in Notebooks

***

<details>
  <summary>Cause</summary>

  The most common cause of errors is a lack of required package(s) installed in your environment. The default environment we provide, based on the Anaconda distribution, contains hundreds of the most common python packages for data science, but it doesn't include everything. You might need to create a custom environment to install the package you need.
</details>

***

<details>
  <summary>Solution</summary>

  **1. Make sure you have the right runtime selected**

  The default `anaconda-<YEAR>.<MONTH>-py<PYTHON_VERSION>` runtimes have a broad selection of packages, but you might have created a custom environment for your notebook. Separate environments are represented as "runtimes" in JupyterLab. You can view and switch between available runtimes by clicking the runtime name in the upper-right corner of the content pane.

  **2. List the packages available in an environment**

  If one of your imports is failing, start by verifying that the package is present in the runtime environment. You can view which packages are available in your current environment from the terminal by running `conda list`.

  To view packages in a specific environment, run `conda list --name <ENV_NAME>`.

  To see a list of available environments, run `conda info --envs`. An asterisk appears beside your current active environment.

  **3. Create a custom runtime**

  If none of the Anaconda provided environments contain the package(s) you need, create a [custom runtime](https://anaconda.com/docs/anaconda-platform/notebooks/notebook-runtimes.md#creating-custom-runtimes) for your notebook project.
</details>

Troubleshoot

### Custom runtime not appearing in Launcher or Assign a Runtime modal

***

<details>
  <summary>Cause</summary>

  The most common reason a runtime or environment is not appearing in the Launcher or Assign a Runtime modal is that it doesn't contain a kernel package (A kernel is a programming-language-specific process that interprets your code, runs it, and gives you the results. For example, the `ipykernel` package enables interactive computing in Python.).
</details>

***

<details>
  <summary>Solution</summary>

  For more information and instructions on installing a kernel package in your runtime/environment, see [Creating custom runtimes](https://anaconda.com/docs/anaconda-platform/notebooks/notebook-runtimes.md#creating-custom-runtimes).
</details>