uv - python dependency manager

This article explains the essential uv commands to manage python version, python projects and to run python script with dependencies

UV Installation and Global Config

Install UV using brew on mac

brew install uv

Install UV using pip

pip install uv --upgrade

Other installation options

https://docs.astral.sh/uv/getting-started/installation

View available python versions

uv python list

List the python version and path used

uv python find

uv run python --version

Install specific versions of python

uv python install 3.10 3.12

Uninstall python versions

uv python uninstall 3.10 3.12

Pin default global python version

uv python pin 3.10 --global

Unpin default global python version

uv python pin --rm --global

Python Project

Init a project

uv init --vcs none --no-readme

Sync a project virutal environment and update the lock file

uv sync

Sync a project in CI without updating lock file

uv sync --locked

Pin a python version to project

uv python pin 3.10

Unpin a python version from project

uv python pin --rm

Add a dependency - latest version

uv add --raw requests

Add a dependency - specific version

uv add "requests==2.31.0"

Add a dependency with minimum version

uv add "tqdm>=4.66.2"

Add a dependency with range

uv add "tqdm>=4.66.2,<5"

Add a dev dependency

uv add --raw --dev "pytest"

Update all dependencies

uv sync --upgrade

Update specific dependencies

uv sync --upgrade-package requests

Update all dependencies (dev and non-dev) with specifiers

Update all non-dev dependencies

uv tree --no-dev -d 1 | sed '1d' | cut -d ' ' -f 2 | xargs -I {} echo 'uv remove {} && uv add --raw {}' | bash

Update all dev dependencies

uv tree --only-dev -d 1 | sed '1d' | cut -d ' ' -f 2 | xargs -I {} echo 'uv remove --dev {} && uv add --dev --raw {}' | bash

Remove a dependency

uv remove requests

Remove a dev dependency

uv remove --dev pytest

Create a lock file

uv lock

View dependency tree

uv tree

View dependency tree (direct depedency)

uv tree -d 1

Build a project

uv build

Setup additional indexes for dependencies with pypi as the default fallback

Add the following lines to the end in pyproject.toml

[[tool.uv.index]]

name = "pytorch-cu118"

url = "https://download.pytorch.org/whl/cu118"

[[tool.uv.index]]

name = "pytorch-cu124"

url = "https://download.pytorch.org/whl/cu124"

Do not use pypi as default index for dependencies

In enterprise environment, it is preferred to use an internal mirror of pypi instead of directly pulling the dependencies from pypi index, hence the following setting will disable the default public pypi and use only internal index and mirror. To disable public pypi index, make one of the declared index as default. Example configuration to be added to pyproject.toml

[[tool.uv.index]]

name = "mirror-pypi"

url = "https://internal-mirror-pypi.example.org"

default = true

[[tool.uv.index]]

name = "additional-index"

url = "https://additional-index.example.org"

Python Scripts

Run a python script with project dependencies

uv run example.py

Run a python script with arguments

uv run example.py test

Run a python script without project dependencies

uv run --no-project example.py

Run a python script with specific python version

uv run --python 3.9 example.py

Run a python script with additional dependencies

uv run --with 'rich==14.1.0' --with 'requests==2.32.5' example.py

Run a python script with depedencies defined as inline comment

Add the following lines to top of the python script

# /// script
# requires-python = ">=3.12"
# dependencies = [
# "requests==2.32.5",
# "rich==14.1.0",
# ]
# ///

uv run example.py

Tool management

Install a tool

uv tool install ruff

Run a tool

uv tool run ruff

Arguments can be appended after the tool name

uv tool run pycowsay hello from uv

Uninstall a tool

uv tool uninstall ruff

List installed tools

uv tool list

Update shell after tool add / remove

uv tool update-shell

Low level operations

Create a virtual environment

With default python and project dependencies in current directory

uv venv .venv

Create a virtual environment in specified directory

uv venv $HOME/Downloads/.venv

Create a virtual environment with specific python version

uv venv --python 3.12 .venv

Create a virtual environment without project dependencies

uv venv --no-project .venv

Create requirements from pip dependencies and install directly using pip

First sync the lock file with pyproject.toml dependencies

uv sync

Then create requirements.txt without dev dependencies

uv export --no-dev --format requirements-txt > requirements.txt

Install the dependencies in the python environment or virtual environment

pip install -r requirements.txt

Similarly create requirements.txt with dev dependencies

uv export --all-groups --format requirements-txt > requirements_dev.txt

Install the dependencies in the python environment or virtual environment

pip install -r requirements_dev.txt

Install from pip requirements as project dependencies and add to pyproject.toml

pip freeze > requirements.txt

uv add -r requirements.txt

View pip dependency tree

uv pip tree

Utility Commands

Remove cache entries

uv cache clean

Remove outdated cache entries

uv cache prune

Show the uv cache directory path

uv cache dir

Show the uv tool directory path

uv tool dir

Show the uv installed Python versions path

uv python dir