Instalações Editáveis & Pacotes Locais

Instalações editáveis vinculam sua árvore de código-fonte ao ambiente virtual para que as alterações de código entrem em vigor imediatamente. Combinado com o layout src/, isso garante imports confiáveis em desenvolvimento e testes.

Receita

# Projeto com layout src/
uv pip install -e .
# ou: pip install -e .
 
# Dependência de caminho local em pyproject.toml
# dependencies = ["my-utils @ file:///caminho/para/my-utils"]

Quando usar isso:

Desenvolvimento ativo em uma biblioteca ou pacote de aplicação
Monorepos com pacotes locais interdependentes
Testes que precisam importar o pacote instalado, não a raiz do repositório

Exemplo de Trabalho

myapp/
├── pyproject.toml
├── src/
│   └── myapp/
│       ├── __init__.py
│       └── core.py
└── tests/
    └── test_core.py

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.14"
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
 
[tool.hatch.build.targets.wheel]
packages = ["src/myapp"]

uv pip install -e ".[dev]"
uv run pytest

# tests/test_core.py
from myapp.core import greet
 
def test_greet():
    assert greet("Ada") == "Hello, Ada!"

O que isso demonstra:

O layout src/ impede imports acidentais da raiz do repositório
A instalação editável faz com que import myapp resolva para src/myapp/
Os testes exercitam o mesmo caminho de import que a produção usa
Alterações em core.py são visíveis na próxima execução do teste sem reinstalar

Mergulho Profundo

Como Funciona

