install

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
scoop install uv

# With pip (if you must, not the preferred way though)
pip install uv


# on macOS 
brew install uv
eval "$(uv generate-shell-completion zsh)"

set UV_CACHE_DIR

By default, the cache is stored in $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Unix and %LOCALAPPDATA%\uv\cache on Windows.

setup a new project

init

1
2

uv init  uv_template --app
cd uv_template

the folder structure:

1
2
3
4
5
6
7

❯ dust
  0B   ┌── README.md      │█                                                                                      │   0%
 57B   │   ┌── __init__.py│█████████████████                                                                      │  20%
 57B   │ ┌─┴ uv_template  │█████████████████                                                                      │  20%
 57B   ├─┴ src            │█████████████████                                                                      │  20%
232B   ├── pyproject.toml │██████████████████████████████████████████████████████████████████████                 │  80%
289B ┌─┴ .                │██████████████████████████████████████████████████████████████████████████████████████ │ 100%

the pyproject.toml file which will look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

❯ cat .\pyproject.toml
[project]
name = "uv-template"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.10"
dependencies = []

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

python

List available Python versions

1

uv python list

install python

1
2
3
4
5
6


# install a specific Python version
uv python  install 3.10.6

# install within a version range
uv python install '>=3.8,<3.10'

Use a specific Python version in a project

1

uv python use <version>

Pin the Python version for a project

1

uv python pin

setup virtualenv

create virtual environment

1

uv venv --python 3.10.6

activate venv

1

.venv\Scripts\activate.ps1

install pip for venv

1

.venv/Scripts/python.exe -m ensurepip --upgrade

#### install ipykernel for venv

1

.venv/Scripts/python.exe -m pip install ipykernel -U --force-reinstall

Remove a virtual environment

1

uv remove

Reinstall all dependencies in the virtual environment

1

uv sync –reinstall

tool

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

uv tool install black

uv tool run ruff

uv tool dir

uv tool upgrade –all

# update shell (if needed)
uv tool update-shell

# check files or directories
uv tool run ruff check

packages

View Dependency Tree

1

uv tree

install

1

uv add  tqdm

after add tqdm, the pyproject.toml file which will look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

❯ cat  .\pyproject.toml
[project]
name = "uv-template"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "tqdm>=4.66.5",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

1

uv pip install requests

1
2
3
4

FROM python:3.11-bookworm 
RUN uv pip install - upgrade pip setuptools wheel 
COPY requirements.txt . 
RUN uv pip install -r requirements.txt

uninstall

1

uv remove pandas

turn pyproject.toml to requirements.txt

1

uv pip compile pyproject.toml -o requirements.txt

1
2
3
4
5
6
7
8

# Generate locked requirements
uv pip compile requirements.in -o requirements.lock

# Upgrade dependencies
uv pip compile requirements.in --upgrade -o requirements.lock

# Platform-specific locking
uv pip compile requirements.in --platform=linux --python-version=3.10 -o requirements.lock

sync

1
2

# Install dependencies from pyproject.toml
uv sync 

1

uv pip sync 

1

uv sync -p 3.12

1

uv pip sync requirements.txt

Upgrading Dependency Versions

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# upgrade a specific package
uv lock --upgrade-package pandas

# upgrade multiple packages
uv lock --upgrade-package numpy scipy matplotlib

# upgrade all dependencies
uv lock --upgrade

# dry run to see potential upgrades without applying
uv lock --upgrade --dry-run

tool

pytest

1

uv tool install --python 3.11 pytest

run

1
2
3
4
5
6

# app.py
import requests
from rich.pretty import pprint
response = requests.get("https://peps.python.org/api/peps.json")
data = response.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

1

uv add --script app.py 'requests<3' 'rich'

1

uv run - python 3.10 app.py

cache

1
2
3
4
5
6

# Clear UV’s cache before critical updates
uv cache clean

# Force a fresh installation
uv install --force

reference

uv cli