Dependencies & Environments

Manage Python versions, packages, and virtual environments with uv.

pynb uses uv to manage Python environments and dependencies. Everything is automatic: uv is downloaded if not present, virtual environments are created per notebook, and common packages are pre-installed.

Zero Config Setup

When you open a notebook for the first time, pynb:

  1. Downloads uv (if not already installed)
  2. Creates a shared base venv with common packages (ipykernel, polars, pandas, pyarrow, DuckDB, jupysql, ADBC drivers, etc.)
  3. Creates a per-notebook venv that inherits from the base via .pth files

This means every notebook gets its own isolated environment, but common packages are shared to save disk space and setup time. New notebook environments are created in ~35ms.

Adding Packages

Dependency Manager Panel

Click the packages icon in the toolbar to open the dependency manager. Type a package name and click Add to install it into the notebook's environment and persist it to the notebook file.

PEP 723 Inline Metadata (.py notebooks)

For .py notebooks, dependencies are stored as PEP 723 inline script metadata at the top of the file:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
#     "beautifulsoup4",
# ]
# ///

# %%
import requests

When you add or remove packages through the dependency manager, this block is updated automatically.

.ipynb Notebooks

For .ipynb notebooks, dependencies are stored in metadata.pynb.dependencies inside the notebook JSON. The dependency manager handles this transparently.

requirements.txt

If a requirements.txt file exists in the same directory as your notebook, pynb installs those packages when the environment is first created.

Python Versions

Global Default

Set a default Python version in Settings > General > Python Version. Options include system default, 3.11 through 3.14, or a custom version string like 3.11.8. uv downloads the requested version automatically if it's not already available.

Per-Notebook Override

Individual notebooks can specify their own Python version. In .py notebooks, use the requires-python field in PEP 723 metadata:

# /// script
# requires-python = ">=3.11"
# ///

pynb extracts the minimum version from the constraint and uses it for that notebook's environment.

For .ipynb notebooks, the version is stored in metadata.pynb.python_version.

Resolution Order

  1. Per-notebook override (PEP 723 or ipynb metadata)
  2. Global setting (from Settings)
  3. System default

Removing Packages

Click the x button next to any package in the dependency manager to remove it from the notebook's dependency list. This updates the PEP 723 block or ipynb metadata but does not uninstall the package from the current environment.