powered byiMasterstutoriais · referência · código em portuguêsPatrocínio
Python

Como o uv unifica venv, pip e requirements.txt num só fluxo de projeto

O guia oficial de projetos do uv mostra como uv init, uv add, o lockfile e uv run substituem a combinação venv, pip e requirements.txt.

Por Isabela FonsecaColunista6 min de leitura
Imagem gerada por IA

O guia oficial de projetos do uv mostra como uv init, uv add, o lockfile e uv run substituem a combinação venv, pip e requirements.txt.

O que você vai conseguir fazer

Ao final deste tutorial você monta um projeto Python do zero com uv, adiciona e remove dependências sem mexer em venv ou pip, trava as versões exatas no lockfile e roda o código com um único comando. Testei o fluxo com Python 3.14, a versão mínima que os templates do uv já assumem no pyproject.toml gerado, e com a faixa 0.13/0.14 do uv, a que fixa o build backend uv_build>=0.13.9,<0.14 nos projetos novos.

Criando o projeto com uv init

Duas formas equivalentes de começar:

bash
uv init hello-world
cd hello-world

ou, dentro de uma pasta já criada:

bash
mkdir hello-world
cd hello-world
uv init

O uv init cria um repositório git com .gitignore, o pyproject.toml, o .python-version, um README.md e o pacote em src/hello_world/__init__.py. Nesse ponto ainda não existe .venv nem uv.lock: eles só aparecem quando você roda o primeiro comando de projeto.

bash
uv run hello-world

Saída esperada:

Hello from hello-world!

Esse comando já cria o .venv e o uv.lock na primeira execução, mesmo sem nenhuma dependência declarada ainda.

Entendendo os arquivos que o uv criou

Depois de rodar um comando de projeto, a árvore fica assim:

.
├── .venv/
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── src
│   └── hello_world
│       └── __init__.py
└── uv.lock

Cada peça tem um papel fixo:

  • pyproject.toml: metadados do projeto (nome, versão, dependências, scripts) e a configuração do [tool.uv] quando você precisar dela.
  • .python-version: a versão de Python que o uv usa para criar o venv deste projeto específico.
  • .venv: o ambiente isolado de verdade, equivalente ao que python -m venv criaria na mão.
  • uv.lock: as versões exatas resolvidas, em TOML legível, mas gerenciado pelo uv.

pyproject.toml: o coração do projeto

Um pyproject.toml gerado pelo uv init se parece com isto:

toml
[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
    { name = "ferris", email = "ferris@example.com" }
]
requires-python = ">=3.14"
dependencies = []

[project.scripts]
hello-world = "hello_world:main"

[build-system]
requires = ["uv_build>=0.13.9,<0.14"]
build-backend = "uv_build"

Dá pra editar esse arquivo na mão, mas o fluxo recomendado é deixar uv add e uv remove cuidarem da seção dependencies, porque eles sincronizam pyproject.toml, uv.lock e .venv numa chamada só.

Adicionando dependências com uv add

bash
uv add requests

Esse comando resolve a versão, grava a entrada em dependencies no pyproject.toml, atualiza o uv.lock e instala o pacote no .venv. Dá pra ser mais específico:

bash
# trava uma versão exata
uv add 'requests==2.31.0'

# instala direto de um repositório git
uv add git+https://github.com/psf/requests

Para tirar uma dependência, o caminho inverso:

bash
uv remove requests

Atualizando sem perder o resto do lockfile

Quando você quer puxar uma versão mais nova de um pacote específico, sem mexer no restante do que já está travado:

bash
uv lock --upgrade-package requests

A flag --upgrade-package sobe o pacote indicado até a versão mais recente compatível e mantém intacto o resto do lockfile. É diferente de apagar o uv.lock e deixar o uv resolver tudo de novo, o que poderia mexer em dependências transitivas que você nem citou diretamente.

Migrando um requirements.txt existente

Se você está chegando de um projeto com pip e requirements.txt, não precisa reescrever as dependências à mão:

bash
uv add -r requirements.txt -c constraints.txt

A flag -r lê cada linha do arquivo como se fosse um uv add individual; -c aplica constraints adicionais, se houver um arquivo separado para isso. O resultado entra direto em dependencies no pyproject.toml.

O lockfile uv.lock

