Una de las grandes fortalezas de Python es su ecosistema: cientos de miles de paquetes listos para instalar y usar. Pero instalar paquetes "a lo loco" en el Python del sistema acaba, tarde o temprano, en conflictos de versiones y proyectos rotos. En esta lección aprenderás la solución profesional: los entornos virtuales (venv), que aíslan las dependencias de cada proyecto, y pip, el gestor de paquetes de Python, junto con el fichero requirements.txt que permite reproducir un entorno en cualquier máquina. Configurar esto ahora, aunque el proyecto Papyrus todavía no necesite paquetes externos, te dará el hábito correcto desde el primer día.

1. El problema: dependencias compartidas y conflictos
2. Qué es un entorno virtual
3. Crear, activar y desactivar un entorno con venv
4. pip: instalar, listar y desinstalar paquetes
5. requirements.txt: entornos reproducibles
6. Buenas prácticas
7. Alternativas que conviene conocer: conda y poetry

Imagina este escenario, muy real:

• Para el proyecto Papyrus instalas un paquete de informes, versión 2.0.
• Meses después, para otro proyecto, necesitas el mismo paquete pero en versión 3.0 (con cambios incompatibles).
• Si ambos proyectos comparten la misma instalación de Python, no pueden convivir: actualizar rompe Papyrus; no actualizar bloquea el proyecto nuevo.

A esto se le llama coloquialmente dependency hell (el infierno de las dependencias). Y tiene un segundo frente: si instalas todo en el Python del sistema operativo, puedes incluso interferir con herramientas del propio sistema que dependen de él (algunos Linux directamente lo bloquean con un error externally-managed-environment).

La solución es conceptualmente simple: que cada proyecto tenga su propia copia aislada del entorno de Python, con sus propios paquetes y versiones.

Un entorno virtual es una carpeta dentro de tu proyecto que contiene:

• Una copia (o enlace) del intérprete de Python.
• Su propia carpeta de paquetes instalados, independiente de la del sistema y de la de otros entornos.
• Scripts de activación que "redirigen" temporalmente los comandos python y pip hacia ese entorno.

Puntos clave para entenderlo bien:

• No es una máquina virtual ni nada pesado: es básicamente una carpeta con ficheros. Crear uno tarda segundos.
• Mientras un entorno está activado, todo lo que instales con pip cae dentro de él, sin tocar nada más.
• Si un entorno se estropea, se borra la carpeta y se crea otro. Nada del sistema se ve afectado.

La herramienta estándar para crearlos, venv, viene incluida con Python 3: no hay que instalar nada.

Sitúate en la carpeta de tu proyecto (la carpeta papyrus que creaste en la lección 01-02) y ejecuta:

Desglose del comando:

• python -m venv — ejecuta el módulo venv que trae Python (-m significa "ejecuta este módulo"; entenderás mejor los módulos en el módulo 3 del curso).
• .venv — el nombre de la carpeta donde se creará el entorno. Es el nombre convencional más extendido (el punto inicial la marca como carpeta "de trabajo interno"); también verás venv o env.

Tras unos segundos tendrás una carpeta .venv dentro del proyecto. No edites nada dentro de ella: es territorio de las herramientas.

Activar el entorno significa que, en esa terminal, python y pip pasan a ser los del entorno. El comando depende del sistema:

En Windows (PowerShell):

En macOS/Linux:

La señal inequívoca de que está activo es el prefijo (.venv) en el prompt de la terminal. A partir de ese momento:

Nota para Windows/PowerShell: si al activar aparece un error sobre "ejecución de scripts deshabilitada", ejecuta una vez Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser y vuelve a intentarlo. Es una protección de PowerShell, no un fallo de Python.

Nota para VS Code: al abrir la carpeta del proyecto, VS Code suele detectar .venv y preguntar si quieres usarlo como intérprete. Di que sí: así el editor y su terminal integrado usarán el entorno automáticamente. Si no pregunta, pulsa Ctrl+Shift+P → "Python: Select Interpreter" y elige el de .venv.

Para volver al Python del sistema en esa terminal:

El prefijo desaparece. El entorno no se borra: solo deja de estar activo. La próxima vez que trabajes en el proyecto, vuelves a activarlo. Y si algún día quieres eliminarlo de verdad, basta con borrar la carpeta .venv.

Ciclo de trabajo diario resumido:

pip es el gestor de paquetes de Python: descarga paquetes del repositorio oficial PyPI (Python Package Index, https://pypi.org, con cientos de miles de paquetes publicados) y los instala en el entorno activo.

Con el entorno .venv activado, los comandos esenciales:

(cowsay es un paquete de broma, perfecto para practicar sin riesgo: hace que una vaca de texto "diga" cosas.) pip descarga el paquete y sus dependencias y los instala en .venv. Probémoslo:

La sentencia import (que estudiarás a fondo en el módulo 3) es la forma de usar un paquete instalado desde tu código.

También puedes instalar una versión concreta, algo clave para la reproducibilidad:

Y para el detalle de un paquete concreto (versión, resumen, dependencias):

pip freeze es como pip list, pero en formato "reinstalable" (paquete==versión). Es la base del requirements.txt que viene ahora.

pip pedirá confirmación (y) y eliminará el paquete del entorno.

Imagina que compartes el proyecto Papyrus con otra persona (o con tu ordenador de dentro de un año). La carpeta .venv no se comparte (es pesada y específica de cada máquina); lo que se comparte es la lista de dependencias: el fichero requirements.txt.

Con el entorno activado y los paquetes que uses instalados:

El símbolo > redirige la salida del comando al fichero. El resultado es un fichero de texto en la raíz del proyecto:

Cada línea es un paquete con su versión exacta ("congelada"): la garantía de que otro entorno instalará exactamente lo mismo.

Quien reciba el proyecto (o tú mismo en otra máquina) solo necesita:

La opción -r significa "instala todo lo que lista este fichero". En tres comandos, un entorno idéntico al original.

Mantén requirements.txt actualizado: cada vez que instales o desinstales un paquete relevante para el proyecto, vuelve a ejecutar pip freeze > requirements.txt.

• Un entorno virtual por proyecto, siempre. Aunque el proyecto sea pequeño. Crear un .venv cuesta 10 segundos; deshacer un lío de versiones cuesta tardes enteras.
• No instales paquetes en el Python del sistema. El Python "global" debe quedarse limpio, solo para crear entornos. Si alguna vez ejecutas pip install y no ves (.venv) en el prompt, detente y activa el entorno.
• La carpeta del entorno se llama .venv y vive en la raíz del proyecto. Es la convención que las herramientas (VS Code incluido) detectan automáticamente.
• requirements.txt sí se comparte; .venv no. Si usas git, añade .venv/ al fichero .gitignore del proyecto para que no se suba al repositorio.
• No edites nada dentro de .venv. Se regenera, no se repara: ante cualquier problema extraño, borra la carpeta y recréala desde requirements.txt.
• Comprueba dónde estás instalando. pip --version muestra la ruta del pip activo; si apunta dentro de tu proyecto, todo correcto.
• Fija versiones en proyectos serios. pip freeze con == garantiza que el proyecto funcione igual dentro de seis meses, aunque los paquetes hayan publicado versiones nuevas.

venv + pip es el equipamiento estándar y es todo lo que necesitas en este curso. Pero en el mundo real oirás hablar de otras herramientas, y conviene que te suenen:

No las estudiaremos en este curso: todo lo que hagamos funciona con venv y pip. Si más adelante un equipo o tutorial usa conda o poetry, los conceptos que acabas de aprender (entorno aislado, lista de dependencias, versiones fijadas) son exactamente los mismos; solo cambian los comandos.

• Instalar sin activar el entorno: el error más frecuente. El paquete acaba en el Python del sistema y "misteriosamente" tu proyecto no lo encuentra (o al revés). Mira siempre el prefijo (.venv) antes de un pip install.
• Abrir una terminal nueva y olvidar reactivar: la activación es por terminal y por sesión. Terminal nueva (o reiniciada) = volver a activar.
• ModuleNotFoundError: No module named '...' al ejecutar tu script: casi siempre significa que el paquete está instalado en otro entorno (o en ninguno), o que VS Code está usando un intérprete distinto al de tu .venv. Revisa "Python: Select Interpreter".
• Error de "ejecución de scripts deshabilitada" en PowerShell: aplica el Set-ExecutionPolicy indicado en el apartado de activación; es cosa de PowerShell, no de tu instalación.
• Subir .venv a git o enviarla por correo: es pesada e inútil fuera de tu máquina. Lo portable es requirements.txt.
• Renombrar o mover la carpeta .venv: los entornos contienen rutas absolutas internas y dejan de funcionar. Si necesitas moverlo: borrar y recrear (con requirements.txt son dos comandos).
• Consejo: crea ya el entorno de tu carpeta papyrus y actívalo cada vez que trabajes en el curso, aunque de momento no instales casi nada. Cuando en los módulos 10 y 11 instalemos Flask, pandas y compañía, el hábito ya estará hecho.

En la carpeta papyrus de tu proyecto: crea un entorno virtual llamado .venv, actívalo, comprueba con pip list que está (casi) vacío y desactívalo. Anota los comandos exactos que has usado en tu sistema operativo.

Con el entorno de Papyrus activado: instala el paquete cowsay, comprueba con pip show cowsay qué versión tienes, genera el requirements.txt del proyecto y muestra su contenido por terminal.

Simula el "traspaso" del proyecto: desactiva y borra la carpeta .venv completa (tranquilo: para eso está el ejercicio), y reconstruye el entorno desde cero usando únicamente requirements.txt. Termina comprobando con pip list que cowsay volvió a instalarse.

Solución 1

En Windows (PowerShell):

En macOS/Linux:

pip list en un entorno recién creado muestra únicamente pip (y en algunas versiones, setuptools): esa es la prueba de que el entorno está limpio y aislado.

Solución 2

Con (.venv) visible en el prompt:

Para ver el contenido del fichero: type requirements.txt en Windows o cat requirements.txt en macOS/Linux. Debe contener algo como:

Solución 3

Borrar la carpeta: Remove-Item -Recurse -Force .venv en PowerShell (o eliminarla desde el explorador de archivos), rm -rf .venv en macOS/Linux. Después, reconstrucción:

pip list vuelve a mostrar cowsay en la versión exacta anotada en requirements.txt. Acabas de demostrar la idea central de la lección: el entorno es desechable; la lista de dependencias es lo valioso.

Con esta lección cierras el módulo de introducción equipado como un profesional: sabes por qué se aíslan las dependencias, creas y gestionas entornos con venv (crear, activar según sistema, desactivar), manejas pip (install, list, show, freeze, uninstall) y haces tus proyectos reproducibles con requirements.txt, siguiendo las buenas prácticas de un entorno por proyecto y un Python de sistema siempre limpio. También te suenan ya conda y poetry, las alternativas que encontrarás ahí fuera.

El proyecto Papyrus tiene ahora todo lo que necesita: un entorno de desarrollo completo, sus primeros scripts (bienvenida, catálogo, ficha interactiva de libros) y un entorno virtual listo para crecer. En el próximo módulo, Estructuras de Control, tus programas empezarán a tomar decisiones y a repetir tareas: condicionales para saber si hay stock, bucles para recorrer el catálogo entero, y mucho más. Ahí es donde la programación empieza a sentirse como un superpoder.