Installare pacchetti locali in modalità editable con pip e virtualenv

Introduzione

Quando si sviluppa un progetto Python, le dipendenze non arrivano sempre da PyPI. In molti casi si lavora su un pacchetto creato internamente, su una libreria ancora in sviluppo o su un componente condiviso tra più applicazioni. In queste situazioni è utile installare il pacchetto locale in modalità editable, cioè modificabile direttamente senza doverlo reinstallare dopo ogni cambiamento.

La modalità editable viene attivata con l’opzione -e di pip. Invece di copiare stabilmente i file del pacchetto nell’ambiente virtuale, pip crea un collegamento verso la cartella sorgente. Di conseguenza, quando si modifica il codice, l’ambiente utilizza immediatamente la versione aggiornata.

Questo tutorial mostra come organizzare un semplice pacchetto locale, creare un ambiente isolato con virtualenv, installarlo in modalità editable e dichiarare anche le sue dipendenze. È una tecnica molto utile per lo sviluppo di librerie, applicazioni modulari e progetti composti da più pacchetti.

Codice completo

Creiamo questa struttura di progetto:

progetto-demo/
├── ambiente/
├── app/
│   ├── pyproject.toml
│   └── src/
│       └── messaggi/
│           ├── __init__.py
│           └── formato.py
└── usa_messaggi.py

Per prima cosa creiamo l’ambiente virtuale dalla cartella principale:

python -m virtualenv ambiente

Attiviamo l’ambiente su Linux o macOS:

source ambiente/bin/activate

Su Windows PowerShell il comando equivalente è:

.ambienteScriptsActivate.ps1

Il file app/pyproject.toml descrive il pacchetto locale:

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "messaggi"
version = "0.1.0"
description = "Una piccola libreria per formattare messaggi"
dependencies = []

[tool.setuptools.packages.find]
where = ["src"]

[tool.setuptools.package-dir]
"" = "src"

Il modulo app/src/messaggi/formato.py contiene la logica della libreria:

def saluta(nome: str) -> str:
    """Restituisce un saluto formattato."""
    nome_pulito = nome.strip()

    if not nome_pulito:
        raise ValueError("Il nome non può essere vuoto")

    return f"Ciao, {nome_pulito}!"

Il file app/src/messaggi/__init__.py può rendere la funzione disponibile direttamente dal pacchetto:

from .formato import saluta

__all__ = ["saluta"]

Installiamo il pacchetto in modalità editable:

python -m pip install --editable ./app

Infine, il file usa_messaggi.py usa il pacchetto installato:

from messaggi import saluta

print(saluta("Ada"))

Eseguiamo il programma dalla cartella principale:

python usa_messaggi.py

Spiegazione

Il comando python -m pip è preferibile rispetto al semplice comando pip perché garantisce che venga utilizzato pip associato all’interprete Python attivo. Questo evita errori frequenti, soprattutto quando nel sistema sono presenti più versioni di Python.

L’opzione --editable, abbreviata in -e, indica a pip di installare il progetto in modalità sviluppo. La dipendenza viene registrata nell’ambiente virtuale, ma il codice sorgente resta nella directory app. Se modifichiamo la funzione saluta, la modifica sarà disponibile subito:

def saluta(nome: str) -> str:
    return f"Benvenuto, {nome.strip()}!"

Non è necessario ripetere il comando di installazione. È sufficiente eseguire nuovamente il programma. Questa caratteristica rende la modalità editable più efficace di una normale installazione locale, che potrebbe copiare i file in una posizione separata.

Il file pyproject.toml è il punto centrale della configurazione moderna dei pacchetti Python. Nella sezione [project] si possono indicare metadati, versione e dipendenze. Per esempio, se la libreria utilizzasse una versione minima di requests, si potrebbe scrivere:

[project]
name = "messaggi"
version = "0.1.0"
dependencies = [
    "requests>=2.31"
]

Dopo aver modificato le dipendenze del progetto, conviene aggiornare l’installazione editable:

python -m pip install --editable ./app

Per controllare che il pacchetto sia presente nell’ambiente si possono usare:

python -m pip show messaggi
python -m pip list

È inoltre possibile verificare che le dipendenze installate siano coerenti:

python -m pip check

Best practice

• Usa sempre un ambiente virtuale: non installare il pacchetto locale nell’installazione globale di Python.
• Preferisci python -m pip: riduce il rischio di usare un pip appartenente a un altro interprete.
• Configura correttamente il layout src: impedisce di importare accidentalmente il codice solo perché ci si trova nella cartella del progetto.
• Definisci le dipendenze in pyproject.toml: in questo modo il progetto dichiara in modo esplicito ciò che gli serve.
• Non usare editable in produzione: sui server è generalmente meglio installare una versione costruita e identificabile del pacchetto.
• Aggiungi test automatici: una modifica locale può influenzare tutti i progetti che usano il pacchetto.
• Controlla la versione di Python: annota nel progetto eventuali requisiti minimi, ad esempio Python 3.10 o superiore.
• Escludi l’ambiente dal controllo versione: aggiungi ambiente/ al file .gitignore, perché contiene file generati localmente.

Riepilogo

L’installazione editable è una soluzione pratica per sviluppare pacchetti Python locali insieme a un’applicazione. Dopo aver creato un ambiente isolato con virtualenv, il comando python -m pip install --editable ./app collega il progetto all’ambiente senza copiare definitivamente il codice.

Il file pyproject.toml descrive il pacchetto, le sue dipendenze e il sistema di build. Le modifiche al codice diventano immediatamente disponibili, mentre pip continua a trattare il progetto come una normale dipendenza installata. Questa tecnica migliora il ciclo di sviluppo e aiuta a separare correttamente codice applicativo, librerie locali e ambiente Python.

Approfondisci con risorse ufficiali

• Documentazione di pip: consulta la guida ufficiale per installazioni locali, opzioni di installazione e gestione dei pacchetti.
• Packaging Python User Guide: approfondisci la struttura dei progetti, il formato pyproject.toml e la creazione dei pacchetti.
• Documentazione di virtualenv: studia le opzioni per creare ambienti virtuali con interpreti e configurazioni differenti.
• Python Packaging Authority: usa le guide PyPA per seguire le pratiche moderne relative a build, distribuzione e dipendenze Python.