Skip to main content
uv is an extremely fast Python package and project manager. This guide will get you from installation to running your first project in minutes.

​
Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh
Verify the installation: 
uv --version
If installed via the standalone installer, you can update uv with uv self update

​
Create your first project

1

Initialize a new project

Create a new Python project with uv init:
$ uv init example
Initialized project `example` at `/home/user/example`
This creates a project structure with:
  • pyproject.toml - Project metadata and dependencies
  • .python-version - Python version pin
  • main.py - Sample Python file
  • README.md - Project documentation
2

Add a dependency

Navigate to your project and add a package:
$ cd example

$ uv add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
   Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
 + example==0.1.0 (from file:///home/user/example)
 + ruff==0.5.0
uv automatically:
  • Creates a virtual environment (.venv)
  • Updates pyproject.toml with the dependency
  • Generates a lockfile (uv.lock)
  • Installs the package
3

Run a command

Execute commands in your project environment with uv run:
$ uv run ruff check
All checks passed!
Run your Python script:
$ uv run main.py
Hello from example!

​
Working with dependencies

​
Lock and sync workflow

Generate or update the lockfile without installing: 
$ uv lock
Resolved 2 packages in 0.33ms
Sync your environment with the lockfile: 
$ uv sync
Resolved 2 packages in 0.70ms
Audited 1 package in 0.02ms
uv run automatically syncs before running, so you don’t need to manually run uv sync in most cases

​
Add dependencies with version constraints

# Specific version
$ uv add 'requests==2.31.0'

# Version range
$ uv add 'requests>=2.30.0,<3.0.0'

# Git dependency
$ uv add git+https://github.com/psf/requests

​
Remove dependencies

$ uv remove requests

​
Manage Python versions

uv can install and manage Python versions for you.

​
Install Python

$ uv python install 3.12 3.13 3.14
Installed 3 versions in 972ms
 + cpython-3.12.12-macos-aarch64-none (python3.12)
 + cpython-3.13.9-macos-aarch64-none (python3.13)
 + cpython-3.14.0-macos-aarch64-none (python3.14)

​
Use a specific Python version

Pin your project to a specific Python version: 
$ uv python pin 3.11
Pinned `.python-version` to `3.11`
Create a virtual environment with a specific Python version: 
$ uv venv --python 3.12.0
Using Python 3.12.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

​
View installed Python versions

$ uv python list

​
Run tools with uvx

Execute Python tools without installing them using uvx (an alias for uv tool run): 
$ uvx pycowsay 'hello world!'
Resolved 1 package in 167ms
Installed 1 package in 9ms
 + pycowsay==0.0.0.2
  """

  ------------
< hello world! >
  ------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||
Run a specific version of a tool: 
$ uvx [email protected] check

​
Install tools globally

For tools you use frequently, install them to make them available system-wide: 
$ uv tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
 + ruff==0.5.0
Installed 1 executable: ruff

$ ruff --version
ruff 0.5.0

​
Next steps

Now that you have uv set up, explore more capabilities:

Working on Projects

Learn about project structure, managing dependencies, and building distributions

Running Scripts

Execute single-file scripts with inline dependency declarations

Python Installation

Deep dive into installing and managing Python versions

Using Tools

Master tool installation and management with uv and uvx
New to Python packaging? Check out our concepts guide to understand how uv manages projects, dependencies, and environments.

Build docs developers (and LLMs) love

Get started for freeTalk to us