install_requires non è un requirements.txt

Il 30 ottobre 2026 install_requires non è un file requirements, e nessuno dei due è la tabella [project] di un pyproject.toml nuovo. Ho letto due pagine della Python Packaging User Guide. Non ho lanciato pip.

In breve: la discussione chiama install_requires una parola chiave di setup.py per il minimo che serve a far girare un progetto, astratto, senza indice. Un requirements file, sulla stessa pagina, è una lista di argomenti di pip install, spesso pinnata, spesso con --index-url, e pip la usa solo se gliela passi con -r. La guida al pyproject.toml, aggiornata nello stesso sito, per i progetti nuovi mette le dipendenze in [project]. Non è npm ci: lì si parla di un lockfile JavaScript.

Il minimo, astratto

La pagina install_requires vs requirements files risulta aggiornata il 29 ottobre 2026. Definisce install_requires come parola chiave Setuptools di setup.py: va usata per dire 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 v2 di A rompe il progetto, 'A>=1,<2' insieme a 'B>=2'. La pagina non considera buona pratica pinnare versioni esatte in install_requires, né elencare le sotto-dipendenze. Scrive che è troppo restrittivo e toglie all’utente il beneficio degli aggiornamenti.

L’ultima distinzione di quel paragrafo: sono requisiti «astratti», nomi e limiti di versione, senza dire da quale indice o sorgente arriveranno. Il dove, scrive la pagina, si decide al momento dell’installazione con le opzioni di pip.

Il file che pip non legge da solo

I requirements file, sulla stessa pagina, sono nel modo più semplice una lista di argomenti di pip install messi in un file. install_requires definisce le dipendenze di un singolo progetto. I requirements file spesso definiscono i requisiti di un intero ambiente Python.

Dove il primo è minimo, i secondi spesso contengono un elenco esaustivo di versioni pinnate, per installazioni ripetibili di un ambiente completo. Dove il primo è astratto, i secondi spesso contengono opzioni come --index-url o --find-links, e così diventano «concreti»: legati a un indice o a una directory.

La frase operativa: i metadati di install_requires pip li analizza da solo durante un’installazione. I requirements file no. Servono quando qualcuno li installa di proposito con python -m pip install -r. Non ho eseguito quel comando.

La tabella dei progetti nuovi

La guida Writing your pyproject.toml, letta lo stesso giorno, non ritira la discussione. Dice un’altra cosa, su un altro file. Il pyproject.toml può avere tre tabelle: [build-system], raccomandata, con il backend e le dipendenze per costruire; [project], il formato con cui la maggior parte dei backend scrive i metadati, dipendenze comprese; [tool], che appartiene al singolo strumento.

Per i progetti nuovi la guida dice di usare [project] e di tenere setup.py solo se serve una configurazione programmatica, per esempio estensioni in C. Aggiunge che i formati setup.cfg e setup.py restano validi. Setuptools, scrive, supporta sia [project] sia il formato vecchio. Poetry prima della 2.0, pubblicata il 5 gennaio 2025, non usava [project] ma [tool.poetry]. Con la 2.0 supporta entrambi.

L’esempio delle dipendenze è questo, non un requirements.txt:

[project]
dependencies = [
  "httpx",
  "gidgethub[httpx]>4.0.0",
  "django>2.1; os_name != 'nt'",
  "django>2.0; os_name == 'nt'",
]

Le dipendenze opzionali stanno in [project.optional-dependencies]. Una chiave è un extra: la guida fa l’esempio di pip install your-project-name[gui]. Non è pip install -r.

Errori da evitare

• Incollare un requirements.txt pinnato dentro install_requires e chiamarlo la stessa cosa. La pagina li mette in due sezioni, con due regole.

• Aspettarsi che pip legga un requirements file solo perché sta nella cartella. La pagina dice che serve python -m pip install -r.

• Cercare l’indice dentro install_requires. Lì la pagina lo chiama astratto.

• Trattare [project] dependencies come il file -r. La guida lo mostra come metadato del progetto, per i progetti nuovi.

• Dare setup.py per cancellato. La guida dice che resta valido, e che si tiene se la configurazione deve essere programmatica.

• Confondere questo con npm ci. Un lockfile npm non è una parola chiave Setuptools.

In sintesi

Il 30 ottobre 2026 la discussione PyPA separa install_requires, minimo e astratto, da un requirements file, spesso completo, spesso concreto, usato solo con pip install -r. La guida al pyproject.toml aggiunge una terza scrittura: per i progetti nuovi le dipendenze stanno in [project], e setup.py non è stato dichiarato morto. Poetry prima del 5 gennaio 2025 usava un’altra tabella. Nessuna di queste pagine è un comando che ho eseguito.

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. Non è un requirements.txt e non è un pyproject.toml.