Ambientes Virtuais: Guia Rápido
Um ambiente virtual isola as dependências do projeto do Python do sistema e de outros projetos. Crie um antes de instalar bibliotecas - é o primeiro passo em qualquer base de código Python real.
//
Busque em todas as páginas da documentação
Um ambiente virtual isola as dependências do projeto do Python do sistema e de outros projetos. Crie um antes de instalar bibliotecas - é o primeiro passo em qualquer base de código Python real.
# uv (recomendado)
uv venv
source .venv/bin/activate
uv pip install httpx pydantic
# venv da biblioteca padrão
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pipQuando usar isto:
# Criar projeto com uv
mkdir demo-app && cd demo-app
uv init --app
uv add fastapi uvicorn pydantic
# Executar usando o interpretador do projeto (nenhuma ativação manual necessária)
uv run python -c "import fastapi; print(fastapi.__version__)"
# Sincronizar do lockfile em um clone recém-criado
uv sync# verify_env.py - execute com: uv run python verify_env.py
import sys
def main() -> None:
prefix = sys.prefix
in_venv = sys.prefix != sys.base_prefix
print(f"prefix={prefix}")
print(f"isolated={in_venv}")
print(f"version={sys.version.split()[0]}")
if __name__ == "__main__":
main()O que isto demonstra:
uv venv / uv init cria .venv ao lado do projetouv add registra as dependências em pyproject.toml e no lockfileuv run executa comandos dentro do ambiente do projetosys.prefix != sys.base_prefix confirma o isolamento.venv..venv/bin ao início do PATH para que python seja resolvido localmente..venv/lib/python3.14/site-packages.uv sync, uv run.| Ferramenta | Ponto Forte |
|---|---|
uv | Velocidade, lockfile, fluxo de trabalho do projeto |
venv | Biblioteca padrão, sem instalação extra |
pip-tools | Compilação legada de requirements.in |
poetry / pdm | Gerenciamento completo de empacotamento + ambiente |
# Ativação no Windows
.venv\Scripts\activate
# Desativar
deactivate
# Qual python
which python
python -c "import sys; print(sys.executable)"uv run..venv; envie pyproject.toml + lock..venv/bin/python no editor.deactivate e reative.| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
uv projeto | Novas aplicações e bibliotecas | Air-gapped sem binário uv |
docker | Paridade de implantação | Apenas verificação de sintaxe local |
pyenv | Múltiplas versões do Python | Versão única é suficiente |
conda | Pilha científica com binários | Serviço web puro |
Com uv run, não. Para comandos python/pip simples, ative ou use o caminho completo .venv/bin/python.
.venv/, __pycache__/, .pytest_cache/, arquivos .env locais com segredos.
uv para novos projetos - instalações e lockfiles mais rápidos. pip dentro do venv está bom para scripts pequenos.
Exclua .venv, execute uv sync ou uv venv && uv pip install -r requirements.txt.
Sim - .venv é uma convenção. Atualize o caminho do interpretador do IDE de acordo.
Use pyenv, uv python pin 3.14, ou matriz de CI python-version: "3.14".
Instala dependências exatamente de uv.lock - clones e CI reproduzíveis.
PEP 668 protege o Python do sistema. Crie um venv em vez de pip install globalmente.
uv add --dev ruff mypy pytest - mantém as ferramentas fora dos conjuntos de dependências de produção quando configurado.
Sim, por padrão com python -m venv. uv gerencia instalações compatíveis com pip em seus ambientes.
Versões da Pilha: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), 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+.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026