Skip to main content
nteract Desktop automatically manages Python and Deno environments for your notebooks. You don’t need to manually create virtual environments or install packages — the app handles it based on what’s in your notebook and what project files are nearby.

​
How It Works

When you open a notebook, nteract Desktop uses a two-stage detection:

​
Stage 1: Which runtime? (Python or Deno)

nteract Desktop checks the notebook’s stored kernel type:
  • If the notebook says it’s a Deno notebook → Deno kernel
  • If the notebook says it’s a Python notebook → Python kernel (then proceeds to Stage 2)
  • New notebooks use your default runtime preference
This means Python and Deno notebooks can coexist in the same project directory — each uses its correct kernel regardless of what project files are nearby.

​
Stage 2: Which Python environment?

For Python notebooks, nteract Desktop looks for dependencies in this order:
1

Inline dependencies

Dependencies stored directly in the notebook metadata (metadata.uv.dependencies or metadata.conda.dependencies)
2

Closest project file

Walks up from the notebook’s directory looking for pyproject.toml, pixi.toml, or environment.yml. The closest match wins.If the same directory has multiple project files, tiebreaker order is: pyproject.toml > pixi.toml > environment.yml
3

Prewarmed environment

If no dependencies found, uses a prewarmed environment with just the basics (ipykernel + ipywidgets)
The search stops at git repository boundaries and your home directory, so project files from unrelated repos won’t interfere.

​
Inline Dependencies

The simplest way to manage packages. Dependencies are stored directly in the notebook file, making it fully portable — anyone who opens the notebook gets the same packages.

​
Adding Packages

Use the dependency panel in the sidebar to add, remove, or sync packages.
  • UV dependencies: Use pip-style package names (pandas, numpy>=2.0)
  • Conda dependencies: Support conda channels and conda-forge packages

​
Storage Format

Dependencies live in the notebook’s JSON metadata: 
{
  "metadata": {
    "uv": {
      "dependencies": ["numpy", "pandas", "matplotlib>=3.5"]
    }
  }
}

​
Environment Caching

For notebooks with inline UV dependencies, the daemon creates cached environments in ~/.cache/runt/inline-envs/. Environments are keyed by a hash of the sorted dependencies, enabling fast reuse: 
~/.cache/runt/inline-envs/
  inline-a1b2c3d4/    # Hash of ["requests"]
  inline-e5f6g7h8/    # Hash of ["pandas", "numpy"]
Cache hit = instant startup. First launch with new dependencies takes time to install packages.

​
Working with pyproject.toml

If your notebook is in a directory with a pyproject.toml, nteract Desktop auto-detects it and uses uv run to start the kernel in the project’s virtual environment.
  • The project’s .venv/ is used directly — no separate cached environment
  • Dependencies stay in sync with the project
  • The dependency panel shows the project’s deps in read-only mode

​
Dependency Panel Actions

The dependency panel offers two actions:

Use project environment

Run the kernel in the project’s .venv (keeps deps in sync with the project)

Copy to notebook

Snapshot the project’s dependencies into the notebook metadata (makes the notebook portable but deps may drift from the project)

​
Working with environment.yml

Conda environment.yml files are auto-detected. nteract Desktop parses the channels, conda dependencies, and pip dependencies from the file and creates a conda environment using rattler. The dependency panel shows the environment.yml dependencies and offers an “Import to notebook” action to copy them into the notebook’s conda metadata for portability.

​
Example environment.yml

name: myproject
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.11
  - numpy
  - pandas
  - pip:
    - requests

​
Working with pixi.toml

Pixi project files are auto-detected. nteract Desktop converts pixi dependencies to conda format and creates the environment using rattler. Both [dependencies] (conda packages) and [pypi-dependencies] (pip packages) are supported. The dependency panel shows pixi dependencies and offers an “Import to notebook” action.

​
Example pixi.toml

[project]
name = "myproject"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64"]

