Una de les grans fortaleses de Python és el seu ecosistema: centenars de milers de paquets a punt per instal·lar i fer servir. Però instal·lar paquets "a la babalà" al Python del sistema acaba, tard o d'hora, en conflictes de versions i projectes trencats. En aquesta lliçó aprendràs la solució professional: els entorns virtuals (venv), que aïllen les dependències de cada projecte, i pip, el gestor de paquets de Python, juntament amb el fitxer requirements.txt que permet reproduir un entorn en qualsevol màquina. Configurar això ara, encara que el projecte Papyrus encara no necessiti paquets externs, et donarà l'hàbit correcte des del primer dia.

1. El problema: dependències compartides i conflictes
2. Què és un entorn virtual
3. Crear, activar i desactivar un entorn amb venv
4. pip: instal·lar, llistar i desinstal·lar paquets
5. requirements.txt: entorns reproduïbles
6. Bones pràctiques
7. Alternatives que convé conèixer: conda i poetry

Imagina aquest escenari, molt real:

• Per al projecte Papyrus instal·les un paquet d'informes, versió 2.0.
• Mesos després, per a un altre projecte, necessites el mateix paquet però en versió 3.0 (amb canvis incompatibles).
• Si tots dos projectes comparteixen la mateixa instal·lació de Python, no poden conviure: actualitzar trenca Papyrus; no actualitzar bloqueja el projecte nou.

