Skip to main content

​
Prerequisites

Make sure you have nteract Desktop installed. If not, follow the Installation guide.

​
Open Your First Notebook

1

Launch nteract Desktop

Open the nteract application from your Applications folder (macOS), Start Menu (Windows), or by running the AppImage (Linux).The daemon starts automatically in the background.
2

Open a notebook file

You can open a notebook in several ways:From the GUI:
  • Click Open Notebook and browse to a .ipynb file
From the command line:
runt notebook path/to/notebook.ipynb
Create a new notebook:
# Python notebook
runt notebook

# Or specify a path for the new notebook
runt notebook ~/notebooks/analysis.ipynb
3

Wait for kernel startup

nteract Desktop automatically:
  • Detects the notebook’s runtime (Python or Deno)
  • Finds nearby project files (pyproject.toml, environment.yml, etc.)
  • Launches the appropriate kernel with the right environment
The first launch may take a few seconds to create the environment. Subsequent launches are instant thanks to environment pooling.
4

Run your first cell

Click on a code cell and press Shift+Enter to execute it.The output appears immediately below the cell.

​
Your First Python Notebook

Let’s create a simple Python notebook and run some code.
1

Create a new Python notebook

runt notebook ~/notebooks/hello.ipynb
2

Add a code cell

Type the following Python code:
import sys
print(f"Python {sys.version}")
print("Hello from nteract Desktop!")
3

Run the cell

Press Shift+Enter. You should see output like:
Python 3.12.1 (main, Jan 10 2024, 12:00:00)
Hello from nteract Desktop!
4

Add a package

Open the dependency panel in the sidebar and add a package like pandas.nteract Desktop automatically:
  • Installs the package in the notebook’s environment
  • Restarts the kernel with the new dependencies
  • Preserves your cell outputs
5

Use the package

Create a new cell:
import pandas as pd

df = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [25, 30, 35]
})

df
Run the cell to see a formatted DataFrame output.

​
Your First Deno Notebook

Let’s create a TypeScript/JavaScript notebook with Deno.
1

Create a new Deno notebook

runt notebook --runtime deno ~/notebooks/hello-deno.ipynb
nteract Desktop automatically installs Deno if it’s not on your PATH.
2

Add a TypeScript cell

const greeting: string = "Hello from Deno!";
console.log(greeting);

Deno.version
3

Run the cell

Press Shift+Enter to see the output:
Hello from Deno!
{ deno: "1.40.0", v8: "12.1.285.6", typescript: "5.3.3" }
4

Import from URL

Deno supports importing modules directly from URLs:
import { serve } from "https://deno.land/[email protected]/http/server.ts";

console.log("Imported serve function:", typeof serve);

​
Using the CLI

The runt CLI provides powerful commands for managing notebooks and kernels.

​
List Open Notebooks

See all notebooks currently open with kernel and environment info: 
runt notebooks
Output: 
╭──────────────────────────────────────┬────────┬──────────────┬────────┬───────╮
│ NOTEBOOK                             │ KERNEL │ ENV          │ STATUS │ PEERS │
├──────────────────────────────────────┼────────┼──────────────┼────────┼───────┤
│ ~/notebooks/analysis.ipynb           │ python │ uv:inline    │ idle   │ 1     │
│ ~/notebooks/hello-deno.ipynb         │ deno   │ deno         │ idle   │ 1     │
╰──────────────────────────────────────┴────────┴──────────────┴────────┴───────╯

​
Interactive Console

Launch an interactive Python console with a Jupyter kernel: 
runt console
This gives you a REPL connected to a kernel, perfect for quick experiments.

​
Daemon Management

Check daemon status and environment pools: 
# Daemon status
runt daemon status

# View daemon logs
runt daemon logs -f

# Flush and rebuild environment pools
runt daemon flush

​
Working with Dependencies

nteract Desktop offers three ways to manage dependencies: Store dependencies directly in the notebook metadata:
1

Open the dependency panel

Click the Dependencies icon in the sidebar.
2

Add packages

Type package names like pandas, numpy>=2.0, or matplotlib.Click Sync to install them.
3

Share the notebook

