Python Journey – Reproducible Notebooks & Tools (marimo + uv)

This repository documents my Python learning path with a focus on:

• Reproducible environments using uv (fast package + venv manager). [github.com]
• Explorable notebooks using marimo (Python‑native interactive notebooks). [pypi.org]
• Small, practical examples → thin, real projects that support compliance, data quality, and light automation.

The structure mirrors my Rust and other language repos for consistency.

---

marimo quickstart

• Edit notebooks: uv run marimo edit notebooks/00_welcome.py [pypi.org]
• Run as app: uv run marimo run notebooks/00_welcome.py [pypi.org]
• Convert Jupyter to marimo: uv run marimo convert demo.ipynb -o notebooks/demo.py [pypi.org]

---

Notebook dependencies (PEP 723)

marimo uses uv to manage per‑notebook dependencies using PEP 723 inline metadata—this lets each notebook declare its own environment. [pydevtools.com], [startdatae...eering.com]

Example:

# /// script
# requires-python = ">=3.11"
# dependencies = ["marimo", "polars", "duckdb"]
# ///

---

How marimo + uv + PEP 723 work (and why it matters)

---

Project mode                           Sandbox mode
-------------                          -----------------------------
 repo/                                  notebooks/y.py
 ├─ pyproject.toml  (shared deps)       ├─ PEP 723 header (deps here)
 └─ notebooks/x.py                      └─ code cells

 Launch:                                Launch:
   uv run marimo edit                     uvx marimo edit --sandbox
     notebooks/x.py                         notebooks/y.py

 Kernel env:                            Kernel env:
   project venv (shared)                  per-file venv (isolated)

marimo is a reactive notebook that stores notebooks as plain .py files instead of JSON, which makes them git‑friendly, script‑runnable, and easy to reuse. You edit with marimo edit, run as an app with marimo run, and convert from Jupyter with marimo convert. [marketplac...studio.com], [pypi.org], [docs.marimo.io]

marimo edit file.py              # open notebook editor       [3](https://pypi.org/project/pep723/)
marimo run file.py               # run as read‑only app       [3](https://pypi.org/project/pep723/)
marimo convert in.ipynb -o out.py# convert Jupyter→marimo     [3](https://pypi.org/project/pep723/)
marimo export file.py --html     # export notebook            [3](https://pypi.org/project/pep723/)
marimo tutorial intro            # launch built‑in tutorial   [3](https://pypi.org/project/pep723/)
marimo check file.py             # lint/format marimo file    [4](https://docs.marimo.io/guides/package_management/using_uv/)

uv is a modern, fast Python package & environment manager. marimo integrates tightly with uv in two workflows: (1) project notebooks that use the repo’s pyproject.toml; and (2) sandboxed notebooks that declare their own deps inline in the file. [pydevtools.com], [github.com]

uv venv                          # create project venv        [2](https://github.com/python/peps/blob/main/peps/pep-0723.rst)
uv sync                          # install project deps       [2](https://github.com/python/peps/blob/main/peps/pep-0723.rst)
uv sync --all-extras --dev       # install dev + extras       [2](https://github.com/python/peps/blob/main/peps/pep-0723.rst)
uv add PKG                       # add project dependency     [1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)
uv add --script nb.py PKG        # add PEP 723 dep to notebook[1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)
uv run CMD                       # run tool in project env    [2](https://github.com/python/peps/blob/main/peps/pep-0723.rst)
uvx marimo edit nb.py            # run notebook (sandbox)     [1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)
uvx --reinstall marimo edit nb.py# rebuild sandbox env        [1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)
uv init NAME                     # create new uv project      [1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)

PEP 723 defines inline script metadata—a standardized way to put dependencies and Python version requirements inside a single file. Tools (like uv) read this metadata, create an isolated env, install exactly those deps, and run the file. This is what powers marimo’s sandboxed notebooks. [startdatae...eering.com]

---

File‑level dependencies with PEP 723

A marimo notebook can declare its own environment at the top of the file:

