install_requires e requirements.txt: quale file legge pip
install_requires è il minimo astratto di un progetto Python. Un requirements file è una lista di argomenti di pip, e pip la legge solo se gliela si passa con -r.
In questa guida (3)
Chi pacchettizza codice Python ha davanti due elenchi che pip tratta in modo diverso. install_requires dice il minimo che serve a far girare un progetto. Un file di requirements è una lista di argomenti di pip install, e pip la legge solo se gliela si passa. Ho letto due pagine della Python Packaging User Guide, entrambe aggiornate al 31 ottobre 2026 e rilette il 2 novembre. Non ho lanciato pip.
Il minimo del progetto
La pagina sul confronto chiama install_requires una parola chiave di Setuptools in setup.py. Va usata per dire che cosa un progetto ha bisogno, come minimo, per girare in modo corretto. Quando pip installa il progetto, è questa la specifica con cui installa le dipendenze.
Gli esempi della pagina sono liste corte: A e B, poi A>=1 e B>=2, poi, se la versione 2 di A rompe il progetto, A>=1,<2 insieme a B>=2. La pagina non considera buona pratica fissare versioni esatte in install_requires, né elencare le dipendenze delle dipendenze. Lo giudica troppo restrittivo, e toglie a chi installa il beneficio degli aggiornamenti.
Quei requisiti sono astratti: nomi e limiti di versione, senza dire da quale indice o da quale cartella arriveranno i pacchetti. Il dove si decide al momento dell'installazione, con le opzioni di pip.
Il file che pip non legge da solo
Un requirements file, sulla stessa pagina, è una lista di argomenti di pip install messa in un file. Spesso descrive un ambiente intero, non un solo progetto, e spesso inchioda le versioni per ripetere l'installazione. Può contenere opzioni come --index-url o --find-links, e così lega i nomi a un indice o a una directory.
pip non analizza quel file da solo durante l'installazione di un progetto. Lo usa quando qualcuno lancia python -m pip install -r.
Dove vanno le dipendenze di un progetto nuovo
La guida al pyproject.toml, aggiornata lo stesso giorno, per i progetti nuovi indica la tabella [project]. Le dipendenze si elencano lì:
[project]
dependencies = [
"httpx",
"gidgethub[httpx]>4.0.0",
]L'esempio è quello della guida. Le dipendenze opzionali, quelle di una sola funzione del pacchetto, stanno in [project.optional-dependencies]. La guida aggiunge che setup.py e setup.cfg restano formati validi, e che setup.py ha ancora un senso se serve una configurazione di programma, per esempio per compilare estensioni in C. Poetry, prima della 2.0 uscita il 5 gennaio 2025, usava [tool.poetry] al posto di [project]. Dalla 2.0, scrive la guida, accetta entrambi.
Fonti: install_requires e requirements file, scrivere il pyproject.toml.
Foto di copertina: Frederick Noronha, Computer keyboard in black and white 33, Wikimedia Commons, CC BY-SA 4.0. La descrizione del file è una tastiera.


