A comprehensive guide and tutorial for uv, the extremely fast Python package manager. This repository contains the source for the uv-class book and several example projects used throughout the course.

This is a teaching resource focused on uv. It covers everything from basic installation to advanced Docker multi-stage builds and C extension management.

The repository includes:

• The Book: A Hugo-based static site containing all chapters.
• Example Projects:
  • examples/berlin-weather: A pure Python project demonstrating standard uv workflows.
  • examples/helloext: A C-based Python extension using scikit-build-core.
  • examples/whoami: Demonstrations of PEP 723 inline script metadata.

• Students: Learning how to manage Python projects effectively.
• Instructors: Looking for a structured curriculum to teach modern Python tooling.
• Developers: Migrating from pip, venv, or Poetry to uv.

This project uses Git submodules for the Hugo theme. You must clone recursively:

git clone --recurse-submodules https://github.com/isotopp/uv-class.git
cd uv-class

• uv: Install uv
• Hugo: Install Hugo (extended version required)

To run the Hugo development server and view the book locally:

hugo server -D

The site will be available at http://localhost:1313/.

If you only want distributable book files and do not want to set up Hugo, you can build them with Pandoc instead.

Requirements:

• pandoc
• zip
• make

Build all export formats:

make all

This writes the generated files to out/:

• out/uv-class.epub
• out/uv-class.docx
• out/uv-class.odt
• out/uv-class.html

Remove generated files again:

make clean

To create a GitHub release with those artifacts attached, use:

scripts/release-artifacts.sh release-YYYY-MM-DD

The script rebuilds the artifacts, creates a zip file, and publishes a GitHub release via gh.

Navigate to any example project in /examples and use uv to run it:

cd examples/berlin-weather
uv run berlin-weather

• content/books/uv-class/: The source chapters for the book.
• themes/hugo-book/: The Hugo theme (git submodule).
• examples/: Standalone Python projects used for demonstrations.
• AGENTS.md: Policy for AI-assisted contributions.

Contributions are welcome! Please see AGENTS.md for guidelines on how to contribute, especially if you are using AI tools.

If you find a bug or have a suggestion, please open a GitHub issue.