A little wrapper around `uv` to launch ephemeral Jupyter notebooks.
Project description
juv
A little wrapper around uv
to launch ephemeral Jupyter notebooks.
uvx juv
# Usage: juv [OPTIONS] COMMAND [ARGS]...
#
# A wrapper around uv to launch ephemeral Jupyter notebooks.
#
# Options:
# --help Show this message and exit.
#
# Commands:
# add Add dependencies to the notebook.
# info Display juv and uv versions.
# init Initialize a new notebook.
# run Launch a notebook or script.
# version Display juv's version.
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
# 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_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...
what
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 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.