# /// script
# requires-python = ">=3.11"
# dependencies = ["marimo", "polars", "duckdb"]
# ///

• What this does: When you launch with uvx marimo edit --sandbox notebooks/00_welcome.py, uv reads the block, builds an isolated env for this one file, installs those packages, and starts marimo. No global pollution, no guessing which venv to use. [pydevtools.com]
• Why it’s new & important: PEP 723 (created Aug 4, 2023; finalized Jan 8, 2024) standardized this inline format, so single‑file notebooks/scripts are portable and reproducible across tools. [startdatae...eering.com]

---

When do you need PEP 723?

• Sandboxed notebooks (recommended for examples/tutorials): Yes. Inline metadata makes each notebook self‑contained and shareable. [pydevtools.com]
• Project notebooks (shared repo env): No. Add marimo to your project (uv add marimo) and run uv run marimo edit notebooks/x.py; dependencies come from pyproject.toml. [github.com]

---

SQL cells in marimo

If you use mo.sql("…") in a notebook, install marimo’s SQL extras (or include them in the PEP 723 block), e.g.:

# project mode
uv add "marimo[sql]"

# sandbox mode (adds to the notebook header)
uv add --script notebooks/00_welcome.py "marimo[sql]"

This pulls in the optional SQL stack (DuckDB backend + SQL parsing), enabling SQL cells to query DataFrames and databases directly from a notebook. [stackoverflow.com]

Tip: For interactive tables / DataFrame outputs, install Polars (or Pandas). marimo’s SQL guide explains supported output types and backends. [stackoverflow.com]

---

Why marimo instead of Jupyter?

marimo gives me:

• Pure .py notebooks → clean diffs, reusable modules, runnable as scripts. [marketplac...studio.com]
• Reactive execution → dependent cells auto‑update (no hidden state). [marketplac...studio.com]
• Built‑in SQL + data tooling. [stackoverflow.com]
• PEP 723 environments via uv → self‑contained, reproducible notebooks. [pydevtools.com], [startdatae...eering.com]

---

What to look at first

• SUMMARY.md – one‑page index of examples and projects
• projects/ – portfolio‑style code with design notes
• docs/architecture/ – decisions: why marimo + uv, notebooks vs scripts

---

FAQ (Quick)

