Para instalar um projeto Python local em modo editável no macOS, abra o Terminal, navegue até o diretório do projeto, crie e ative um ambiente virtual, e depois execute python -m pip install -e .. Isso vincula as importações do Python à sua árvore de código-fonte de trabalho, para que as alterações nos arquivos Python fiquem disponíveis em novas sessões do interpretador sem a necessidade de reinstalação. O projeto ainda precisa de metadados de empacotamento, e o comportamento exato do modo editável depende do seu backend de compilação (build backend).

O que uma instalação editável faz

Uma instalação comum coloca o projeto no ambiente Python selecionado como um pacote instalado. Uma instalação editável, por outro lado, disponibiliza o código-fonte no diretório de desenvolvimento para o caminho de importação do Python. Ela é útil quando você está modificando esse projeto localmente; isso não significa que todos os arquivos do projeto ou recursos que não sejam do Python sejam tratados automaticamente da mesma forma. Guia do pip para instalação de projetos locais

O modo editável também não faz com que as alterações de dependências desapareçam. O pip instala as dependências declaradas pelo projeto da maneira usual, a menos que você passe --no-deps. As alterações no código-fonte Python geralmente ficam visíveis na próxima execução, mas uma alteração nos metadados do projeto, scripts de linha de comando gerados ou código compilado pode exigir reinstalação ou recompilação. Guia do Usuário de Empacotamento Python: Empacotamento e distribuição de projetos

Preparar um ambiente virtual no macOS

No Terminal, mude para a pasta raiz do projeto, o diretório que contém o pyproject.toml ou um arquivo legado suportado setup.py. O comando cd abaixo presume que a pasta está no seu diretório pessoal (home); coloque o caminho entre aspas se ele contiver espaços.

cd "$HOME/path/to/my-project"
python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip --version

O ambiente virtual mantém os pacotes instalados deste projeto separados de outros ambientes Python. Após a ativação, python deve se referir ao interpretador do ambiente, de modo que o uso de python -m pip vincula o pip a esse interpretador. A documentação do Python descreve o venv como uma ferramenta para criar ambientes isolados e documenta o comando de ativação para shells POSIX, incluindo o shell usado por padrão nas configurações atuais do Terminal do macOS. Documentação do Python: venv

Se o python3 não for encontrado, instale ou localize um interpretador Python 3 primeiro; o macOS não garante que um Python pronto para desenvolvimento esteja disponível sob esse comando. Se o projeto especificar uma versão suportada do Python, use essa versão para criar o .venv. Evite instalar pacotes em um Python gerenciado pelo sistema quando um ambiente de projeto for suficiente.

Instalar o projeto em modo editável

Com o ambiente ativo e o Terminal ainda na raiz do projeto, execute:

python -m pip install -e .

Aqui, -e significa editável e . significa o diretório atual. O pip espera que o diretório de um projeto local contenha pyproject.toml ou setup.py. Projetos modernos normalmente declaram um backend de compilação no pyproject.toml; o pip solicita que esse backend realize a instalação editável. O backend deve suportar a interface de instalação editável para que isso funcione como esperado. Referência de instalação do pip, Interface do sistema de compilação do pip

Para instalar a partir de um diretório diferente, forneça o seu caminho em vez de ., por exemplo, python -m pip install -e "$HOME/path/to/my-project". Colocar o caminho entre aspas protege contra espaços e metacaracteres do shell. A instalação se aplica ao ambiente Python associado ao comando python que você utilizou.

Confirmar o ambiente e diagnosticar erros

Verifique a visualização de projetos instalados do pip para confirmar que ele lista o pacote e a localização do seu projeto editável:

python -m pip list

Em seguida, inicie o Python a partir do ambiente ativado e tente importar o pacote usando seu nome de importação documentado. O nome de importação pode ser diferente do nome de distribuição do projeto, portanto, consulte o README do projeto ou o diretório do pacote em vez de tentar adivinhar. Se a importação funcionar apenas a partir de uma pasta, verifique se a instalação aponta para a raiz pretendida do projeto e se o pacote está configurado para descoberta por seu backend.

Se o pip informar que o diretório não é instalável, verifique se você está na raiz correta e se ela contém pyproject.toml ou setup.py. Se o backend de compilação rejeitar o modo editável, atualize ou configure o backend do projeto de acordo com a documentação dele; nem todo backend mais antigo ou customizado suporta instalações editáveis. Para um projeto moderno com pyproject.toml, o pip utiliza o hook editável da PEP 660 do backend. Interface do sistema de compilação do pip

Se uma alteração no projeto adicionar dependências, entry points ou alterar metadados, execute novamente python -m pip install -e .. Para extensões compiladas, execute também as etapas de compilação documentadas do projeto. O pip observa que instalações editáveis e comuns podem se comportar de maneira diferente; portanto, uma instalação editável é destinada ao desenvolvimento local e não substitui a verificação do fluxo comum de instalação antes de distribuir um pacote. Guia do pip para instalação de projetos locais

Fontes