juv 0.2.25

A toolkit for reproducible Jupyter notebooks, powered by uv.

juv

A toolkit for reproducible Jupyter notebooks, powered by uv.

Features

• 🗂️ Create, manage, and run reproducible notebooks
• 📌 Pin dependencies with PEP 723 - inline script metadata
• 🚀 Launch ephemeral sessions for multiple front ends (e.g., JupyterLab, Notebook, NbClassic)
• ⚡ Powered by uv for fast dependency management

Installation

juv is published to the Python Package Index (PyPI) and can be installed globally with uv or pipx (recommended):

uv tool install juv
# or pipx install juv

You can also use the uvx command to invoke it without installing:

uvx juv

Usage

juv should feel familar for uv users. The goal is to extend its dependencies management to Jupyter notebooks.

# create a notebook
juv init notebook.ipynb
juv init --python=3.9 notebook.ipynb # specify a minimum Python version

# add dependencies to the notebook
juv add notebook.ipynb pandas numpy
juv add notebook.ipynb --requirements=requirements.txt

# Pin a timestamp to constrain dependency resolution to a specific date
juv stamp notebook.ipynb # now

# launch the notebook
juv run notebook.ipynb
juv run --with=polars notebook.ipynb # additional dependencies for this session (not saved)
juv run --jupyter=notebook@6.4.0 notebook.ipynb # pick a specific Jupyter frontend
juv run --jupyter=nbclassic notebook.ipynb -- --no-browser # pass additional arguments to Jupyter

# JUV_JUPYTER env var to set preferred Jupyter frontend (default: lab)
export JUV_JUPYTER=nbclassic
juv run notebook.ipynb

If a script is provided to run, it will be converted to a notebook before launching the Jupyter session.

uvx juv run script.py
# Converted script to notebook `script.ipynb`
# Launching Jupyter session...

Motivation

Rethinking the "getting started" guide for notebooks

Jupyter notebooks are the de facto standard for data science, yet they suffer from a reproducibility crisis.

This issue does not stem from a fundamental lack of care for reproducibility. Rather, our tools limit us from easily falling into the pit of success with notebooks - in particular, managing dependencies.

Notebooks are much like one-off Python scripts and therefore do not benefit from the same dependency management as packages. Being a "good steward" of notebooks requires discipline (due to the manual nature of virtual environments) and knowledge of Python packaging - a somewhat unreasonable expectation for domain experts who are focused on solving problems, not software engineering.

You will often find a "getting started" guide in the wild like this:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt # or just pip install pandas numpy, etc
jupyter lab

Four lines of code, where a few things can go wrong. What version of Python? What package version(s)? What if we forget to activate the environment?

The gold standard for "getting started" is a single command (i.e, no guide).

<magic tool> run notebook.ipynb

However, this ideal has remained elusive for Jupyter notebooks. Why?

• Virtual environments are a leaky abstraction deeply ingrained in the Python psyche: create, activate, install, run. Their historical "cost" has forced us to treat them as entities that must be managed explicitly. In fact, an entire ecosystem of tooling and best practices are oriented around long-lived environments, rather than something more ephemeral. End users separately create and then mutate virtual environments with low-level tools like pip. The manual nature and overhead of these steps encourages sharing environments across projects - a nightmare for reproducibility.

• Only Python packages could historically specify their dependencies. Data science code often lives in notebooks rather than packages, with no way to specify dependencies for standalone scripts without external files like requirements.txt.

Aligning of the stars

Two key ideas have changed my perspective on this problem and inspired juv:

• Virtual environments are now "cheap". A year ago, they were a necessary evil. uv is such a departure from the status quo that it forces us to rethink best practices. Environments are now created faster than JupyterLab starts - why keep them around at all?

• PEP 723. Inline script metadata introduces a standard for specifying dependencies for standalone Python scripts. A single file can now contain everything needed to run it, without relying on external files like requirements.txt or pyproject.toml.

So, what if:

• Environments were disposable by default?
• Notebooks could specify their own dependencies?

This is the vision of juv

[!NOTE] Dependency management is just one challenge for notebook reproducibility (non-linear execution being another). juv aims to solve this specific pain point for the existing ecosystem. I'm personally excited for initiatives that rethink notebooks from the ground up, making a tool like juv obsolete.

How

PEP 723 (inline script metadata) allows specifying dependencies as comments within Python scripts, enabling self-contained, reproducible execution. This feature could significantly improve reproducibility in the data science ecosystem, since many analyses are shared as standalone code (not packages). However, a lot of data science code lives in notebooks (.ipynb files), not Python scripts (.py files).

juv bridges this gap by:

• Extending PEP 723-style metadata support from uv to Jupyter notebooks
• Launching Jupyter sessions for various notebook front ends (e.g., JupyterLab, Notebook, NbClassic) with the specified dependencies

It's a simple Python script that parses the notebook and starts a Jupyter session with the specified dependencies (piggybacking on uv's existing functionality).

Alternatives

juv is opinionated and might not suit your preferences. That's ok! uv is super extensible, and I recommend reading the wonderful documentation to learn about its primitives.

For example, you can achieve a similar workflow using the --with-requirements flag:

uvx --with-requirements=requirements.txt --from=jupyter-core --with=jupyterlab jupyter lab notebook.ipynb

While slightly more verbose and breaking self-containment, this approach totally works and saves you from installing another dependency.

There is also an experimental rewrite in Rust.

Contributing

juv welcomes contributions in the form of bug reports, feature requests, and pull requests. See the CONTRIBUTING.md for more information.