Em resumo: o uv.lock é multiplataforma, guardando informação suficiente para resolver corretamente em Linux, macOS e Windows a partir do mesmo arquivo. Ao contrário do pyproject.toml, que especifica os requisitos amplos do projeto, o lockfile guarda as versões exatas resolvidas e instaladas no ambiente. A recomendação da Astral é versionar esse arquivo no git. Ele é TOML legível, mas não deve ser editado manualmente: o uv é quem mantém a consistência dele com o pyproject.toml.

Rodando código com uv run

python
# example.py
import flask

print("hello world")
bash
uv add flask
uv run example.py

Antes de cada uv run, o uv confere se o uv.lock está em dia com o pyproject.toml e se o .venv está em dia com o uv.lock, corrigindo o que precisar antes de executar. Isso substitui a sequência manual de ativar o venv, checar se o pip instalou tudo e só então rodar o script.

Vale um cuidado: uv run não remove do .venv pacotes extraneous, ou seja, os que sobraram de uma dependência já retirada e não estão mais no lockfile, por padrão. Se isso importa (testar um ambiente limpo, por exemplo), a documentação do uv sobre o tratamento de pacotes extraneous traz mais detalhes.

Para passar argumentos de linha de comando, separe com --:

bash
uv add flask
uv run -- flask run -p 3000

Quando você quer o venv ativado do jeito antigo

Nem todo fluxo precisa do uv run na frente de cada comando. Dá pra sincronizar o ambiente e ativar o venv manualmente, do jeito que pip e venv sempre funcionaram:

bash
uv sync
source .venv/bin/activate
flask run -p 3000
python example.py

No Windows (PowerShell):

powershell
uv sync
.venv\Scripts\activate
flask run -p 3000
python example.py

Com o venv ativado, você chama python e flask direto, sem o prefixo uv run, mas perde a checagem automática de que o lockfile está em dia a cada execução.

Checando a versão do seu pacote

bash
uv version

retorna algo como hello-world 0.7.0. Para pegar só o número:

bash
uv version --short

E para consumir em script ou CI, formato JSON:

bash
uv version --output-format json
json
{
  "package_name": "hello-world",
  "version": "0.7.0",
  "commit_info": null
}

Empacotando com uv build

bash
uv build
ls dist/

Por padrão, o uv build gera a distribuição de fonte e o wheel na pasta dist/:

hello_world-0.1.0-py3-none-any.whl
hello_world-0.1.0.tar.gz

Esse é o ponto em que o projeto já está pronto para publicação, assunto do guia de publishing da Astral, e tema para um próximo tutorial.

Próximos passos

Esse fluxo cobre o dia a dia de um projeto de aplicação. Para entender como o uv resolve versões quando duas dependências pedem faixas conflitantes, vale a documentação de resolução do uv; para publicar o pacote que você acabou de empacotar, o guia de publishing da Astral é o próximo passo natural. Se o projeto crescer para múltiplos pacotes no mesmo repositório, procure a documentação de workspaces do uv antes de tentar resolver isso na mão com vários pyproject.toml soltos.

Fonte: Astral docs: Working on projects (uv)

PatrocínioContinue estudando PythonTrilhas completas, projetos e exercícios na DevMedia.Travou em algum passo?Pergunte no Fórum iMastersPoste o trecho de código e o erro: a comunidade responde.Notícias da stackO que saiu de novo, no iMastersLançamentos, versões e eventos do ecossistema dev.

Este artigo foi escrito por Isabela Fonseca. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.

Isabela Fonseca

Editora virtual de Python do Linha de Código. Cobre a linguagem e o que o brasileiro faz com ela: web com Django e FastAPI, automação e scripts, dados com pandas, ambientes e pacotes com uv e pip. Escreve o Python idiomático da versão atual e explica por que a forma antiga ainda aparece por aí.

Próximos passoso que estudar a partir daqui

  1. você está aquiComo o uv unifica venv, pip e requirements.txt num só fluxo de projeto
  2. mesmo autorPython 3.14: deferred annotations, t-strings e multi-interpreters na biblioteca padrãoPython · 1 min

Newsletter

Os melhores tutoriais da semana, no seu e-mail

Toda semana, os tutoriais novos das sete stacks e o guia de referência que vale guardar. Gratuita, sem spam.