Il venv e pip
Una scatola di librerie per ogni progetto
- 12 minuti di lettura
Il tabellone di Porta Codice ha bisogno di una libreria che disegna tabelle, tabulate, alla versione 0.9.0. Il vecchio programma della biglietteria ne vuole un'altra, più vecchia. Sul tuo computer c'è un Python solo, e un Python solo tiene una versione di ogni libreria.
Il venv (virtual environment, «ambiente virtuale») risolve questo: ogni progetto ha la sua scatola, con il suo Python e le sue librerie. Quello che metti in una scatola non tocca le altre, e non tocca il Python del computer.
Il computer Il progetto "tabellone" Il progetto "biglietteria"
Python del sistema Python del tabellone Python della biglietteria
(lo usa anche il sistema: tabulate 0.9.0 tabulate 0.8.9
non si tocca) python-dotenv 1.2.4 requests 2.32.3Un venv è una cartella come le altre, di solito si chiama .venv e sta nella cartella del progetto. Dentro ci sono una copia del Python e un posto per le librerie. Per buttarlo basta cancellare la cartella: ne fai un altro in dieci secondi.
Il disegno
tabellone/ la cartella del progetto
├── requirements.txt l'elenco delle librerie che servono
├── tabellone.py il tuo codice
└── .venv/ il venv: il punto davanti la nasconde a ls
├── pyvenv.cfg dice con quale Python è nato (version = 3.12.13)
├── bin/
│ ├── python il Python di questo progetto
│ ├── pip l'installatore di librerie, di questo progetto
│ └── activate lo script che accende il venv
└── lib/python3.12/site-packages/
├── pip qui dentro finiscono le librerie
└── tabulate (dopo pip install)Su Windows con WSL è tutto uguale: dentro Ubuntu sei su Linux, e il disegno è lo stesso.
Crearlo
Prima guarda con quale Python lo fai, perché il venv nasce con il Python che lo crea e se lo porta dietro per sempre:
python3 --versionPython 3.12.13Il tuo numero finale può essere diverso, l'importante è 3.12. Poi, dalla cartella del progetto:
python3 -m venv .venv
ls -a. .. .venv tabellone.pypython3 -m venv .venv si legge: «Python, lancia il modulo venv e fai una cartella che si chiama .venv». Non stampa niente se va bene. ls -a serve perché la cartella comincia con un punto, e ls da solo non la mostra: te lo ricordi dal capitolo Il terminale.
Cosa c'è dentro, dopo la creazione:
ls -a .venv
ls .venv/lib/python3.12/site-packages
grep version .venv/pyvenv.cfg. bin lib
.. include pyvenv.cfg
pip pip-25.0.1.dist-info
version = 3.12.13Le tre risposte vengono da tre comandi, una dopo l'altra. Nelle librerie c'è già solo pip: il venv è nuovo e vuoto.
Accenderlo
Un venv creato è spento: il terminale continua a usare il Python di prima. Per accenderlo:
source .venv/bin/activatesource esegue lo script dentro il terminale in cui sei (e non in uno nuovo): per questo cambia il tuo terminale. Lo riconosci dal prompt, che si allunga:
tabellone % venv spento
(.venv) tabellone % venv accesoQuello che è cambiato davvero lo vedi con which, che dice quale programma risponde quando scrivi un nome:
which python
which pip/Users/marta/corso/tabellone/.venv/bin/python
/Users/marta/corso/tabellone/.venv/bin/pipEcco il trucco: source .venv/bin/activate mette la cartella .venv/bin in testa alla lista dei posti dove il terminale cerca i programmi (si chiama PATH). Da quel momento python e pip sono quelli del progetto.
echo "$PATH" | tr ':' '\n' | head -1/Users/marta/corso/tabellone/.venv/binLa prima riga della lista è il venv. Per questo il venv va riacceso a ogni terminale nuovo: l'accensione vale solo per il terminale dove l'hai fatta. Aprire un terminale = ripartire con il venv spento. Da dentro la cartella del progetto:
source .venv/bin/activateRiempirlo
Con il venv acceso, pip installa le librerie dentro il venv. pip scarica da internet, da un archivio che si chiama PyPI: si scrive il nome della libreria, e se vuoi una versione precisa == e il numero.
python tabellone.pyTraceback (most recent call last):
File "/Users/marta/corso/tabellone/tabellone.py", line 3, in <module>
from tabulate import tabulate
ModuleNotFoundError: No module named 'tabulate'Il venv è vuoto: Python non trova la libreria (come si legge un traceback lo spiega Leggere un traceback). La mettiamo:
pip install tabulate==0.9.0Collecting tabulate==0.9.0
Downloading tabulate-0.9.0-py3-none-any.whl.metadata (34 kB)
Downloading tabulate-0.9.0-py3-none-any.whl (35 kB)
Installing collected packages: tabulate
Successfully installed tabulate-0.9.0
[notice] A new release of pip is available: 25.0.1 -> 26.3
[notice] To update, run: pip install --upgrade pipL'avviso [notice] sull'aggiornare pip si può ignorare. Ora pip list dice cosa c'è nel venv, e il programma parte:
pip list
python tabellone.pyPackage Version
-------- -------
pip 25.0.1
tabulate 0.9.0
Treno Destinazione Ora
------- -------------- -----
M12 Piazza Query 06:10
M14 Vecchia Fiera 06:18
T28 Ponte Ciclo 06:25L'elenco: requirements.txt e pip freeze
Il venv non si copia e non va su GitHub: pesa, ed è legato al tuo computer. Quello che si passa ai colleghi è l'elenco di cosa c'è dentro: il file requirements.txt, una libreria per riga, con la versione.
pip freeze stampa esattamente quell'elenco, nel formato giusto:
pip freezetabulate==0.9.0Per metterlo in un file serve un simbolo nuovo, >: manda quello che un comando stampa dentro un file, invece che sullo schermo.
pip freeze > requirements.txt
cat requirements.txttabulate==0.9.0Il primo comando non stampa niente (è tutto finito nel file), il secondo lo legge. Se il file c'era già, > lo cancella e lo riscrive: come rm, niente cestino.
Chi riceve il progetto fa il contrario: crea il suo venv, lo accende, e dice a pip di installare tutto l'elenco:
pip install -r requirements.txt-r vuol dire read, «leggi da questo file». Senza -r, pip cercherebbe una libreria che si chiama requirements.txt.
Spegnerlo, buttarlo, rifarlo
deactivateNon stampa niente: il prompt perde il (.venv), e python e pip tornano quelli di prima. Il venv è sempre lì, solo spento.
Un venv non si ripara: si butta e si rifà. È una cartella di librerie, e tutto quello che c'è dentro lo ricrea il requirements.txt.
rm -rf .venv
ls -a. .. requirements.txtrm -rf cancella la cartella con tutto quello che c'è dentro e senza chiedere (come rm -r, dal capitolo sul terminale: niente cestino, e prima controlli con pwd di essere nella cartella giusta). Poi si rifà tutto:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtIl venv sta nel .gitignore del progetto, perché non deve finire su GitHub. Ogni progetto del corso ce l'ha già:
cat .gitignore.venv/Come si usa .gitignore lo spiega Il giro di ogni giorno.
Quale Python: la versione
Il venv ha la stessa versione di Python che lo ha creato. Se python3 sul tuo computer è vecchio, il venv è vecchio, e le cose nuove del linguaggio non funzionano. Sul Mac, python3 può essere quello fornito da Apple, che è fermo al 3.9:
/usr/bin/python3 --versionPython 3.9.6Il corso usa Python 3.12. Se hai più versioni, scegli quella giusta scrivendo il nome intero: python3.12 -m venv .venv. E se un venv è nato con quella sbagliata, lo butti e lo rifai.
Come lo fanno in azienda: un programma, asdf, gestisce le versioni di Python, e un file .tool-versions nella cartella del progetto dice quale usare. Non c'è niente da installare per il corso, ma è utile saperlo: se nella cartella manca la riga, i comandi lo dicono.
python3 --versionNo version is set for command python3
Consider adding one of the following versions in your config file at /Users/marta/corso/tabellone/.tool-versions
python 3.12.13Con il file .tool-versions scritto così, la stessa domanda ha una risposta:
cat .tool-versions
python3 --versionpython 3.12.13
Python 3.12.13Fuori dal venv: externally-managed-environment
Se lanci pip install a venv spento, sul Python del computer, i sistemi nuovi si rifiutano: il Python di Homebrew (Mac) e quello di Ubuntu sono «gestiti dall'esterno», e non vogliono librerie tue.
pip3 install tabulateerror: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try brew install
xyz, where xyz is the package you are trying to
install.
If you wish to install a Python library that isn't in Homebrew,
use a virtual environment:
python3 -m venv path/to/venv
source path/to/venv/bin/activate
python3 -m pip install xyz
If you wish to install a Python application that isn't in Homebrew,
it may be easiest to use 'pipx install xyz', which will manage a
virtual environment for you. You can install pipx with
brew install pipx
You may restore the old behavior of pip by passing
the '--break-system-packages' flag to pip, or by adding
'break-system-packages = true' to your pip.conf file. The latter
will permanently disable this error.
If you disable this error, we STRONGLY recommend that you additionally
pass the '--user' flag to pip, or set 'user = true' in your pip.conf
file. Failure to do this can result in a broken Homebrew installation.
Read more about this behavior here: <https://peps.python.org/pep-0668/>
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.Il messaggio è lungo, ma l'unica riga che conta è la prima. Su Ubuntu (WSL) i consigli in mezzo parlano di apt, ma la prima riga è uguale.
La cura è una sola: accendi il venv, e rifai pip install. Non usare mai --break-system-packages: il messaggio lo propone, tu no.
Quale Python sta rispondendo?
Quando qualcosa non va («pytest: command not found», «No module named …»), la prima domanda è sempre questa. Tre comandi:
pwd
which python
python -m pytest --versionwhich python dice quale Python risponde: se finisce con /.venv/bin/python ed è la cartella del tuo progetto, il venv giusto è acceso. python -m pytest usa sicuramente il pytest di quel Python, mentre pytest da solo può essere un altro. Se nel venv pytest non c'è, lo dice:
/Users/marta/corso/tabellone/.venv/bin/python: No module named pytestSu un Mac senza asdf, a venv spento il comando python può non esistere proprio: esiste solo python3. Per questo nei comandi del corso, dentro il venv, scriviamo python.
I casi lunghi (VS Code che sceglie il Python sbagliato, il pannello Testing vuoto) hanno la loro pagina: pytest non parte, o non trova niente. L'interprete di VS Code è nel capitolo VS Code per Python; pytest lo trovi nel capitolo Lanciare i test.
Ricorda
- Un venv è una cartella (
.venv) con dentro un Python e le sue librerie: una per progetto. - Si crea una volta:
python3 -m venv .venv. Si accende a ogni terminale:source .venv/bin/activate. Il prompt comincia con(.venv). pip install nome==versionemette una libreria nel venv acceso.pip listdice cosa c'è.pip freeze > requirements.txtscrive l'elenco;pip install -r requirements.txtlo rilegge. Il venv non si passa: si passa l'elenco.- Un venv rotto o vecchio non si ripara:
rm -rf .venve si rifà. which pythondice chi risponde.externally-managed-environmentvuol dire: venv spento.