pip install -e . grava um arquivo .pth no venv apontando para src/
O backend de build descobre pacotes através da configuração pyproject.toml
Dependências de caminho (my-utils @ file://...) criam links simbólicos para pacotes locais na árvore de dependências
Workspaces do uv coordenam múltiplos pacotes editáveis em um monorepo

Layout `src` vs Layout Plano

Layout	Risco de importação	Recomendado
`src/myapp/`	Baixo (precisa instalar)	Sim
`myapp/` na raiz	Testes importam código não instalado	Não

Notas Python

# workspace uv para monorepos
[tool.uv.workspace]
members = ["packages/*"]
 
# packages/myapp/pyproject.toml
[project]
name = "myapp"
dependencies = ["my-utils"]
 
# packages/my-utils/pyproject.toml
[project]
name = "my-utils"

uv sync   # instala todos os membros do workspace editáveis

Armadilhas

Testes passam sem instalação (layout plano) - CI falha porque o pacote nunca foi construído. Correção: adote o layout src/; sempre pip install -e . antes de testar.
Instalação editável após renomear pacote - .pth obsoleto aponta para o caminho antigo. Correção: reinstale: uv pip install -e . --force-reinstall.
Dependências de caminho absoluto em pyproject.toml - quebra em outras máquinas. Correção: use workspaces uv ou dependências de caminho relativo para monorepos.
__init__.py ausente - pacotes de namespace podem confundir a descoberta editável. Correção: inclua __init__.py a menos que você use intencionalmente pacotes de namespace.
Publicar um pacote apenas editável - pip install do PyPI precisa de um wheel real. Correção: editável é para desenvolvimento; uv build para distribuição.

Alternativas

Alternativa	Use Quando	Não Use Quando
`PYTHONPATH=src`	Hack rápido, sem instalação	Produção ou CI (frágil)
Instalação regular (`pip install .`)	Verificando o pacote construído	Desenvolvimento ativo
Workspace uv	Monorepo com 2+ pacotes	Aplicações de pacote único

FAQs

O que -e significa?

Editável. O pacote instalado se vincula de volta ao seu diretório de código-fonte.

Preciso reinstalar após adicionar um novo módulo?

Não para novos arquivos .py dentro de um pacote existente. Sim se você adicionar um novo pacote de nível superior ou alterar pontos de entrada.

Por que usar o layout src/?

Força os testes a importar o pacote instalado, capturando bugs de empacotamento antes do lançamento.

Como funcionam as dependências de caminho de monorepo?

Workspaces uv ou dependencies = ["sibling @ file:///${PROJECT_ROOT}/packages/sibling"] com caminhos relativos.

Posso instalar uma dependência editavelmente?

Sim: uv pip install -e ../my-utils ou declare-a como membro do workspace.

Editável funciona com Poetry?

Sim: poetry install instala o projeto atual editavelmente por padrão.

E arquivos de dados em modo editável?

Dados do pacote devem ser declarados em pyproject.toml ([tool.hatch.build.targets.wheel.force-include]). Edições de código-fonte em arquivos de dados são capturadas imediatamente.

Como verifico o caminho de instalação?

python -c "import myapp; print(myapp.__file__)" deve apontar para src/myapp/.

Editável no Docker?

Monte o código-fonte como um volume e pip install -e . no contêiner para desenvolvimento com recarga ao vivo.

Posso misturar dependências editáveis e regulares?

Sim. Apenas seu projeto (e irmãos do workspace) são editáveis; dependências do PyPI instalam normalmente.

Relacionado

pyproject.toml Explicado - configuração do pacote
uv - A Toolchain Rápida - suporte a workspace
Noções Básicas de Empacotamento - wheels e sdists
Melhores Práticas de Ambientes - convenções de layout

Versões de 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+.

Instalações Editáveis & Pacotes Locais

Receita

# Projeto com layout src/
uv pip install -e .
# ou: pip install -e .
 
# Dependência de caminho local em pyproject.toml
# dependencies = ["my-utils @ file:///caminho/para/my-utils"]

Quando usar isso:

Desenvolvimento ativo em uma biblioteca ou pacote de aplicação
Monorepos com pacotes locais interdependentes
Testes que precisam importar o pacote instalado, não a raiz do repositório

Exemplo de Trabalho

myapp/
├── pyproject.toml
├── src/
│   └── myapp/
│       ├── __init__.py
│       └── core.py
└── tests/
    └── test_core.py

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.14"
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
 
[tool.hatch.build.targets.wheel]
packages = ["src/myapp"]

uv pip install -e ".[dev]"
uv run pytest

# tests/test_core.py
from myapp.core import greet
 
def test_greet():
    assert greet("Ada") == "Hello, Ada!"

O que isso demonstra:

O layout src/ impede imports acidentais da raiz do repositório
A instalação editável faz com que import myapp resolva para src/myapp/
Os testes exercitam o mesmo caminho de import que a produção usa
Alterações em core.py são visíveis na próxima execução do teste sem reinstalar

Mergulho Profundo

Como Funciona

pip install -e . grava um arquivo .pth no venv apontando para src/
O backend de build descobre pacotes através da configuração pyproject.toml
Dependências de caminho (my-utils @ file://...) criam links simbólicos para pacotes locais na árvore de dependências
Workspaces do uv coordenam múltiplos pacotes editáveis em um monorepo

Layout `src` vs Layout Plano

Layout	Risco de importação	Recomendado
`src/myapp/`	Baixo (precisa instalar)	Sim
`myapp/` na raiz	Testes importam código não instalado	Não

Notas Python

# workspace uv para monorepos
[tool.uv.workspace]
members = ["packages/*"]
 
# packages/myapp/pyproject.toml
[project]
name = "myapp"
dependencies = ["my-utils"]
 
# packages/my-utils/pyproject.toml
[project]
name = "my-utils"

uv sync   # instala todos os membros do workspace editáveis

Armadilhas

Testes passam sem instalação (layout plano) - CI falha porque o pacote nunca foi construído. Correção: adote o layout src/; sempre pip install -e . antes de testar.
Instalação editável após renomear pacote - .pth obsoleto aponta para o caminho antigo. Correção: reinstale: uv pip install -e . --force-reinstall.
Dependências de caminho absoluto em pyproject.toml - quebra em outras máquinas. Correção: use workspaces uv ou dependências de caminho relativo para monorepos.
__init__.py ausente - pacotes de namespace podem confundir a descoberta editável. Correção: inclua __init__.py a menos que você use intencionalmente pacotes de namespace.
Publicar um pacote apenas editável - pip install do PyPI precisa de um wheel real. Correção: editável é para desenvolvimento; uv build para distribuição.

Alternativas

Alternativa	Use Quando	Não Use Quando
`PYTHONPATH=src`	Hack rápido, sem instalação	Produção ou CI (frágil)
Instalação regular (`pip install .`)	Verificando o pacote construído	Desenvolvimento ativo
Workspace uv	Monorepo com 2+ pacotes	Aplicações de pacote único

FAQs

O que -e significa?

Editável. O pacote instalado se vincula de volta ao seu diretório de código-fonte.

Preciso reinstalar após adicionar um novo módulo?

Não para novos arquivos .py dentro de um pacote existente. Sim se você adicionar um novo pacote de nível superior ou alterar pontos de entrada.

Por que usar o layout src/?

Força os testes a importar o pacote instalado, capturando bugs de empacotamento antes do lançamento.

Como funcionam as dependências de caminho de monorepo?

Workspaces uv ou dependencies = ["sibling @ file:///${PROJECT_ROOT}/packages/sibling"] com caminhos relativos.

Posso instalar uma dependência editavelmente?

Sim: uv pip install -e ../my-utils ou declare-a como membro do workspace.

Editável funciona com Poetry?

Sim: poetry install instala o projeto atual editavelmente por padrão.

E arquivos de dados em modo editável?

Dados do pacote devem ser declarados em pyproject.toml ([tool.hatch.build.targets.wheel.force-include]). Edições de código-fonte em arquivos de dados são capturadas imediatamente.

Como verifico o caminho de instalação?

python -c "import myapp; print(myapp.__file__)" deve apontar para src/myapp/.

Editável no Docker?

Monte o código-fonte como um volume e pip install -e . no contêiner para desenvolvimento com recarga ao vivo.

Posso misturar dependências editáveis e regulares?

Sim. Apenas seu projeto (e irmãos do workspace) são editáveis; dependências do PyPI instalam normalmente.

Relacionado

pyproject.toml Explicado - configuração do pacote
uv - A Toolchain Rápida - suporte a workspace
Noções Básicas de Empacotamento - wheels e sdists
Melhores Práticas de Ambientes - convenções de layout

Versões de 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+.

Instalações Editáveis & Pacotes Locais

Buscar na documentação

Instalações Editáveis & Pacotes Locais