uv

uv is designed to be a drop-in replacement for almost every major tool in the Python development lifecycle.

• Manages and installs multiple Python versions automatically.
• Provides full project management with a universal lockfile (uv.lock) for reproducible builds.
• It can run and install Python-based CLI tools in isolated environments.
• Creates and manages virtual environments at lightning speed.
• Handles package uploads and distribution.

INFO

When to use: uv is designed exclusively for Python-based projects and backends, as its dependency management is scoped strictly to the Python ecosystem.

Installation

Linux

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

Core Workflow

WARNING

Don't "brainlessly" run following commands. Replace placeholder values inside <> first.

Project Management

Create

New project

# Create project with a ready-to-use pyproject.toml
uv init <project_name>

Current folder

# Turn current directory into a uv-managed project
uv init

Library package

# Create package-style layout instead of plain app skeleton
uv init --lib <project_name>

If the project already exists, you can install the dependencies recorded in pyproject.toml and uv.lock:

uv sync

TIP

uv run <command> auto-uses project environment, so manual activation is often not needed.

Dependencies

Add

# Add runtime dependency and update lockfile
uv add <package_name>

Add dev dependency

# Good for linters, formatters, test tools
uv add --dev <package_name>

Remove

# Remove dependency from project metadata and lockfile
uv remove <package_name>

Upgrade one package

# Refresh specific dependency to newer compatible version
uv lock --upgrade-package <package_name>

Upgrade all

# Re-resolve full lockfile against latest allowed versions
uv lock --upgrade

If the lockfile already exists and you only want to install exact locked versions again:

uv sync --frozen

Run

Python script

# Run code inside uv-managed environment
uv run python <script_name>.py

Module

# Useful for package entry points and tools
uv run python -m <module_name>

Pytest

# Example: test execution without manual activation
uv run pytest

txt

Python Versions

Install Python

# Download and register Python version for local use
uv python install 3.11

List available

# Show discoverable and installed Python versions
uv python list

Pin version

# Write preferred interpreter version into .python-version
uv python pin 3.11

TIP

Pinned Python version helps teams keep the same interpreter across machines.

Virtual Environments

Default .venv

# Create local virtual environment in current project
uv venv

Custom path

# Create environment with custom folder name
uv venv <env_name>

Specific Python

# Build environment with exact interpreter version
uv venv --python 3.11

To activate manually:

source .venv/bin/activate

To leave the environment:

deactivate

Tools

uv tool installs Python CLI apps in isolated environments, similar to pipx.

Install tool

# Install CLI globally without polluting project deps
uv tool install <tool_name>

Run once

# Download if needed, run, then reuse cached environment later
uvx <tool_name>

Upgrade tool

# Refresh installed CLI tool to newer version
uv tool upgrade <tool_name>

Remove tool

# Uninstall previously installed CLI tool
uv tool uninstall <tool_name>

pip-Compatible Commands

uv pip becomes useful when you need fast pip-style commands inside an existing virtual environment.

Install

# Install package into active environment
uv pip install <package_name>

Remove

# Uninstall package from active environment
uv pip uninstall <package_name>

List

# Show installed packages in active environment
uv pip list

Freeze

# Export exact installed versions
uv pip freeze > requirements.txt

Example Flow

uv init myapp
cd myapp
uv python pin 3.11
uv add fastapi uvicorn
uv add --dev pytest ruff
uv run main.py

Official reference: https://docs.astral.sh/uv/