UV - Python package and project manager

uv.md

O uv é um gerenciador de pacotes e ambientes para Python de próxima geração, projetado para ser extremamente rápido e leve

Ele substitui ferramentas como pip, pip-tools e virtualenv, oferecendo em um só comando:

Instalação de dependências (com cache e paralelismo, muito mais rápido que o pip).

• Criação e gerenciamento de ambientes virtuais.

• Geração de arquivo de lock (uv.lock) para reprodutibilidade.

• Integração direta com pyproject.toml.

Em resumo: o uv é um pip + virtualenv + pip-tools turbinado em uma única ferramenta, com foco em velocidade, simplicidade e reprodutibilidade.

Para Instalar:

https://docs.astral.sh/uv/getting-started/installation/

Verificar versão:

uv --version

Iniciar UV no projeto:

# se esitver na pasta do projeto
uv init .

# se não exsitver na pasta do projeto
uv init diretorio/meu-app

add uma lib:

uv add fastapi

Use o uv add --dev para instalar dependências só em um ambiente, por exemplo instalar só pra DEV e não para PRD:

uv add --dev pytest

Rodar o arquivo pelo uv (nesse momento é criado o ambiente virtual):

uv run arquivo.py

Jupyter notebook com UV

uv add jupyter

Depois da instalação, você pode executar:

uv run jupyter notebook
ou
uv run jupyter lab

⚡ O uv run garante que o comando rode dentro do ambiente do projeto, sem precisar ativar manualmente o .venv.

Ver os pacotes já instalados:

uv tree

---

PYENV + UV

Caso precise trabalhar com múltiplas versões do Python, a utilização do Pyenv com o UV é bem simples.

Após baixar e instalar o Pyenv na sua máquina, siga os passos abaixo:

Para verificar as versões do python baixados na sua máquina:

pyenv versions

O comando pyenv install instala uma versão específica do python. Para instalar a 3.11.5 use:

pyenv install 3.11.5

Para definir uma versão global na sua máquina use o pyenv global:

pyenv global 3.12.1

Para definir uma versão local para um projeto use o pyenv local dentro da pasta do seu projeto:

pyenv local 3.12.1

Após definir a versão local para seu proejto, é preciso recriar o ambiente virtual para usar a versão Python do Pyenv.

Para isso, na raiz do seu projeto, execute:

rm -rf .venv

uv venv

uv sync

Por fim, na raiz do projeto, execute o comando abaixo para verificar a versão do Python para aquele projeto:

uv run python --version

---

Como recriar o ambiente em outra máquina:

No novo computador, basta copiar o projeto com esses arquivos e rodar:

uv sync

O uv vai ler o pyproject.toml e o uv.lock para instalar exatamente as dependências do ambiente original.

Arquivos que você deve preservar

1 - pyproject.toml

• Define o projeto, dependências principais, versões mínimas e metadados.

• É o arquivo central: sem ele, não há como recriar o ambiente corretamente.

2 - uv.lock

• Arquivo de lock do uv, equivalente a um poetry.lock ou requirements.txt congelado.

• Garante que você terá as mesmas versões exatas das bibliotecas, preservando a reprodutibilidade.

3 - (Opcional) .python-version ou configuração equivalente

• Caso esteja usando pyenv ou alguma forma de fixar a versão do Python.

• Isso assegura que no outro computador você usará o mesmo interpretador.

4 - (Opcional) Arquivos de configuração adicionais

• .env (se houver variáveis de ambiente do projeto).

• Scripts auxiliares (ex.: Makefile, tasks.py).

remover uma lib:

uv remove redis

O comando uv tool install ... é usado para instalar ferramentas de linha de comando escritas em Python de forma global.

O comando uvx é usado para executar ferramentas de linha de comando escritas em Python de forma isolada, sem poluir o seu ambiente global

Instala o Black, formatador automático de código Python:

uv tool install black

Executar:

uvx black arquivo.py

Instala o HTTPie, cliente de linha de comando para fazer requisições HTTP de forma amigável.

Você poderá rodar http GET https://api.exemplo.com direto no terminal.

uv tool install httpie