UV: Cheatsheet

Some usefull commands with uv

Published: | Last updated:

Here's a quick UV cheatsheet with some simple commands I use regularly.

Starting a new project

If you have a fresh brand new project, you can start using UV right away.

From the command line, run:

uv init

This will create a pyproject.toml file, a new virtual environment (in directory .venv), and install python.

You want to add pandas to your project? It's as simple as running:

uv add pandas

Understanding pyproject.toml

Let's say you have an existing pyproject.toml file that looks something like this:

[project]
name = "yourproject"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "jinja2>=3.1.6",
]
[dependency-groups]
dev = [
    "livereload>=2.7.1",
]

This tells us a few interesting things:

  • This project requires a version of Python that is >= 3.12
  • This project depends on the jinja2 package
  • There are separate dependencies in a group called dev that uses the livereload package

The dependency-groups separate your project dependencies. You can use this to do things like split dependencies that are strictly necessary for your project, from those dependencies needed during development of your project.

Sync Python with pyproject.toml

To install and sync your virual environment with the dependencies (e.g., 'jinja2' in this example) in the pyproject.toml file, run this from the command line:

uv sync

To sync and install the dev dependencies (e.g., 'livereload') in addition to the regular dependecies (e.g., 'jinja2') in the pyproject.toml file, run: 

uv sync --group dev

If you have other groups, you can sync everything with:

uv sync --all-groups

Add packages

Let's say you want to add the Python package beautifulsoup4 to your core dependencies, run this from the command line:

uv add beautifulsoup4

This will add beautifulsoup4 to dependecies in your pyproject.toml, and download and install the package in your virtual environment. So you can start using it right away!

Let's say you want to add the ruff package to format your code. Since ruff isn't required to run your project, you might want to separate it for your rother dependencies and add it as a dev group dependency: 

uv add --group dev ruff

You should now see beautifulsoup4 as part of the dependencies and ruff as part of the dev group dependencies in your pyproject.toml file looking something like this:

dependencies = [
    "jinja2>=3.1.6",
    "beautifulsoup4>=4.14.2",
]
[dependency-groups]
dev = [
    "livereload>=2.7.1",
    "ruff>=0.14.1",
]

Running scripts

You can/should even run your scripts (with command line arguments) with uv:

uv run python my_script.py --myargs

Export pyproject.toml to requirements.txt

Sometimes you'll still want to create a requirements.txt from your pyproject.toml.

You can export pyproject.toml to requirements.txt by running this command:

uv pip compile pyproject.toml -o requirements.txt

This will give you a `requirements.txt` for the packages in the dependencies list.

However, this list of packages will include your dependencies (e.g., "jinja"), and the dependencies of your dependencies (e.g., the dependenices of "jinja").

This may or may not be what you want. To ONLY include the dependencies you specified, you can instead run:

uv pip compile --no-deps pyproject.toml -o requirements.txt