Skip to content

Commit fa1431b

Browse files
copdipscopdips
committed
update python uv cheat sheet
1 parent 03b9cd9 commit fa1431b

1 file changed

Lines changed: 69 additions & 29 deletions

File tree

‎docs/posts/2025/2025-08-26-python-uv-cheat-sheet.md‎

Lines changed: 69 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -7,22 +7,29 @@ categories:
77
comments: true
88
date:
99
created: 2025-08-26
10+
updated: 2025-08-28
1011
---
1112

1213
# Python uv cheat sheet
1314

14-
Python [UV](https://docs.astral.sh/uv/) common usage cheat sheet, but doesn't cover all the features.
15+
Python [uv](https://docs.astral.sh/uv/) common usage cheat sheet, but doesn't cover all the features.
1516

1617
<!-- more -->
1718

1819
## Init project
1920

20-
```bash
21-
# init new project with new folder
22-
uv init my-project -p python3.13
21+
uv init can have 3 templates: [`--app`](https://docs.astral.sh/uv/concepts/projects/init/#packaged-applications) (by default), [`--lib`](https://docs.astral.sh/uv/concepts/projects/init/#applications) and [`--package`](https://docs.astral.sh/uv/concepts/projects/init/#packaged-applications).
22+
23+
| Command | Description |
24+
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
25+
| `uv init my-project -p python3.13` | Init new project with new folder |
26+
| `uv init -p python3.13` | Init an existing project with python3.13 |
27+
| `uv init --lib` | Libraries template creates a src folder whereas application template only creates a main.py file |
28+
| `uv init --package` | Init a project with package template, same as libraries but pyproject.toml has a `[project.scripts]` key, so this is for command-line interface you can later run the command by: `uv run pkg-1` |
2329

24-
# init an existing project
25-
uv init -p python3.13
30+
```toml title="pyproject.toml created by uv init --package pkg-1"
31+
[project.scripts]
32+
pkg-1 = "pkg_1:main"
2633
```
2734

2835
!!! warning "uv init under a folder with already a pyproject.toml"
@@ -100,6 +107,27 @@ typing = [
100107

101108
```
102109

110+
### Add to dependency sources
111+
112+
[Dependency sources](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-sources) are for local development only.
113+
114+
```bash
115+
uv add git+https://github.com/encode/httpx
116+
uv add --editable ../temp1/lib_1
117+
```
118+
119+
```toml
120+
[project]
121+
name = "temp"
122+
...
123+
[tool.uv.sources]
124+
httpx = { git = "https://github.com/encode/httpx" }
125+
lib-1 = { path = "../temp1/lib_1", editable = true }
126+
```
127+
128+
!!! note
129+
For multiple packages in the same repository, [workspaces](https://docs.astral.sh/uv/concepts/projects/workspaces/) may be a better fit.
130+
103131
## Install dependencies
104132

105133
```toml title="pyproject.toml"
@@ -141,40 +169,48 @@ all = [
141169

142170
!!! note "use `uv sync --dry-run` to see what will be the changes"
143171

144-
- Install dependencies only: `uv sync --no-dev` (without any extra nor any group)
145-
- Install dependencies and `dev` group: `uv sync`
146-
- Install dependencies and all groups (dependency-groups): `uv sync --all-groups`
147-
- Install dependencies and all extras (project.optional-dependencies) and `dev` group: `uv sync --all-extras` (`dev` group is by default)
148-
- Install dependencies and all extras and all groups: `uv sync --all-extras --all-groups`
149-
- Install dependencies and extra `aio` and `dev` group: `uv sync --extra aio`
150-
- Install dependencies and extra `aio` but without `dev` group: `uv sync --extra aio --no-dev`
151-
- Install dependencies and `dev` groups and already installed extraneous packages not declared in pyproject.toml: `uv sync --extra aio --inexact`
172+
| Command | Description |
173+
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
174+
| `uv sync --no-dev` | Install [dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#project-dependencies) only (without any extra nor any group) |
175+
| `uv sync` | Install dependencies and `dev` group, no extras, no other groups than `dev` |
176+
| `uv sync --all-groups` | Install dependencies and all groups ([`dependency-groups`](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups)) |
177+
| `uv sync --all-extras` | Install dependencies and all extras ([`project.optional-dependencies`](https://docs.astral.sh/uv/concepts/projects/dependencies/#optional-dependencies)) and `dev` group (`dev` group is by default) |
178+
| `uv sync --all-extras --all-groups` | Install dependencies and all extras and all groups |
179+
| `uv sync --extra aio` | Install dependencies and extra `aio` and `dev` group |
180+
| `uv sync --extra aio --no-dev` | Install dependencies and extra `aio` but without `dev` group |
181+
| `uv sync --extra aio --inexact` | Install dependencies and `dev` groups and retain already installed [extraneous packages](https://docs.astral.sh/uv/concepts/projects/sync/#retaining-extraneous-packages) not declared in pyproject.toml |
182+
| `uv sync --locked --no-dev` | Ensure install by respecting `uv.lock` (ensure uv.lock won't be changed after uv sync) and raise error if lock file doesn't conform with pyproject.toml.<br/><br/>In 🐳 Dockerfile ([official uv Dockerfile example](https://github.com/astral-sh/uv-docker-example/blob/main/Dockerfile)), we often use `uv sync --locked --no-install-project --no-dev`, see [Using uv in Docker](https://docs.astral.sh/uv/guides/integration/docker/) to understand the usage of each parameters. |
152183

153-
- Ensure install by respecting `uv.lock` (ensure uv.lock won't be changed after uv sync) and raise error if lock file doesn't conform with pyproject.toml: `uv sync --locked --no-dev`, in Dockerfile ([official uv Dockerfile example](https://github.com/astral-sh/uv-docker-example/blob/main/Dockerfile)), we often use `uv sync --locked --no-install-project --no-dev`, see [Using uv in Docker](https://docs.astral.sh/uv/guides/integration/docker/) to understand the usage of each parameters.
154-
155-
```bash
156-
$ uv sync --locked --no-dev
157-
Resolved 21 packages in 33ms
158-
The lockfile at `uv.lock` needs to be updated, but `--locked` was provided. To update the lockfile, run `uv lock`.
159-
```
184+
```bash
185+
$ uv sync --locked --no-dev
186+
Resolved 21 packages in 33ms
187+
The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.
188+
To update the lockfile, run `uv lock`.
189+
```
160190

161191
## Dependencies tree
162192

163-
- `uv pip tree`: display the **installed packages** in a tree format.
164-
- `uv tree`: update `uv.lock` based on `pyproject.toml` and display tree based on `uv.lock`, **no package installation will occur**. `uv tree` displays better than `uv tree pip tree`
165-
- `uv tree --frozen`: don't update `uv.lock`, just display tree based on the current `uv.lock`
166-
- `uv tree --locked`: if `uv.lock` is not updated, display a warning message. This command is not very useful.
193+
| Command | Description |
194+
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
195+
| `uv pip tree` | Display the **installed packages** in a tree format |
196+
| `uv tree` | Update `uv.lock` based on `pyproject.toml` and display tree based on `uv.lock`, **no package installation will occur**. `uv tree` displays better than `uv pip tree` |
197+
| `uv tree --frozen` | Don't update `uv.lock`, just display tree based on the current `uv.lock` |
198+
| `uv tree --locked` | If `uv.lock` is not updated, display a warning message. This command is not very useful |
167199

168200
## List outdated packages
169201

170202
- `uv tree --outdated`: display a list of outdated packages with their latest versions.
171203

172204
## Upgrade packages and uv.lock
173205

174-
- `uv lock`: update the `uv.lock` file to match the current state of `pyproject.toml`.
175-
- `uv lock -U`: update the `uv.lock` file and upgrade all packages to their latest compatible versions.
176-
- `uv sync`: same as `uv lock` but also installs the dependencies.
177-
- `uv sync -U`: same as `uv lock -U` but also installs the dependencies.
206+
[`uv.lock` file](https://docs.astral.sh/uv/concepts/projects/layout/#the-lockfile)can be updated by `uv lock`, `uv sync`, `uv run`, `uv add`, `uv remove`.
207+
208+
| Command | Description |
209+
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
210+
| `uv lock` | Update the `uv.lock` file to match the current state of `pyproject.toml` |
211+
| `uv lock -U` | Update the `uv.lock` file and [upgrade](https://docs.astral.sh/uv/concepts/projects/sync/#upgrading-locked-package-versions) all packages to their latest compatible versions |
212+
| `uv sync` | Same as `uv lock` but also installs the dependencies |
213+
| `uv sync -U` | Same as `uv lock -U` but also installs the dependencies |
178214

179215
!!! note "`uv lock` vs `uv lock -U` and `uv sync` vs `uv sync -U`"
180216
If latest version of fastapi is 0.116.1, and pyproject.toml declares fastapi>=0.115.1, and current uv.lock has fastapi==0.115.1. then:
@@ -187,3 +223,7 @@ all = [
187223
## Integrations
188224

189225
Check [this doc](https://docs.astral.sh/uv/guides/integration/) for more information on integrations with other tools and platforms (Docker, Jupyter, Github Actions, Pre Commit, PyTorch FastAPI, etc.).
226+
227+
## Build
228+
229+
uv can also [build with extension module by `--build-backend` flag](https://docs.astral.sh/uv/concepts/projects/init/#projects-with-extension-modules) to work with Rust and C, C++, CPython etc.

0 commit comments

Comments
 (0)