[dependencies]
python = "3.11.*"
numpy = ">=1.20"

[pypi-dependencies]
requests = "*"

​
Deno Notebooks

Deno notebooks use the Deno runtime for TypeScript/JavaScript. Unlike Python, Deno manages its own dependencies through import maps and URL imports, so there’s no separate environment to create.

​
How Deno is Obtained

1

Check PATH

nteract Desktop first checks if deno is on your PATH
2

Auto-install if needed

If not found, nteract Desktop automatically installs Deno from conda-forge (stored in ~/.cache/runt/tools/)
Deno notebooks work out of the box — you don’t need to install Deno manually.

​
Project Configuration

If your notebook is near a deno.json or deno.jsonc file, Deno will use that configuration for import maps and permissions.
deno.json
{
  "imports": {
    "lodash": "https://esm.sh/[email protected]"
  }
}

​
User Preferences

You can configure two default preferences in settings:

​
Default Runtime

Choose what type of kernel new notebooks use:
  • Python (default) — standard Python notebooks with ipykernel
  • Deno — TypeScript/JavaScript notebooks using the Deno kernel

​
Default Python Environment

Choose which package manager to use for Python notebooks:
  • UV (default) — fast, pip-compatible package management
  • Conda — supports conda packages (useful for non-Python dependencies like CUDA libraries)
This preference is used when no project files are detected and the notebook has no inline dependencies. When a project file is present, nteract Desktop picks the appropriate backend automatically (UV for pyproject.toml, Conda for environment.yml and pixi.toml).
See the Settings guide for how to change these defaults.

​
Trust Dialog

When you open a notebook with inline dependencies for the first time, nteract Desktop may show a trust dialog asking you to approve the dependency installation.

​
Why This Happens

  • Dependencies are signed with a per-machine key
  • Notebooks from other machines (shared by a colleague, cloned from a repo) have a different signature
  • nteract Desktop asks you to verify the dependencies before installing anything
After you approve, the notebook is re-signed with your machine’s key and won’t prompt again unless the dependencies change.

​
Environment Source Labels

The kernel status indicator shows where the environment came from:
LabelDescription
uv:inlineUV environment from notebook metadata
uv:pyprojectUV environment from pyproject.toml
uv:prewarmedUV environment from the prewarmed pool
conda:inlineConda environment from notebook metadata
conda:env_ymlConda environment from environment.yml
conda:pixiConda environment from pixi.toml
conda:prewarmedConda environment from the prewarmed pool
denoDeno runtime

​
Cache and Cleanup

nteract Desktop caches environments so notebooks with the same dependencies share a single environment, making subsequent opens instant.
WhatLocation
UV environments~/.cache/runt/envs/
Conda environments~/.cache/runt/conda-envs/
Inline UV envs~/.cache/runt/inline-envs/
Tools (uv, deno)~/.cache/runt/tools/
Trust key~/.config/runt/trust-key
To reclaim disk space, delete the environment cache directories. nteract Desktop will recreate environments as needed.

​
Troubleshooting

​
Packages aren’t available after adding them

Click “Sync Now” in the dependency panel to install pending changes, then restart the kernel.

​
Wrong environment detected

If the kernel started with a prewarmed environment instead of your project’s dependencies:
  1. Check that your project file (pyproject.toml, environment.yml, pixi.toml) is in the notebook’s directory or a parent directory
  2. Verify you’re within the same git repository (the search stops at git boundaries)
  3. Check daemon logs: runt daemon logs -f

​
Slow first start

The first time a notebook opens with dependencies, nteract Desktop needs to download and install packages. Subsequent opens with the same dependencies are instant due to caching.

​
Trust dialog keeps appearing

This happens when the notebook’s dependency signature doesn’t match your machine’s key. Approve the dependencies once and nteract Desktop will re-sign the notebook.

Build docs developers (and LLMs) love

Get started for freeTalk to us