Skip to content

Environment Management

Each notebook has its own isolated Python environment managed by uv.

How It Works

When you create a notebook, Strata:

  1. Generates a pyproject.toml with pyarrow as the default dependency
  2. Runs uv sync to create a .venv/ and uv.lock
  3. All cell execution uses this notebook-local venv

The environment lockfile hash (sha256(uv.lock)) participates in provenance. Changing the environment invalidates all cached cell outputs.

Python Version

At notebook creation time, you can select a Python version from the versions configured on the server. The default is the server's own Python version.

Note

The available versions depend on the server's STRATA_NOTEBOOK_PYTHON_VERSIONS configuration. On the hosted preview, both 3.12 and 3.13 are available.

Installing Packages

From the UI

Open the Environment panel in the sidebar. Type a package name and click Add.

pandas>=2.0
scikit-learn
matplotlib

The operation runs asynchronously — you can continue editing cells while it installs.

Import from requirements.txt

In the Environment panel, click Import and paste a requirements.txt:

pandas>=2.0
numpy>=2.0
scikit-learn>=1.5
matplotlib>=3.9
seaborn>=0.13

Strata previews the changes (additions, removals, unchanged) before applying.

Import from environment.yaml

Conda-style environment.yaml files are supported on a best-effort basis. Strata extracts pip dependencies and ignores conda-specific packages.

Export

Click Export to download the current dependencies as requirements.txt.

Environment Operations

All environment mutations run as async jobs with four actions:

Action Description
add Install a new package
remove Remove a package
sync Rebuild the environment from pyproject.toml
import Bulk import from requirements.txt or environment.yaml

The UI shows:

  • Current job status (running, success, failed)
  • Recent operation history (persisted across server restarts)
  • Resolved package count and lockfile hash

Cache Invalidation

When you install or remove a package:

  1. uv sync runs to update uv.lock
  2. The lockfile hash changes
  3. All cells become stale (their provenance no longer matches)
  4. Re-running any cell recomputes with the new environment

Switching back

If you remove a package and then re-add it (returning to the same uv.lock), the original provenance hashes match again and cells get cache hits. This is free by construction — no special logic needed.

Missing Package Detection

When a cell fails with ModuleNotFoundError, Strata detects the missing package and offers a one-click install button:

ModuleNotFoundError: No module named 'pandas'
→ [Install pandas]

File Layout

my_notebook/
├── pyproject.toml    # Package declarations
├── uv.lock           # Locked dependency graph
└── .venv/            # Virtual environment (auto-created, not committed)

The pyproject.toml and uv.lock are the source of truth. The .venv/ is recreated by uv sync when needed.