UV: Cheatsheet

Some useful commands with uv

Published: | Last updated:

A UV cheatsheet with some commands I regularly use.

Starting a new project

If you are starting a brand new project, run from the command line:

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

This downloads and installs pandas in your virtual environment .venv.

You can start the Python REPL by running this from the command line:

uv run python

If you're using an IDE like VSCode then ensure you select the Python version in your newly created virtual environment .venv/bin/python.

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

Deleting environment

uv will create a virtual environment in your project's directory under .venv

If you no longer need this environment, you can just delete it:

rm -r .venv