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"
|
setup virtualenv
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'
|
create virtual environment
1
|
uv venv --python 3.10.6
|
1
2
3
4
5
6
7
8
9
10
11
12
|
uv tool install black
uv tool run ruff
uv tool dir
# update shell (if needed)
uv tool update-shell
# check files or directories
uv tool run ruff check
|
packages
View Dependency Tree
install
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
|
uninstall
turn pyproject.toml to requirements.txt
1
|
uv pip compile pyproject.toml -o requirements.txt
|
sync
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
|
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
|
reference
uv cli