UV commands that you might forget

Recently I’ve been using uv to manage Python project depedencies and publish them to Pypi. Uv manage dependencies and keep them in sync with a lock file, can run other Python packages in isolated virtual environments and allow to install multiple versions of Python on the same computer.

Python versions

uv let’s you use multiple Python versions. You don’t need Python installed before working with your projects.

Get the available and installed Python versions

uv python list

Install Python 3.X

uv python install 3.X

Launch the Python REPL

uv run python

Upgrade your Python versions

uv python upgrade

Create a new project

uv supports Python projects with a pyproject.toml file. You can also manage pip style projects thanks to pip and venv commands.

Initialize a project in a specific folder. The hello folder will be created.

uv init hello

Or initialize in the current working directory

uv init

To initialize a command line app that can be published to PyPI use the --package flag

uv init --package

If you want to create a library for others to use use --lib

uv init --lib

uv uses a src based directory structure. The src layout is particularly valuable when developing libraries. It ensures that the library is isolated from any python invocations in the project root and that distributed library code is well separated from the rest of the project source.

Manage dependencies

uv helps you manage project dependencies and keep them in sync with a lock file.

Add a single dependency

uv add requests

Add multiple dependencies at once

uv add A B C

Add dependencies from a requirements file

uv add -r requirements.txt

Add a development dependency

uv add --dev pytest

Run an executable installed in your project

uv run pytest

Remove a dependency

uv remove requests

Remove multiple dependencies and their transitive dependencies

uv remove A B C

View the project dependencies tree

uv tree

Upgrade the dependencies’ versions

uv lock --upgrade

Build and publish

uv supports building and publishing packageable projects to PyPI.

Build your packageable project

uv build

Publish your packageable project to PyPI

uv publish

Check your project version

uv version

Bump project major version (e.g., 0.3.2 -> 1.0.0)

uv version --bump major

Bump minor version into a beta (e.g., 1.0.0 -> 1.1.0b1 or 1.1.0b1 -> 1.1.0b2)

uv version --bump minor --bump beta

Bump version into release candidate (e.g., 1.1.0b1 -> 1.1.0rc1 or 1.1.0rc1 -> 1.1.0rc2)

uv version --bump rc

Turn into a stable version (e.g., 1.1.0rc1 -> 1.1.0)

uv version --bump stable

Working with scripts

uv supports Python scripts with inline dependency metadata.

Initialize a script file

uv init --script myscript.py

Initialize a script and pin it to a specific Python version

uv init --script myscript.py --python 3.X

Add a dependency to the script

uv add click --script myscript.py

Remove a dependency from the script

uv remove click --script myscript.py

Run the script

uv run myscript.py

Run the script with a specific Python version

uv run --python 3.X myscript.py

Run the script with an additional dependency

uv run --with click myscript.py

Managing tools

uv allows you to run and install tools in isolated environments without affecting your project dependencies.

Run a tool in an isolated environment

uv tool run pytest

Run a specific command from a package

uv tool run textual-demo --from textual

The uvx command is an alias for uv tool run

uvx pytest

Install a tool in an isolated environment but make it globally available

uv tool install ruff

Install a tool with extra dependencies (e.g., a tool with its plugins)

uv tool install --with dep package-name

List all installed tools

uv tool list

Upgrade a specific tool

uv tool upgrade ruff

Upgrade all tools

uv tool upgrade --all

Uninstall a tool

uv tool uninstall ruff

Install the current packageable project in editable mode

uv tool install -e .