uv - A Ferramenta Rápida

uv é um gerenciador de pacotes Python tudo-em-um escrito em Rust. Ele substitui pip, venv, pip-tools e pyenv por uma única CLI rápida - o padrão recomendado para projetos Python 3.14.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Instalar uv
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Novo projeto
uv init myapp && cd myapp
uv add fastapi pydantic
uv run uvicorn myapp.main:app --reload
 
# Projeto existente
uv sync
uv run pytest

Quando usar isso:

• Iniciando um novo projeto Python 3.14
• Substituindo fluxos de trabalho lentos de pip install + venv manual
• Pipelines de CI que precisam de instalações de dependência em menos de um segundo
• Gerenciando múltiplas versões do Python sem pyenv

Exemplo de Trabalho

#!/usr/bin/env bash
set -euo pipefail
 
# Inicializar um serviço FastAPI com uv
uv init invoice-api
cd invoice-api
 
uv add "fastapi>=0.115" "uvicorn[standard]>=0.34" "pydantic>=2"
 
cat > src/invoice_api/main.py <<'PY'
from fastapi import FastAPI
from pydantic import BaseModel
 
app = FastAPI()
 
class Invoice(BaseModel):
    id: int
    amount: float
 
@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}
 
@app.post("/invoices")
def create(invoice: Invoice) -> Invoice:
    return invoice
PY
 
uv run uvicorn invoice_api.main:app --host 0.0.0.0 --port 8000

O que isso demonstra:

• uv init cria a estrutura pyproject.toml, src/ e .venv
• uv add resolve dependências e atualiza uv.lock
• uv run executa dentro do ambiente do projeto sem ativação manual
• Pontos de entrada são resolvidos automaticamente a partir do pacote src/

Mergulho Profundo

Como Funciona

• uv usa um cache global de pacotes e hardlinks para diretórios .venv por projeto.
• A resolução ocorre em Rust - tipicamente 10-100x mais rápido que o pip para árvores de dependência grandes.
• uv.lock é um lockfile universal (compatível com PEP 751) com versões exatas e hashes.
• uv python gerencia downloads de interpretadores junto com o gerenciamento de pacotes.

Comandos Principais

Notas Python

# Fixar interpretador para o projeto
uv python pin 3.14
 
# Executar com uma versão específica sem alterar o pin
uv run --python 3.13 pytest
 
# Atualizar todas as dependências
uv lock --upgrade

Armadilhas

• Esquecer uv sync após clonar - imports falham com ModuleNotFoundError. Correção: execute uv sync (ou uv sync --frozen em CI) antes de qualquer comando.
• Misturar pip e uv no mesmo venv - conflitos de metadados causam desvios sutis de versão. Correção: escolha uma ferramenta por projeto; use uv pip se precisar da semântica do pip.
• Não commitar uv.lock - colegas de equipe obtêm versões de dependência diferentes. Correção: comite o lockfile; use uv sync --frozen em CI.
• Executar uv add sem atualizar o lock - pyproject.toml e lockfile divergem. Correção: uv add atualiza ambos; se editar pyproject.toml manualmente, execute uv lock depois.
• uv pip install global - polui o interpretador do sistema. Correção: sempre trabalhe dentro de um projeto (uv init / uv sync) ou passe --python explicitamente.

Alternativas

FAQs

Relacionados

• Noções Básicas de Ambientes e Empacotamento - Fundamentos de venv e isolamento
• pyproject.toml Explicado - Estrutura de metadados do projeto
• Resolução de Dependências e Lockfiles - Estratégias de fixação
• Gerenciando Versões do Python - Testes multi-versão

Versões da Pilha: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.