Anyone who opens your notebook gets the same dependencies automatically.
Inline dependencies are cached in ~/.cache/runt/inline-envs/ by dependency hash, so the same set of packages is reused across notebooks.
If your notebook is in a directory with a project file, nteract Desktop auto-detects it: 
[project]
name = "my-analysis"
dependencies = [
    "pandas>=2.0",
    "matplotlib",
]
The dependency panel shows project dependencies and offers actions:
  • Use project environment — run in the project’s .venv
  • Copy to notebook — snapshot deps into notebook metadata

​
3. Prewarmed Pools (Default)

If no dependencies are specified, nteract Desktop uses a prewarmed environment from the pool:
  • UV pool — Basic Python environment with ipykernel
  • Conda pool — Conda-based environment with common packages
You can configure which pool is used in Settings → Default Python Environment.

​
Keyboard Shortcuts

Speed up your workflow with these shortcuts:
ActionShortcut
Run cell and advanceShift+Enter
Run cell in placeCtrl+Enter (or Cmd+Enter on macOS)
Insert cell aboveA (command mode)
Insert cell belowB (command mode)
Delete cellD, D (press D twice in command mode)
Change to code cellY (command mode)
Change to markdown cellM (command mode)
Enter command modeEsc
Enter edit modeEnter
Save notebookCmd+S (macOS) or Ctrl+S (Windows/Linux)
Command mode is when the cell has a blue border. Edit mode is when you’re typing inside a cell.

​
Realtime Collaboration

Open the same notebook in multiple windows to see realtime sync in action:
1

Open a notebook

runt notebook ~/notebooks/shared.ipynb
2

Open it again in another window

runt notebook ~/notebooks/shared.ipynb
3

Edit in one window

Type in a cell in the first window.
4

Watch changes sync

The second window updates instantly via Automerge.
This also works with AI agents using the Python bindings: 
from runtimed import Session

session = Session("~/notebooks/shared.ipynb")
session.edit_cell(cell_id, "print('Hello from agent!')")
The desktop app sees the agent’s edits in realtime.

​
Viewing Outputs

nteract Desktop renders rich outputs:
  • Images: PNG, JPEG, SVG
  • HTML: Interactive visualizations
  • LaTeX: Math equations via KaTeX
  • Markdown: Formatted text
  • DataFrames: Pandas/Polars tables
  • Plots: Matplotlib, Plotly, Altair
Example with matplotlib: 
import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 2*np.pi, 100)
y = np.sin(x)

plt.plot(x, y)
plt.title("Sine Wave")
plt.show()
The plot appears inline below the cell.

​
Trust and Security

When you open a notebook with dependencies for the first time, nteract Desktop may show a trust dialog. Why? Dependencies are signed with a per-machine key. Notebooks from other machines have a different signature, so nteract Desktop asks you to verify before installing. What to do:
  • Review the dependency list
  • Click Trust and Install if the dependencies look safe
  • The notebook is re-signed with your key and won’t prompt again
See the Environments guide for more details.

​
Checking Daemon Logs

If something goes wrong, check the daemon logs: 
# View last 100 log lines
runt daemon logs -n 100

# Follow logs in realtime
runt daemon logs -f
Logs are also stored on disk: 
~/Library/Caches/runt/runtimed.log

​
Next Steps

Now that you’ve run your first notebook, explore these topics:

Environment Management

Learn how nteract Desktop detects and manages Python and Deno environments

Settings

Configure default runtime, environment backend, and other preferences

Collaboration

Deep dive into realtime sync and multi-client notebooks

CLI Reference

Full reference for all runt commands

​
Common Issues

Check daemon status:
runt daemon status
If the daemon is not running, restart it:
# macOS
launchctl kickstart -k gui/$(id -u)/io.nteract.runtimed

# Linux
systemctl --user restart runtimed.service
Check the daemon logs for error messages:
runt daemon logs -f
Common issues:
  • Network connectivity (can’t reach PyPI or conda-forge)
  • Invalid package names
  • Conflicting dependencies
Verify the file path is correct and the file is valid JSON:
# Check if file exists
ls -l path/to/notebook.ipynb

# Validate JSON
python -m json.tool path/to/notebook.ipynb > /dev/null
nteract Desktop walks up from the notebook directory looking for project files.Verify your project file is in the notebook’s directory or a parent directory:
# From notebook directory
ls pyproject.toml environment.yml pixi.toml
The search stops at .git boundaries and your home directory.
For more troubleshooting help, see the Logging guide or check the GitHub issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us