uv: o gerenciador unificado

Este capítulo usa comandos de terminal. Os arquivos deste capítulo estão em exemplos/.

Por que eu uso o uv

O uv é feito pela Astral (os criadores do ruff) e escrito em Rust. O que me convenceu foi a combinação de três coisas: ele substitui pyenv, venv, pip, pipx e boa parte do Poetry; ele baixa Pythons prontos em vez de compilar; e ele tem uma interface compatível com o pip para quando você já tem um fluxo montado.

Instalar

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

Também é possível instalar com pipx install uv ou pip install uv. Se você instalou pelo instalador oficial, atualize com:

uv self update

Gerenciar versões de Python

O uv baixa e guarda as versões que você pedir. Não precisa de compilador nem de Python prévio:

uv python install 3.12 3.13 3.14
uv python list
uv python pin 3.13

O uv python pin grava o arquivo .python-version na pasta, o mesmo arquivo que o pyenv usa.

Criar e gerenciar um projeto

uv init meu-app
cd meu-app
uv add requests
uv add --dev pytest
uv run python main.py
uv run pytest

O uv add altera o pyproject.toml e atualiza o arquivo uv.lock. O uv run garante que o ambiente exista e esteja em dia antes de executar, então você não precisa ativar nada. O pyproject.toml fica assim:

[project]
name = "meu-app"
version = "0.1.0"
description = "Exemplo de projeto gerenciado pelo uv"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.34.2",
]

[dependency-groups]
dev = [
    "pytest>=9.1.1",
]

Outros comandos que eu uso o tempo todo:

uv remove requests
uv sync
uv lock
uv tree

Scripts com dependências embutidas

Para um script solto que precisa de uma biblioteca, o uv aceita metadados no próprio arquivo (um padrão chamado PEP 723). Ele cria um ambiente temporário só para aquela execução:

# /// script
# requires-python = ">=3.12"
# dependencies = ["rich"]
# ///
from rich import print

print("[bold]Olá[/bold] de um script com dependências embutidas")

uv run exemplos/uv/script_inline.py

Para adicionar uma dependência a um script existente: uv add --script script.py requests.

Ferramentas de linha de comando

uv tool install ruff
uvx ruff check .
uv tool list
uv tool upgrade --all

O uvx é um atalho para uv tool run: roda a ferramenta num ambiente temporário, como o pipx run.

Compatibilidade com o pip

Se você já tem requirements.txt e não quer migrar agora, use a interface compatível:

uv venv
uv pip install -r requirements.txt

uv add versus uv pip install

O uv add registra a dependência no pyproject.toml e no lockfile. O uv pip install só instala no ambiente, no estilo do pip, e não registra nada. Misturar os dois no mesmo projeto é a causa mais comum de "funciona na minha máquina".