Quickstart

Get started with uv in minutes - from installation to your first working Python project

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

macOS and Linux

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

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

pip install uv

pipx install uv

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 ruff@0.3.0 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.