uv: O gerenciador de pacotes Python que substitui pip, pip-tools e venv (Guia 2026)

Se você passou algum tempo em um projeto Python este ano, provavelmente já viu uv aparecer em um arquivo README ou CI. É um gerenciador de pacotes escrito em Rust e uma ferramenta virtualenv da Astral (a mesma equipe por trás do ruff) - e é 10-100x mais rápido que a combinação clássica pip / pip-tools / venv.

Este guia aborda: o que o uv realmente substitui, os cinco comandos que cobrem 95% do que você faz diariamente e os dois casos em que você deve usar as ferramentas clássicas.

O que uv substitui

| Ferramenta clássica | equivalente UV | Aceleração |

|---|---|---|

| python -m venv .venv | uv venv | ~5x |

| pip install pkg | uv pip install pkg | ~10-50x |

| pip install -r requirements.txt | uv pip install -r requirements.txt | 20-100x em cache frio |

| pip-compile (ferramentas pip) | uv pip compile | ~50x |

| python -m venv + source activate para cada projeto | uv run <cmd> | Ignora totalmente a ativação |

A diferença de velocidade é real. A instalação de um projeto Django moderado (Django + DRF + aipo + redis + boto3 + ~40 deps transitivos) em um cache frio leva aproximadamente 45 segundos com pip e aproximadamente 2 segundos com uv. Em um cache quente, o UV é essencialmente instantâneo porque usa um cache global com link físico em vez de copiar arquivos em cada local.

Os cinco comandos que você realmente usará

1. Instale o próprio uv

BASH
# macOS + Linux — one line, no sudo, no Python needed
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Or via brew / apt / your package manager (updated frequently)
brew install uv

uv é um binário único e independente - sem inicialização do Python, sem dependências próprias.

2. Crie um ambiente virtual

BASH
cd my-project
uv venv                       # creates .venv/ using the current Python
uv venv --python 3.13         # or pin a version — uv will download it if missing

Ao contrário de python -m venv, uv pode buscar a versão do Python que você solicitou. Chega de dança de três passos do tipo "pyenv install, venv e então ativar".

3. Instale pacotes

BASH
uv pip install fastapi httpx        # into the current venv
uv pip install -r requirements.txt  # bulk install
uv pip install -e .                 # editable install of current project

A sintaxe é intencionalmente idêntica a pip - troque pip por uv pip e tudo funciona. Custo de migração: cinco pressionamentos de tecla.

4. Requisitos de congelamento/compilação

BASH
# From an installed venv → requirements.txt (like `pip freeze`)
uv pip freeze > requirements.txt

# From a loose requirements.in → fully pinned requirements.txt (like pip-compile)
uv pip compile requirements.in -o requirements.txt

A etapa compile é determinística - mesma entrada, mesma saída, byte por byte. Perfeito para CI reproduzível.

5. Execute um comando sem ativar o venv

BASH
uv run pytest                    # runs pytest from the current venv
uv run python manage.py migrate  # any command, any script
uv run --with ipython python     # temporarily add ipython for this session

Este é o recurso matador. Chega de source .venv/bin/activate antes de cada comando. Ótimo em CI, ótimo em Makefiles, ótimo em shell scripts.

Migrando um projeto existente (2 minutos)

Supondo que você tenha um requirements.txt:

BASH
# 1. Nuke the old venv
rm -rf .venv

# 2. Create the uv venv
uv venv

# 3. Install
uv pip install -r requirements.txt

# 4. Verify
uv run python -c "import fastapi; print(fastapi.__version__)"

Quatro comandos, concluídos. Seu requirements.txt não precisa ser alterado. Seu pyproject.toml não precisa mudar. Seu CI quase não precisa mudar – troque a etapa de instalação e pronto.

O caminho nativo pyproject.toml (projetos uv-first)

Para projetos começando do zero, use o fluxo de trabalho nativo do uv — sem nenhum arquivo requirements.txt:

BASH
uv init my-project     # generates pyproject.toml + .python-version + .gitignore
cd my-project
uv add fastapi         # adds fastapi to pyproject.toml [dependencies] AND installs
uv add --dev pytest    # adds to dev-dependencies
uv sync                # installs exactly what pyproject.toml says (uses uv.lock)
uv lock --upgrade      # bumps every dependency to its latest compatible version

Este é o mesmo formato de cargo para Rust ou npm para Node — um arquivo de configuração, um arquivo de bloqueio, instalações determinísticas. Se você está começando do zero em 2026, este é o caminho.

Quando ainda usar pip / venv

Dois casos:

1. Sistemas CI legados que não podem instalar o uv. Se você estiver preso a um agente Jenkins de 2019 sem acesso ao shell, o atrito da instalação do uv pode superar o ganho de velocidade. Todo sistema CI moderno (GitHub Actions, GitLab CI, CircleCI, BuildKite) possui um instalador UV de uma linha.

2. Ambientes airgapped com um espelho `pip` bloqueado. uv é padronizado como PyPI, mas suporta --index-url — isso geralmente funciona, mas alguns espelhos corporativos têm comportamentos sutis (cabeçalhos de autenticação, API JSON vs API simples) que uv trata de maneira diferente. Teste antes de se comprometer.

É isso. Para todos os outros casos em 2026 – desenvolvimento solo, projetos de equipe, código aberto, CI, Docker – o uv é mais rápido, mais confiável e requer menos sobrecarga mental do que a pilha clássica.

A troca de CI de 30 segundos

Antes (ações do GitHub):

YAML
- uses: actions/setup-python@v5
  with:
    python-version: '3.13'
- run: pip install -r requirements.txt
- run: pytest

Depois:

YAML
- uses: astral-sh/setup-uv@v3
- run: uv sync
- run: uv run pytest

As execuções do CI caem de aproximadamente 2 minutos para aproximadamente 15 segundos na etapa de instalação. Se sua matriz de teste for executada 5x por PR, isso representa uma economia cumulativa real.

uv é a ferramenta rara que é ao mesmo tempo mais rápida E mais simples do que a que substitui. Se você ganhar a vida escrevendo Python em 2026, gaste 10 minutos trocando um projeto. O hábito será levado a cada novo projeto que você tocar.

Próxima etapa: o curso Python DevOps abrange uv, ruff, Docker e a moderna pilha de implantação do Python — 104 lições interativas.