Noções Básicas de Ambientes e Empacotamento

10 exemplos para você começar com Ambientes e Empacotamento - 7 básicos e 3 intermediários.

Pré-requisitos

• Python 3.14.0 instalado (python3 --version)
• uv 0.6+ recomendado para instalações rápidas: curl -LsSf https://astral.sh/uv/install.sh | sh
• Um diretório de projeto com um pyproject.toml (crie um com uv init se necessário)

Exemplos Básicos

1. Criar um Ambiente Virtual

Um ambiente virtual isola as dependências do projeto do Python do sistema.

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
which python                # aponta para dentro do .venv

• venv vem com o Python 3.14 - nenhuma instalação extra é necessária
• A ativação adiciona .venv/bin ao PATH para que pip e python sejam locais do projeto
• Desative com deactivate ao trocar de projetos
• Nunca comite .venv/ - adicione-o ao .gitignore

Relacionado: uv - A Ferramenta Rápida - alternativa mais rápida para venv + pip manual

2. Instalar um Pacote com pip

Instale dependências no ambiente ativo.

pip install httpx
pip freeze > requirements.txt

• pip resolve e instala do PyPI apenas no venv ativo
• pip freeze captura as versões exatas para reprodutibilidade
• Prefira pyproject.toml + lockfiles para novos projetos (veja pyproject.toml Explicado)
• Use pip install -r requirements.txt para restaurar um conjunto congelado

3. Inicializar um Projeto com uv

uv substitui venv + pip + pip-tools em uma ferramenta rápida.

uv init myapp
cd myapp
uv add httpx pydantic
uv run python -c "import httpx; print(httpx.__version__)"

• uv init cria pyproject.toml e um .venv automaticamente
• uv add grava as dependências em pyproject.toml e atualiza o lockfile
• uv run executa dentro do ambiente do projeto sem ativação manual
• uv é a toolchain padrão recomendada para projetos Python 3.14

Relacionado: uv - A Ferramenta Rápida - fluxo completo do uv

4. Declarar Dependências em pyproject.toml

Projetos modernos declaram metadados e dependências em um único arquivo.

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
    "httpx>=0.28",
    "pydantic>=2",
]

• [project] é o bloco de metadados PEP 621 que todas as ferramentas de build leem
• requires-python impede instalações em interpretadores não suportados
• Intervalos de versão (>=) equilibram flexibilidade com reprodutibilidade via lockfiles
• Configurações específicas da ferramenta (ruff, pytest) ficam no mesmo arquivo sob [tool.*]

Relacionado: pyproject.toml Explicado - todas as seções decodificadas

5. Fixar com um Lockfile

Lockfiles registram versões resolvidas exatas para instalações reproduzíveis.

uv lock
uv sync

• uv lock resolve todas as dependências e grava uv.lock
• uv sync instala exatamente o que o lockfile especifica
• Comite o lockfile - colegas de equipe e CI obtêm ambientes idênticos
• Execute uv lock novamente quando alterar as dependências de pyproject.toml

Relacionado: Resolução de Dependências e Lockfiles - estratégias de fixação

6. Instalar Múltiplas Versões do Python

Teste com várias versões do Python em uma única máquina.

uv python install 3.13 3.14
uv venv --python 3.14
uv run --python 3.13 pytest

• uv python install baixa interpretadores sem pyenv
• Fixe o venv do projeto em uma versão específica com --python
• Execute comandos contra qualquer versão instalada com uv run --python
• Combine requires-python em pyproject.toml com sua versão mínima suportada

Relacionado: Gerenciando Versões do Python - pyenv e matrizes de CI

7. Instalação Editável para Desenvolvimento Local

Edite o código-fonte e veja as alterações sem reinstalar.

uv pip install -e .
# ou: pip install -e .

• -e (editável) vincula o pacote ao venv através de um arquivo .pth
• Alterações em src/myapp/ entram em vigor na próxima importação
• Use o layout src/ para que os testes importem o pacote instalado, não a raiz do repositório
• Necessário para monorepos com pacotes locais interdependentes

Relacionado: Instalações Editáveis e Pacotes Locais - layout src e monorepos

Exemplos Intermediários

8. Grupos de Dependência para Dev vs. Produção

Separe dependências de tempo de execução e de desenvolvimento.

[project]
dependencies = ["fastapi>=0.115"]
 
[dependency-groups]
dev = ["pytest>=8", "ruff>=0.9", "mypy>=1.14"]

uv sync --group dev
uv sync --no-dev   # instalação de produção apenas

• [dependency-groups] (PEP 735) substitui requirements-dev.txt ad-hoc
• uv sync --group dev instala ferramentas de runtime + dev
• CI pode instalar apenas o que cada job precisa
• Nunca envie dependências de desenvolvimento para contêineres de produção

9. Configurar um Índice de Pacotes Privado

Baixe pacotes de um espelho interno ou PyPI privado.

export UV_INDEX_URL=https://pypi.internal.corp/simple/
uv sync

# Alternativa pyproject.toml
[[tool.uv.index]]
url = "https://pypi.internal.corp/simple/"
default = true

• Índices privados hospedam pacotes internos e espelham o PyPI público
• Credenciais vão em ~/.netrc, variáveis de ambiente ou segredos de CI - nunca em pyproject.toml
• --index-url substitui o padrão para um único comando
• Use o PyPI público como fallback para pacotes não espelhados internamente

Relacionado: Índices e Espelhos Privados - autenticação e configuração de CI

10. Reproduzir um Ambiente do Zero

Clone, instale e execute em três comandos.

git clone https://github.com/org/myapp.git && cd myapp
uv sync --frozen
uv run pytest

• --frozen falha se o lockfile estiver desatualizado com pyproject.toml
• Novos contribuidores obtêm um ambiente de trabalho em segundos
• CI deve usar o mesmo comando uv sync --frozen
• Documente os três comandos no seu README

Relacionado: Melhores Práticas de Ambientes - convenções de equipe

Versões da Stack: 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+.