D'això se'n diu col·loquialment dependency hell (l'infern de les dependències). I té un segon front: si ho instal·les tot al Python del sistema operatiu, pots fins i tot interferir amb eines del mateix sistema que en depenen (alguns Linux directament ho bloquegen amb un error externally-managed-environment).

La solució és conceptualment simple: que cada projecte tingui la seva pròpia còpia aïllada de l'entorn de Python, amb els seus propis paquets i versions.

Un entorn virtual és una carpeta dins del teu projecte que conté:

• Una còpia (o enllaç) de l'intèrpret de Python.
• La seva pròpia carpeta de paquets instal·lats, independent de la del sistema i de la d'altres entorns.
• Scripts d'activació que "redirigeixen" temporalment les comandes python i pip cap a aquell entorn.

Punts clau per entendre'l bé:

• No és una màquina virtual ni res de pesant: és bàsicament una carpeta amb fitxers. Crear-ne un triga segons.
• Mentre un entorn està activat, tot el que instal·lis amb pip cau a dins seu, sense tocar res més.
• Si un entorn s'espatlla, s'esborra la carpeta i se'n crea un altre. Res del sistema no en resulta afectat.

L'eina estàndard per crear-los, venv, ve inclosa amb Python 3: no cal instal·lar res.

Situa't a la carpeta del teu projecte (la carpeta papyrus que vas crear a la lliçó 01-02) i executa:

Desglossament de la comanda:

• python -m venv — executa el mòdul venv que porta Python (-m significa "executa aquest mòdul"; entendràs millor els mòduls al mòdul 3 del curs).
• .venv — el nom de la carpeta on es crearà l'entorn. És el nom convencional més estès (el punt inicial la marca com a carpeta "de treball intern"); també veuràs venv o env.

Al cap d'uns segons tindràs una carpeta .venv dins del projecte. No editis res del seu interior: és territori de les eines.

Activar l'entorn vol dir que, en aquella terminal, python i pip passen a ser els de l'entorn. La comanda depèn del sistema:

A Windows (PowerShell):

A macOS/Linux:

El senyal inequívoc que està actiu és el prefix (.venv) al prompt de la terminal. A partir d'aquell moment:

Nota per a Windows/PowerShell: si en activar apareix un error sobre "execució de scripts deshabilitada", executa un cop Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser i torna-ho a intentar. És una protecció de PowerShell, no una errada de Python.

Nota per a VS Code: en obrir la carpeta del projecte, VS Code sol detectar .venv i preguntar si el vols fer servir com a intèrpret. Digues que sí: així l'editor i el seu terminal integrat faran servir l'entorn automàticament. Si no ho pregunta, prem Ctrl+Shift+P → "Python: Select Interpreter" i tria el de .venv.

Per tornar al Python del sistema en aquella terminal:

El prefix desapareix. L'entorn no s'esborra: només deixa d'estar actiu. La propera vegada que treballis al projecte, el tornes a activar. I si algun dia el vols eliminar de debò, n'hi ha prou d'esborrar la carpeta .venv.

Cicle de treball diari resumit:

pip és el gestor de paquets de Python: descarrega paquets del repositori oficial PyPI (Python Package Index, https://pypi.org, amb centenars de milers de paquets publicats) i els instal·la a l'entorn actiu.

Amb l'entorn .venv activat, les comandes essencials:

(cowsay és un paquet de broma, perfecte per practicar sense risc: fa que una vaca de text "digui" coses.) pip descarrega el paquet i les seves dependències i els instal·la a .venv. Provem-lo:

La sentència import (que estudiaràs a fons al mòdul 3) és la manera de fer servir un paquet instal·lat des del teu codi.

També pots instal·lar una versió concreta, cosa clau per a la reproduïbilitat:

I per al detall d'un paquet concret (versió, resum, dependències):

pip freeze és com pip list, però en format "reinstal·lable" (paquet==versió). És la base del requirements.txt que ve tot seguit.

pip demanarà confirmació (y) i eliminarà el paquet de l'entorn.

Imagina que comparteixes el projecte Papyrus amb una altra persona (o amb el teu ordinador d'aquí a un any). La carpeta .venv no es comparteix (és pesant i específica de cada màquina); el que es comparteix és la llista de dependències: el fitxer requirements.txt.

Amb l'entorn activat i els paquets que facis servir instal·lats:

El símbol > redirigeix la sortida de la comanda al fitxer. El resultat és un fitxer de text a l'arrel del projecte:

Cada línia és un paquet amb la seva versió exacta ("congelada"): la garantia que un altre entorn instal·larà exactament el mateix.

Qui rebi el projecte (o tu mateix en una altra màquina) només necessita:

L'opció -r significa "instal·la tot el que llista aquest fitxer". En tres comandes, un entorn idèntic a l'original.

Mantén requirements.txt actualitzat: cada vegada que instal·lis o desinstal·lis un paquet rellevant per al projecte, torna a executar pip freeze > requirements.txt.

• Un entorn virtual per projecte, sempre. Encara que el projecte sigui petit. Crear un .venv costa 10 segons; desfer un embolic de versions costa tardes senceres.
• No instal·lis paquets al Python del sistema. El Python "global" ha de quedar net, només per crear entorns. Si mai executes pip install i no veus (.venv) al prompt, atura't i activa l'entorn.
• La carpeta de l'entorn es diu .venv i viu a l'arrel del projecte. És la convenció que les eines (VS Code inclòs) detecten automàticament.
• requirements.txt sí que es comparteix; .venv no. Si fas servir git, afegeix .venv/ al fitxer .gitignore del projecte perquè no pugi al repositori.
• No editis res dins de .venv. Es regenera, no es repara: davant de qualsevol problema estrany, esborra la carpeta i recrea-la des de requirements.txt.
• Comprova on estàs instal·lant. pip --version mostra la ruta del pip actiu; si apunta dins del teu projecte, tot correcte.
• Fixa versions en projectes seriosos. pip freeze amb == garanteix que el projecte funcioni igual d'aquí a sis mesos, encara que els paquets hagin publicat versions noves.

venv + pip és l'equipament estàndard i és tot el que necessites en aquest curs. Però al món real sentiràs a parlar d'altres eines, i convé que et sonin:

No les estudiarem en aquest curs: tot el que fem funciona amb venv i pip. Si més endavant un equip o tutorial fa servir conda o poetry, els conceptes que acabes d'aprendre (entorn aïllat, llista de dependències, versions fixades) són exactament els mateixos; només canvien les comandes.

• Instal·lar sense activar l'entorn: l'error més freqüent. El paquet acaba al Python del sistema i "misteriosament" el teu projecte no el troba (o a l'inrevés). Mira sempre el prefix (.venv) abans d'un pip install.
• Obrir una terminal nova i oblidar-se de reactivar: l'activació és per terminal i per sessió. Terminal nova (o reiniciada) = tornar a activar.
• ModuleNotFoundError: No module named '...' en executar el teu script: gairebé sempre significa que el paquet està instal·lat en un altre entorn (o en cap), o que VS Code està fent servir un intèrpret diferent del del teu .venv. Revisa "Python: Select Interpreter".
• Error d'"execució de scripts deshabilitada" a PowerShell: aplica el Set-ExecutionPolicy indicat a l'apartat d'activació; és cosa de PowerShell, no de la teva instal·lació.
• Pujar .venv a git o enviar-la per correu: és pesant i inútil fora de la teva màquina. El que és portable és requirements.txt.
• Canviar el nom o moure la carpeta .venv: els entorns contenen rutes absolutes internes i deixen de funcionar. Si necessites moure'l: esborrar i recrear (amb requirements.txt són dues comandes).
• Consell: crea ja l'entorn de la teva carpeta papyrus i activa'l cada vegada que treballis en el curs, encara que de moment no instal·lis gairebé res. Quan als mòduls 10 i 11 instal·lem Flask, pandas i companyia, l'hàbit ja estarà fet.

A la carpeta papyrus del teu projecte: crea un entorn virtual anomenat .venv, activa'l, comprova amb pip list que està (gairebé) buit i desactiva'l. Anota les comandes exactes que has fet servir al teu sistema operatiu.

Amb l'entorn de Papyrus activat: instal·la el paquet cowsay, comprova amb pip show cowsay quina versió tens, genera el requirements.txt del projecte i mostra'n el contingut per terminal.

Simula el "traspàs" del projecte: desactiva i esborra la carpeta .venv sencera (tranquil: per això hi ha l'exercici), i reconstrueix l'entorn des de zero fent servir únicament requirements.txt. Acaba comprovant amb pip list que cowsay s'ha tornat a instal·lar.

Solució 1

A Windows (PowerShell):

A macOS/Linux:

pip list en un entorn acabat de crear mostra únicament pip (i en algunes versions, setuptools): aquesta és la prova que l'entorn està net i aïllat.

Solució 2

Amb (.venv) visible al prompt:

Per veure el contingut del fitxer: type requirements.txt a Windows o cat requirements.txt a macOS/Linux. Ha de contenir alguna cosa com:

Solució 3

Esborrar la carpeta: Remove-Item -Recurse -Force .venv a PowerShell (o eliminar-la des de l'explorador de fitxers), rm -rf .venv a macOS/Linux. Després, la reconstrucció:

pip list torna a mostrar cowsay en la versió exacta anotada a requirements.txt. Acabes de demostrar la idea central de la lliçó: l'entorn és rebutjable; la llista de dependències és el que és valuós.

Amb aquesta lliçó tanques el mòdul d'introducció equipat com un professional: saps per què s'aïllen les dependències, crees i gestiones entorns amb venv (crear, activar segons el sistema, desactivar), fas anar pip (install, list, show, freeze, uninstall) i fas els teus projectes reproduïbles amb requirements.txt, seguint les bones pràctiques d'un entorn per projecte i un Python de sistema sempre net. També et sonen ja conda i poetry, les alternatives que trobaràs allà fora.

El projecte Papyrus té ara tot el que necessita: un entorn de desenvolupament complet, els seus primers scripts (benvinguda, catàleg, fitxa interactiva de llibres) i un entorn virtual a punt per créixer. Al proper mòdul, Estructures de Control, els teus programes començaran a prendre decisions i a repetir tasques: condicionals per saber si hi ha estoc, bucles per recórrer el catàleg sencer, i molt més. Aquí és on la programació comença a sentir-se com un superpoder.