🦉 Knowledge Base

uv

3 min read

what is it?

extremely fast python package and project manager, written in rust. see link

installation

curl -LsSf https://astral.sh/uv/install.sh | sh

creating a new project

mkdir hello-world
cd hello-world
uv init

will create the following

❯ uv init
Initialized project `hello-world`
❯ ll
drwxr-xr-x   - devuntu 27 Oct 22:42 .git
.rw-r--r-- 109 devuntu 27 Oct 22:42 .gitignore
.rw-r--r--   5 devuntu 27 Oct 22:42 .python-version
.rw-r--r--  89 devuntu 27 Oct 22:42 hello.py
.rw-r--r-- 157 devuntu 27 Oct 22:42 pyproject.toml
.rw-r--r--   0 devuntu 27 Oct 22:42 README.md
❯

uv venv or the project commands(uv run, uv sync, or uv lock) will create a virtual environment, if it doesn’t already exist

❯ uv run hello.py
Using CPython 3.12.3 interpreter at: /usr/bin/python3
Creating virtual environment at: .venv
Hello from hello-world!
❯ ll
drwxr-xr-x   - devuntu 27 Oct 22:42 .git
drwxr-xr-x   - devuntu 27 Oct 22:51 .venv
.rw-r--r-- 109 devuntu 27 Oct 22:42 .gitignore
.rw-r--r--   5 devuntu 27 Oct 22:42 .python-version
.rw-r--r--  89 devuntu 27 Oct 22:42 hello.py
.rw-r--r-- 157 devuntu 27 Oct 22:42 pyproject.toml
.rw-r--r--   0 devuntu 27 Oct 22:42 README.md
.rw-r--r-- 118 devuntu 27 Oct 22:51 uv.lock

uv.lock

uv.lock is a cross-platform lockfile that contains exact information about your project’s dependencies. unlike the pyproject.toml which is used to specify the broad requirements of your project, the lockfile contains the exact resolved versions that are installed in the project environment. this file should be checked into version control, allowing for consistent and reproducible installations across machines.

uv.lock is a human-readable toml file but is managed by uv and should not be edited manually.

see the lockfile documentation for more details

existing project

for existing projects with a requirements.txt

uv pip sync requirements.txt
# most pip commands work, i.e uv pip list, uv pip install, etc.
❯ uv pip sync requirements.txt
Resolved 13 packages in 8ms
   Built lazy-object-proxy==1.3.1
   Built wrapt==1.10.11
Prepared 3 packages in 855ms
Installed 13 packages in 153ms
 + astroid==2.0.4
 + django==2.2
 + djangorestframework==3.11.0
 + isort==4.3.4
 + lazy-object-proxy==1.3.1
 + mccabe==0.6.1
 + psycopg2-binary==2.9.10
 + pycodestyle==2.4.0
 + python-dotenv==1.0.1
 + pytz==2018.5
 + six==1.11.0
 + whitenoise==5.1.0
 + wrapt==1.10.11

this installs the the packages in requirements.txt into the venv directory.

to update the uv.lock file, use uv add

❯ uv add -r requirements.txt
Resolved 15 packages in 31ms
Installed 1 package in 2ms
 + sqlparse==0.5.1

this updates the the pyproject.toml and uv.lock files

❯ cat pyproject.toml
[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "astroid==2.0.4",
    "django==2.2",
    "djangorestframework==3.11.0",
    "isort==4.3.4",
    "lazy-object-proxy==1.3.1",
    "mccabe==0.6.1",
    "psycopg2-binary>=2.9.10",
    "pycodestyle==2.4.0",
    "python-dotenv>=1.0.1",
    "pytz==2018.5",
    "six==1.11.0",
    "whitenoise==5.1.0",
    "wrapt==1.10.11",
]

add these artifacts to git. for other people checking out the project, the workflow would then be

  • install uv
  • git clone the project
  • run uv sync to build the virtual environment and install the packages and dependencies specified in pyproject.toml and uv.lock

Graph View

Backlinks