Document describing how to use `uv` to set up a project.

uv_setup.md

Setting Up a Python Environment for Quarto + Jupyter Using uv and .venv

This guide explains how to:

1. Install uv
2. Create a project with pyproject.toml
3. Use a project-local .venv
4. Add dependencies to the project
5. Sync the environment
6. Register the environment as a Jupyter kernel
7. Use the kernel from Quarto

This workflow works well with modern editors because many IDEs automatically detect a local .venv, and uv uses .venv as the default project environment.

---

Why uv?

uv is a fast Python package and environment manager written in Rust. It combines several common tools into a single workflow.

uv handles:

• environment management (similar to venv)
• dependency management (similar to pip)
• project metadata using pyproject.toml
• optional lockfiles for reproducible environments

Compared with traditional setups such as venv + pip, uv provides:

• much faster installs
• a simple command set (uv add, uv sync)
• automatic use of a project-local .venv
• native pyproject.toml support

This guide uses uv in a lightweight research workflow suitable for:

• Quarto projects
• Jupyter notebooks
• teaching materials
• exploratory analysis

The goal is to keep environments simple, local to the project, and easy to recreate.

---

Step 1: Install uv

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Reload your shell if necessary:

source ~/.zshrc
# or
source ~/.bashrc

Verify installation:

uv --version

---

Step 2: Create a project

mkdir notes_py
cd notes_py
uv init

This creates a pyproject.toml file.

---

Step 3: Project environment .venv

uv uses .venv as the default project environment.

Typical project layout:

notes_py/
├── pyproject.toml
├── uv.lock
└── .venv/

Many IDEs automatically detect .venv environments.

---

Step 4: Add dependencies

Example:

uv add jupyter pandas matplotlib

---

Step 5: Add ipykernel

To use the environment with Jupyter or Quarto:

uv add --dev ipykernel

---

Step 6: Sync the environment

uv sync

This creates or updates the .venv environment.

---

Step 7: Register the .venv environment as a Jupyter kernel

Jupyter does not automatically detect project environments. To use the project’s .venv inside notebooks or Quarto, we register it as a Jupyter kernel.

Run:

uv run python -m ipykernel install \
  --user \
  --name notes_py \
  --display-name "Python (notes_py)"

Explanation:

• uv run python ensures the Python interpreter inside .venv is used
• `--name notes