Managing Python Projects with uv

Overview

• 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

• 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) pipeline, to be copied into the

  .github/workflows/

  directory (if not existing, be sure to create that 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 installation
• 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 compatible with uv
  • README.md
  • main.py

  • test_main.py

  • .gitignore
  • ci.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/ci.yml .github/workflows/
git add src/<project>/main.py tests/test_main.py .github/workflows/ci.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