> For the complete documentation index, see [llms.txt](https://documentation.dnanexus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.dnanexus.com/user/jupyter-notebooks/running-dxjupyterlab.md).

# Running JupyterLab

Learn to launch a JupyterLab session on the DNAnexus Platform, via the JupyterLab app.

{% hint style="info" %}
JupyterLab is accessible to all users of the UK Biobank Research Analysis Platform and Our Future Health Trusted Research Environment.

For DNAnexus Platform users, a license is required to access JupyterLab. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

## Running from the UI

1. In the main menu, navigate to **Tools** > **JupyterLab**. If you have used JupyterLab before, the page shows your previous sessions across different projects.
2. Click **New JupyterLab**.
3. Configure your JupyterLab session:
   * Specify the session name and select an instance type.
   * Choose the project in which to run the JupyterLab session.
   * Set the session duration after which the environment automatically shuts down.
   * Optionally, provide a snapshot file to load a previously saved environment.
   * If needed, enable Spark Cluster and set the number of nodes.
4. Select a feature option based on your analysis needs:
   * `PYTHON_R` (default): Python3 and R kernels and interpreters
   * `ML`: Python3 with machine learning packages (TensorFlow, PyTorch, CNTK) and image processing (Nipype), but no R
   * `IMAGE_PROCESSING`: Python3 with image processing packages (Nipype, FreeSurfer, FSL), but no R. [FreeSurfer](/user/jupyter-notebooks/freesurfer-in-dxjupyterlab.md) requires a license. GUI viewers such as `fsleyes` and `freeview` cannot be launched in the headless environment.
   * `STATA`: Stata requires a [license to run](/user/jupyter-notebooks/stata-in-dxjupyterlab.md)
   * `MONAI_ML`: Extends the `ML` feature with specialized medical imaging frameworks, such as MONAI Core, MONAI Label, and 3D Slicer.
5. Review the pricing estimate (if you have billing access) based on your selected duration and instance type.
6. Click **Start Environment** to launch your session. JupyterLab shows an "Initializing" state while the worker initializes and the server starts.
7. Open your JupyterLab environment by clicking the session name link once the state changes to "Ready". You can also access it directly via `https://job-xxxx.dnanexus.cloud`, where `job-xxxx` is your job ID.

{% hint style="info" %}
If a snapshot does not work with the default app environment, you can [recreate snapshot for the default environment](/user/jupyter-notebooks.md#recreating-a-snapshot-for-the-default-app-environment) or [restore snapshot with a compatible earlier app version](#running-an-earlier-app-version).
{% endhint %}

For a detailed list of libraries included in each feature option, see the [in-product documentation](https://platform.dnanexus.com/app/app-dxjupyterlab).

## Running JupyterLab from the CLI

You can start the JupyterLab environment directly from the command line by running the app:

```shell
dx run app-dxjupyterlab
```

Once the app starts, you may check if the JupyterLab server is ready to serve connections by running `dx describe job-xxxx --json` and confirming that the job's `httpsAppState` property is set to `running`. Once it is running, you can open your browser and go to `https://job-xxxx.dnanexus.cloud` where `job-xxxx` is the ID of the job running the app.

To run the Spark version of the app, use the command:

```shell
dx run app-dxjupyterlab_spark_cluster
```

You can check the optional input parameters for the apps on the DNAnexus Platform:

* [JupyterLab App](https://platform.dnanexus.com/app/app-dxjupyterlab)
* [JupyterLab Spark Cluster App](https://platform.dnanexus.com/app/app-dxjupyterlab_spark_cluster)

From the CLI, you can learn more about `dx run` with the following command:

```shell
dx run APP_NAME -h
```

where `APP_NAME` is either `app-dxjupyterlab` or `app-dxjupyterlab_spark_cluster`.

## Running an Earlier App Version

The **New JupyterLab** flow launches the default app version. To use a snapshot that does not work in that environment, launch a compatible earlier app version. Use the app version that created the snapshot if it is available. The app version does not necessarily match the JupyterLab software version included in the app.

### From the UI

1. In the main menu, select **Tools** > **Tools Library**.
2. Find and select the JupyterLab app you want to run.
3. Select an app version from the version dropdown on the app detail page or in the **Run App** dialog.
4. Select the project and configure the app inputs. To restore a snapshot, provide the snapshot file in the `snapshot` input.
5. Select **Run** to launch the app.

### From the CLI

Select a project, then run the command for the app you want to use. Replace `APP_VERSION` with the app version identifier.

```shell
dx run app-dxjupyterlab/APP_VERSION --priority high
```

For the Spark cluster-enabled app, run:

```shell
dx run app-dxjupyterlab_spark_cluster/APP_VERSION --priority high
```

To restore a snapshot, add `-isnapshot=SNAPSHOT_FILE` to either command. Replace `SNAPSHOT_FILE` with the snapshot's file ID or project path.

{% hint style="info" %}
Running JupyterLab at high priority is not required. However, doing so ensures that your interactive session is not interrupted by spot instance termination.
{% endhint %}

After launching either app, [check that the server is ready and open your session](#running-jupyterlab-from-the-cli).

## Next Steps

See the [Quickstart](/user/jupyter-notebooks/quickstart.md) and [References](/user/jupyter-notebooks/references.md) pages for more details on how to use JupyterLab.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.dnanexus.com/user/jupyter-notebooks/running-dxjupyterlab.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.