**Do I need PEP 723 for every notebook?**  
No.  
• Use it for **sandboxed notebooks** (per‑file env). [1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)  
• Skip it for **project notebooks** using `pyproject.toml`. [2](https://github.com/python/peps/blob/main/peps/pep-0723.rst)

**When should I use sandbox mode vs project mode?**  
• **Sandbox mode (`uvx`)** → examples, tutorials, experiments, isolated deps. [1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)  
• **Project mode (`uv run`)** → shared deps, coherent repos, real workflows. [2](https://github.com/python/peps/blob/main/peps/pep-0723.rst)

**Why does marimo use `.py` files instead of `.ipynb`?**  
Because marimo notebooks are pure Python modules: git‑friendly, importable, script‑runnable, and reactive. [3](https://marketplace.visualstudio.com/items?itemName=marimo-team.vscode-marimo)

**Where do I install packages for a notebook?**  
• Project mode → `uv add package` (updates `pyproject.toml`). [1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)  
• Sandbox mode → `uv add --script nb.py package` (updates PEP 723 block). [1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)

**How does uv know what to install for sandboxed notebooks?**  
uv reads the notebook’s inline PEP 723 metadata and builds a per‑file environment automatically. [4](https://www.startdataengineering.com/post/python-notebook-best-practices-for-data-engineering/)

**What if I remove a dependency but the environment doesn’t update?**  
Force rebuild:  
`uvx --reinstall marimo edit nb.py`  
uv normally caches sandbox envs for speed. [1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)

**How do I fix SQL cell errors?**  
Install marimo’s SQL extras:  
`uv add "marimo[sql]"` (project)  
`uv add --script nb.py "marimo[sql]"` (sandbox)  
SQL cells require optional SQL dependencies. [5](https://stackoverflow.com/questions/46775346/what-do-square-brackets-mean-in-pip-install)

**Can notebooks import project code?**  
• Project mode → Yes, automatically (shared environment).  
• Sandbox mode → Add the project as editable:  
  `uv add --script nb.py . --editable`  
(uv updates PEP 723 metadata accordingly.) [1](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)

**Should all notebooks share the same dependencies?**  
Not in sandbox mode.  
Each notebook should declare **only what it uses** in its PEP 723 block.  
This is the whole purpose of per‑file environments. [4](https://www.startdataengineering.com/post/python-notebook-best-practices-for-data-engineering/)

**Is marimo a replacement for Jupyter?**  
For many workflows, yes: marimo provides reactive execution, no hidden state, pure `.py` notebooks, SQL tooling, and app deployment. [3](https://marketplace.visualstudio.com/items?itemName=marimo-team.vscode-marimo)

---

Tooling

• Python: 3.11+
• uv: creates virtual environments, resolves + installs deps, runs tools. [github.com]
• marimo: interactive notebooks in plain .py files. [marketplac...studio.com]

Common commands:

# Create and use a virtual environment
uv venv

# Install all dependencies (incl. dev extras)
uv sync --all-extras --dev

# Run marimo notebook editor (project mode)
uv run marimo edit notebooks/00_welcome.py

# Lint & tests
uv run ruff check .
uv run pytest -q

Troubleshooting (Quick)

• SQL cell errors (“sqlglot is required”):
    Install SQL extras:
        uv add "marimo[sql]"          # project mode
        uv add --script nb.py "marimo[sql]"   # sandbox mode
    (marimo SQL cells require optional SQL dependencies.) [1](https://stackoverflow.com/questions/46775346/what-do-square-brackets-mean-in-pip-install)

• ImportError when running a sandboxed notebook:
    Add the missing package to the notebook’s PEP 723 block:
        uv add --script nb.py package
    (uv updates the inline metadata for per‑file environments.) [2](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)

• Notebook environment didn’t update after editing dependencies:
    Force rebuild:
        uvx --reinstall marimo edit nb.py
    (uv may reuse cached envs unless forced to rebuild.) [2](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)

• Using project mode but imports still fail:
    Ensure dependency is in pyproject.toml:
        uv add package
    and relaunch with:
        uv run marimo edit nb.py
    (Project notebooks use the project venv, not sandboxed metadata.) [3](https://github.com/python/peps/blob/main/peps/pep-0723.rst)

• Unsure whether to use `uv run` or `uvx`:
    uv run → project environment (shared)
    uvx     → sandbox environment (per‑notebook)
    (uvx executes using inline script metadata.) [2](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script/)

• marimo UI opens but code doesn’t run:
    Ensure notebook begins with valid PEP 723 header if using sandbox mode:
        # /// script
        # requires-python = ">=3.11"
        # dependencies = [...]
        # ///
    (PEP 723 defines the inline metadata format tools rely on.) [4](https://www.startdataengineering.com/post/python-notebook-best-practices-for-data-engineering/)

---

Status Badges

https://github.com/pmdenlinger/python-dev-journey/actions/workflows/ci.yml/badge.svg
https://img.shields.io/badge/License-MIT-green.svg

---

Learning Philosophy

Progress from small, focused examples → real projects. Each step is documented with:

• Motivation
• Constraints & trade‑offs
• Tests and observability where it makes sense

---

License

LICENSE

---

References

• marimo docs: quickstart & CLI commands (edit, run, convert). [pypi.org], [docs.marimo.io]
• marimo architecture & file format (plain .py notebooks). [marketplac...studio.com]
• marimo SQL guide and DuckDB integration. [stackoverflow.com], [stackoverflow.com]
• uv + marimo integration, sandbox vs. project workflows. [pydevtools.com], [github.com]
• PEP 723 (inline script metadata): creation/finalization dates and spec. [startdatae...eering.com]