Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

Il banco di lavoro2. Il venv e pipp. 29

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.3

Un 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:

Terminale
python3 --version
Python 3.12.13

Il tuo numero finale può essere diverso, l'importante è 3.12. Poi, dalla cartella del progetto:

Terminale
python3 -m venv .venv
ls -a
.               ..              .venv           tabellone.py

python3 -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:

Terminale
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.13

Le 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:

Terminale
source .venv/bin/activate

source 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 acceso

Quello che è cambiato davvero lo vedi con which, che dice quale programma risponde quando scrivi un nome:

Terminale
which python
which pip
/Users/marta/corso/tabellone/.venv/bin/python
/Users/marta/corso/tabellone/.venv/bin/pip

Ecco 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.

Terminale
echo "$PATH" | tr ':' '\n' | head -1
/Users/marta/corso/tabellone/.venv/bin

La 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:

Terminale
source .venv/bin/activate

Riempirlo

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.

Terminale
python tabellone.py
Traceback (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:

Terminale
pip install tabulate==0.9.0
Collecting 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 pip

L'avviso [notice] sull'aggiornare pip si può ignorare. Ora pip list dice cosa c'è nel venv, e il programma parte:

Terminale
pip list
python tabellone.py
Package  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:25

L'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:

Terminale
pip freeze
tabulate==0.9.0

Per metterlo in un file serve un simbolo nuovo, >: manda quello che un comando stampa dentro un file, invece che sullo schermo.

Terminale
pip freeze > requirements.txt
cat requirements.txt
tabulate==0.9.0

Il 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:

Terminale
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

Terminale
deactivate

Non 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.

Terminale
rm -rf .venv
ls -a
.                       ..                      requirements.txt

rm -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:

Terminale
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Il venv sta nel .gitignore del progetto, perché non deve finire su GitHub. Ogni progetto del corso ce l'ha già:

Terminale
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:

Terminale
/usr/bin/python3 --version
Python 3.9.6

Il 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.

Terminale
python3 --version
No 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.13

Con il file .tool-versions scritto così, la stessa domanda ha una risposta:

Terminale
cat .tool-versions
python3 --version
python 3.12.13
Python 3.12.13

Fuori 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.

Terminale
pip3 install tabulate
error: 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:

Terminale
pwd
which python
python -m pytest --version

which 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 pytest

Su 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==versione mette una libreria nel venv acceso. pip list dice cosa c'è.
  • pip freeze > requirements.txt scrive l'elenco; pip install -r requirements.txt lo rilegge. Il venv non si passa: si passa l'elenco.
  • Un venv rotto o vecchio non si ripara: rm -rf .venv e si rifà.
  • which python dice chi risponde. externally-managed-environment vuol dire: venv spento.