Getting started with uv

by Tim Hopper

uv handles Python installation, project setup, dependency management, and script execution in a single tool. This tutorial walks through each of those capabilities so you can start using uv for any Python project.

Prerequisites

You need a terminal (Terminal on macOS, PowerShell on Windows, or any Linux shell). No prior Python installation is required.

Installing uv

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

Alternatively, install with Homebrew:

brew install uv

Verify the installation:

$ uv --version
uv 0.7.x

For platform-specific details, see How to install uv.

Creating a project

Initialize a new project

uv init my-project
cd my-project

Examine the generated files

uv init creates a ready-to-use project structure:

- pyproject.toml
- .python-version
- main.py
- README.md

Open pyproject.toml to see your project metadata:

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []

The .python-version file records which Python version the project uses. uv reads this file automatically and downloads that interpreter if it isn’t already installed. See What is a Python version file? for more on how this works.

Run the starter script

$ uv run main.py
Hello from my-project!

uv run creates a virtual environment in .venv/, installs the correct Python version, syncs any dependencies, and then runs your script. All of that happens automatically on the first run.

Tip

uv init creates an application project by default. For libraries, CLI tools, or other structures, see Understanding uv init project types.

Adding dependencies

Add a package

uv add requests

This command does three things: updates dependencies in pyproject.toml, resolves compatible versions and writes a lockfile (uv.lock), and installs the package into the project’s virtual environment.

Your pyproject.toml now includes:

dependencies = [
    "requests>=2.32.3",
]

Use the package in your code

Replace the contents of main.py with:

import requests

response = requests.get("https://httpbin.org/json")
data = response.json()
print(data["slideshow"]["title"])  # prints the title from the response

Run it:

$ uv run main.py
Sample Slide Show

Add a development dependency

Development tools like linters and test runners belong in a separate dependency group so they don’t ship with your project:

uv add --dev ruff

This adds ruff under a development dependency group in pyproject.toml. Run it with:

uv run ruff check .

Remove a package

uv remove requests

This updates pyproject.toml, regenerates uv.lock, and uninstalls the package from the virtual environment.

Running code and tools

uv run is the primary way to execute anything inside your project’s environment. It ensures dependencies are synced before every invocation.

# Run a Python script
uv run main.py

# Run a module
uv run -m http.server 8000

# Run a tool installed as a dependency
uv run ruff format .

To run a CLI tool that isn’t part of your project (a one-off invocation), use uvx:

# Run a tool without adding it as a dependency
uvx cowsay "hello uv"

For a deeper comparison, see When to use uv run vs uvx.

Managing Python versions

uv downloads and manages Python interpreters directly. No separate tool like pyenv is needed.

List available versions

$ uv python list

This shows all Python versions uv can install.

Install a specific version

uv python install 3.12

Pin a version to your project

uv python pin 3.12

This writes 3.12 to the .python-version file. The next time you run uv run, uv uses that version (installing it first if necessary).

Test against a different version

You can run a single command with a different Python version without changing the project pin:

uv run --python 3.11 main.py

What to explore next

You now know how to install uv, scaffold a project, manage dependencies, run code, and switch Python versions. Each of these topics goes deeper:

Complete guide to uv covers workspaces, lockfile strategies, and advanced configuration
Create your first Python project builds a text analysis tool from scratch using uv
Set up Ruff for formatting and checking your code adds linting and formatting to a uv project
Setting up testing with pytest and uv sets up a test suite with fixtures and coverage
How to translate pip commands to uv maps familiar pip workflows to uv equivalents
uv reference page for a concise overview of features, pros, and cons

Last updated on April 10, 2026

Create your first Python project with pixi Migrate a conda project to pixi

Please submit corrections and feedback...