Managing Python Projects with uv

Overview

This skill helps you work with Python projects managed by uv, an extremely fast Python package and project manager written in Rust. Use this skill for:

• Initializing new Python projects

• Managing dependencies and virtual environments

• Running scripts and applications

• Building and publishing packages

• Optimizing Python workflows with uv’s speed

• There are several ways to install and use Python and the ecosystem built upon Python.

  • PyEnv has been available for a while and is now mature enough to be widely used by the majority of users. PyEnv is the solution be default used in these cheat sheets
  • uv is the new, shiny, kid on the block, and may appeal to those seeking to be on the edge of technological trends. There is at least a very specific use case where uv proves useful, it is to power standalone Python scripts: it is enough to add the magic #!/usr/bin/env -S uv command as the first line of any Python script, and that latter becomes standalone, self-served on any platform, any where, whithout requiring the users to install anything like dependencies (apart uv itself, obviously)

When to Use This Skill

Use this skill when:

• Setting up a new Python project from scratch
• Converting an existing project to use uv
• Managing dependencies (adding, removing, updating packages)
• Working with virtual environments
• Running Python scripts or applications in a uv project
• Building distributions for PyPI
• The user asks about uv commands or workflows
• You need to check which Python version or packages are installed

Additional Resources

Assets for this skill

• Makefile — Example of Makefile excerpts with relevant targets
• pyproject.toml — Example of Python project file, compatible with uv
• README.md — Example of relevant excerpts in the README file
• main.py — Example of working standalone main.py file, to be copied in the src/<project>/ directory (if not existing, be sure to create that directory, adapting to your project)
• test_main.py — Example of working test_main.py Python test script, to be copied in the tests/ directory (if not existing, be sure to create that directory)
• .gitignore – Example of relevant excerpts in the .gitignore file, Git-ignoring Python-/uv-related files
• ci.yml – Example of relevant excerpts in the ci.yml CI/CD (GitHub Actions) dev pipeline, to be copied into the .github/workflows/ directory (if not existing, be sure to create that directory)
• publish.yml – Example of relevant excerpts in the publish.yml CI/CD (GitHub Actions) release pipeline, to be copied into the .github/workflows/ directory

Data Engineering Helpers

• Data Engineering Helpers – Knowledge Sharing – Python
  • Cheat sheet for how to set up and use Python, especially detailing the installation and use of uv

uv

• Astral doc – uv
• GitHub – Astral – uv
• Astral doc – uv migration guides

Quick Reference

• Integrate the sample files into your project directory (if you had not any such file, just copy them; otherwise, merge their content within your corresponding files):
  • Makefile
  • pyproject.toml
  • README.md
  • main.py
  • test_main.py
  • .gitignore
  • ci.yml
  • publish.yml

Quick start

• If not already done so, install a specific Python version for uv:

make init-uv-python PYTHON_VERSION=3.13

• Clean all previous work:

make clean

• Note that uv is expecting that the Python source code be in the src/<project>/ sub-directory
  • The <project> name is specified in the pyproject.toml Python project specification file. Change it to reflect your project name
  • For the next commands to work, that source directory should at least contain a Python script. If need, copy the main.py into the src/<project>/ directory:

mkdir -p src/<project> tests .github/workflows
cp assets/main.py src/<project>/
cp assets/test_main.py tests/
cp assets/*.yml .github/workflows/
git add src/<project>/main.py tests/test_main.py .github/workflows/*.yml

• Initialize the Python environment with uv:

make init update

• Run the Python script:

make run

Useful commands

• Build the artifact (Python wheel):

make build

• Check (with the linter and type checkers) that there is no Python issue:

make check

• Test the Python package:

make test

• Publish the artifact (Python wheel):

make publish