This is a quick memo on how to use the Rust-based Python package & project manager, "uv".
Introduction
uv is a high-performance Python package and project manager written in Rust.
It aims to replace tools like:
- pip
- pip-tools
- pipx
- poetry
- pyenv
- twine
- virtualenv
Since its release in 2024, uv has quickly gained attention.
Nowadays, many Python projects are starting to use uv by default. Here is a quick note on how to get started.
# Python version used in this post $ python --version Python 3.11.9 # uv version $ uv --version uv 0.6.8 (c1ef48276 2025-03-18)
Note: This article was translated from my original post.
How to Use uv
Installing uv
On macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
On Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
You can also install it using pip or pipx:
pip install uv
pipx install uv
Listing uv Commands
To see all available uv commands, just run uv.
$ uv An extremely fast Python package manager. Usage: uv [OPTIONS] <COMMAND> Commands: run Run a command or script init Create a new project add Add dependencies to the project remove Remove dependencies from the project sync Update the project's environment lock Update the project's lockfile export Export the project's lockfile to an alternate format tree Display the project's dependency tree tool Run and install commands provided by Python packages python Manage Python versions and installations pip Manage Python packages with a pip-compatible interface venv Create a virtual environment build Build Python packages into source distributions and wheels publish Upload distributions to an index cache Manage uv's cache self Manage the uv executable version Display uv's version help Display documentation for a command Cache options: -n, --no-cache Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation [env: UV_NO_CACHE=] --cache-dir <CACHE_DIR> Path to the cache directory [env: UV_CACHE_DIR=] Python options: --managed-python Require use of uv-managed Python versions [env: UV_MANAGED_PYTHON=] --no-managed-python Disable use of uv-managed Python versions [env: UV_NO_MANAGED_PYTHON=] --no-python-downloads Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"] Global options: -q, --quiet Do not print any output -v, --verbose... Use verbose output --color <COLOR_CHOICE> Control the use of color in output [possible values: auto, always, never] --native-tls Whether to load TLS certificates from the platform's native certificate store [env: UV_NATIVE_TLS=] --offline Disable network access [env: UV_OFFLINE=] --allow-insecure-host <ALLOW_INSECURE_HOST> Allow insecure connections to a host [env: UV_INSECURE_HOST=] --no-progress Hide all progress outputs [env: UV_NO_PROGRESS=] --directory <DIRECTORY> Change to the given directory prior to running the command --project <PROJECT> Run the command within the given project directory --config-file <CONFIG_FILE> The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=] --no-config Avoid discovering configuration files (`pyproject.toml`, `uv.toml`) [env: UV_NO_CONFIG=] -h, --help Display the concise help for this command -V, --version Display the uv version Use `uv help` for more details.
We'll focus on some of the most common basic commands.
Creating a Python Project
uv init <project name> # Example: uv init myproject
This generates a project like this:
myproject ├── .python-version ├── README.md ├── main.py └── pyproject.toml 1 directory, 4 files
Initial file contents:
.python-version:
3.11
README.md:
# (blank)
main.py:
def main(): print("Hello from myproject!") if __name__ == "__main__": main()
pyproject.toml:
[project] name = "myproject" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.11" dependencies = []
Creating a Virtual Environment
uv venv
This creates a .venv folder and sets up a virtual environment:
$ tree -L 3 .venv .venv ├── CACHEDIR.TAG ├── bin │ ├── activate │ ├── activate.bat │ ├── activate.csh │ ├── activate.fish │ ├── activate.nu │ ├── activate.ps1 │ ├── activate_this.py │ ├── deactivate.bat │ ├── pydoc.bat │ ├── python -> /Users/bioerrorlog/.pyenv/versions/3.11.9/bin/python3.11 │ ├── python3 -> python │ └── python3.11 -> python ├── lib │ └── python3.11 │ └── site-packages └── pyvenv.cfg 5 directories, 14 files
To activate the virtual environment:
macOS/Linux:
source .venv/bin/activate
Windows:
.venv\Scripts\activate
Adding a Python Package
uv add <package name>
Example installing httpx:
$ uv add httpx Resolved 9 packages in 248ms Prepared 8 packages in 104ms Installed 8 packages in 15ms + anyio==4.9.0 + certifi==2025.1.31 + h11==0.14.0 + httpcore==1.0.7 + httpx==0.28.1 + idna==3.10 + sniffio==1.3.1 + typing-extensions==4.12.2
This updates pyproject.toml and creates/updates uv.lock.
As promised, uv add is noticeably faster than pip install.
Checking Installed Packages
Similar to pip freeze:
uv pip freeze
For example, if httpx is installed, the output will look like:
anyio==4.9.0 certifi==2025.1.31 h11==0.14.0 httpcore==1.0.7 httpx==0.28.1 idna==3.10 sniffio==1.3.1 typing-extensions==4.12.2
You can also view packages as a tree:
uv tree
Example output:
Resolved 9 packages in 9ms myproject v0.1.0 └── httpx v0.28.1 ├── anyio v4.9.0 │ ├── idna v3.10 │ ├── sniffio v1.3.1 │ └── typing-extensions v4.12.2 ├── certifi v2025.1.31 ├── httpcore v1.0.7 │ ├── certifi v2025.1.31 │ └── h11 v0.14.0 └── idna v3.10
Running Python Code
uv run main.py
Use uv run to run a Python script.
Conclusion
This was a simple memo of basic uv commands.
For more details, check out uv --help or the documentation.
Hope this helps someone!
[Related Articles]
