iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article

⚡

The Complete Guide to uv: A Python Package Manager That Replaces pip, poetry, and pyenv

2026/03/14に公開

For years, it has been common knowledge in Python development to use pip, venv, poetry, and pyenv separately.

uv is a tool that aims to handle all of these with a single command.

What is uv?

uv is a Python package manager and project management tool written in Rust. It is developed by the same Astral team behind ruff (the lightning-fast linter for Python).

What uv replaces

Traditional tool	Purpose	uv equivalent
`pip`	Package installation and management	`uv pip install`
`venv` / `virtualenv`	Virtual environment creation and management	`uv venv`
`pip-tools`	Dependency lock file generation	`uv pip compile`
`pipx`	Isolated CLI tool installation	`uv tool install`
`pyenv`	Python version switching and management	`uv python install`
`poetry` / `hatch`	Project management and package building	`uv init` / `uv add`

It consolidates these tools into a single binary and achieves dependency resolution speeds 10–100x faster than pip.

Installation

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Homebrew (macOS / Linux)
brew install uv

# via pip (if an existing environment is available)
pip install uv

After installation, restart your shell or run source ~/.zshrc.

uv --version
# uv 0.6.x (...)

Python Version Management (Replacing pyenv)

Installing Python

# Install the latest stable Python
uv python install

# Install a specific version
uv python install 3.12
uv python install 3.11 3.12 3.13

# List installed Python versions
uv python list

Unlike pyenv, you do not need to append configuration to your shell. uv manages it automatically.

Switching Python Versions

# Pin the Python version for the project
uv python pin 3.12

# → A .python-version file will be created

Project Management (Replacing poetry)

Creating a New Project

uv init my-project
cd my-project

The following files will be generated:

my-project/
├── .python-version   # Python version
├── pyproject.toml    # Project settings / Dependencies
├── uv.lock           # Lock file (automatically generated)
├── README.md
└── hello.py

Contents of pyproject.toml:

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

Adding and Removing Dependencies

# Add packages (automatically reflected in pyproject.toml)
uv add requests
uv add fastapi uvicorn

# Specify version
uv add "django>=5.0"

# Add as development dependencies
uv add --dev pytest ruff mypy

# Remove package
uv remove requests

You can use it just like poetry add. uv.lock is also updated automatically.

Synchronizing Dependencies

# Sync virtual environment based on pyproject.toml
uv sync

# Sync including development dependencies
uv sync --dev

After git clone, simply running uv sync will prepare the environment.

Typical Project Startup Flow

Script Execution (Using without a Virtual Environment)

uv run

# Execute without explicitly activating a virtual environment
uv run python main.py
uv run pytest
uv run ruff check .

If .venv does not exist, it will automatically create one and run the command. This eliminates the need for source .venv/bin/activate.

Inline Script Dependencies (PEP 723)

By adding dependency information at the top of your script, uv can automatically install and run it.

#!/usr/bin/env -S uv run
# /// script
# dependencies = [
#   "requests",
#   "rich",
# ]
# ///

import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.json())

uv run fetch.py
# → Automatically installs requests and rich, then executes

You do not need to check for pre-installed libraries, and you can distribute the script as a standalone file.

Replacing pip (For existing projects and transition periods)

Existing pip commands can be replaced almost as-is with uv pip.

# Installation
uv pip install requests
uv pip install -r requirements.txt

# Uninstallation
uv pip uninstall requests

# Listing
uv pip list
uv pip freeze

# Compiling dependencies (Replacement for pip-tools)
uv pip compile requirements.in -o requirements.txt

Managing CLI Tools (Replacing pipx)

CLI tools that you want to install globally (such as ruff, httpie, or black) are managed using uv tool.

# Installation
uv tool install ruff
uv tool install httpie

# Temporary execution (Use without installation)
uvx ruff check .
uvx black .

# Listing
uv tool list

# Update
uv tool upgrade ruff
uv tool upgrade --all

uvx is a shortcut for uv tool run. It is convenient because you can try out tools without installing them.

Migrating from Existing Projects

Migrating from pip + requirements.txt

# Initialize in an existing directory
uv init --no-package

# Import dependencies from requirements.txt
uv add $(cat requirements.txt)

# Or generate a lockfile with pip compile
uv pip compile requirements.txt -o requirements.lock

Migrating from poetry

# If a pyproject.toml exists, uv will recognize it automatically
uv sync

# Convert poetry.lock to uv.lock
uv lock

Using in CI/CD

GitHub Actions

- name: Set up Python with uv
  uses: astral-sh/setup-uv@v5
  with:
    python-version: "3.12"

- name: Install dependencies
  run: uv sync --dev

- name: Run tests
  run: uv run pytest

The setup-uv action is officially provided, and it manages caching automatically.

Experience the Speed

According to the benchmarks in the official uv GitHub README, the following measurements were taken when installing the trio package without caching:

Tool	Installation Time	vs. pip (Speed)
pip	Approx. 11.2s	1x
poetry	Approx. 15.0s	0.75x (Slower than pip)
uv	Approx. 0.3s	Approx. 37x (Faster than pip)

With caching enabled, it is even faster, completing almost instantly. This has a significant impact on large-scale projects and reducing CI execution time.

Frequently Asked Questions

Q. Is it okay to keep using poetry?

Yes, that is fine. However, uv encapsulates almost all the functionality that poetry provides, and it is significantly faster. There is plenty of reason to choose uv for new projects.

Q. Should uv.lock be managed with git?

Yes, it should be committed. uv.lock is a guarantee for team members and CI to reproduce the exact same environment. It has the same purpose as poetry.lock or package-lock.json.

Q. Where is the virtual environment located?

By default, it is created in .venv/ at the project root. If you want to manage it globally, you can change it using the UV_PROJECT_ENVIRONMENT environment variable.

Q. Does it conflict with the system Python installation?

Python managed by uv is placed independently in ~/.local/share/uv/python/, so it does not conflict with the system Python.

Summary

Feature	Command
Install Python	`uv python install 3.12`
Create Project	`uv init`
Add Packages	`uv add requests`
Sync Dependencies	`uv sync`
Run Script	`uv run main.py`
Manage CLI Tools	`uv tool install ruff`
Replace pip	`uv pip install ...`

Setting up Python development can now be completed in two steps: curl ... | sh and uv sync. Start by trying out uv python install and uv init.

Reference Links

GitHubで編集を提案