Entornos virtuales y pip

Imagina que tienes dos proyectos. Uno es una web que lleva dos años funcionando y necesita Django 4.2, porque con la versión nueva se rompe. El otro lo empiezas hoy y quieres Django 5.2. Si instalas las bibliotecas en el Python de tu sistema, solo puede haber una versión de Django instalada a la vez: cada vez que cambies de proyecto tendrás que desinstalar y reinstalar, y tarde o temprano uno de los dos dejará de arrancar.

La solución es no instalar nada en el Python del sistema. En su lugar, cada proyecto tiene su propia copia privada de Python con sus propias bibliotecas dentro de una carpeta. Eso es un entorno virtual, y hoy es la forma normal de trabajar en Python: un proyecto, un entorno.

Crear el entorno#

Colócate en la carpeta del proyecto y ejecuta:

python3 -m venv .venv

venv es un módulo de la biblioteca estándar, por eso se lanza con -m. El último argumento es el nombre de la carpeta que va a crear; .venv es el nombre que usa todo el mundo y el que reconocen los editores automáticamente.

Tarda unos segundos y deja una carpeta nueva:

ls -a .venv

.        ..        .gitignore    bin        include        lib        pyvenv.cfg

Dentro hay una copia del intérprete y una carpeta vacía donde se instalarán las bibliotecas. En Windows, en vez de bin verás Scripts.

Activarlo#

Crear el entorno no basta: hay que activarlo en cada terminal donde vayas a usarlo. El comando depende del sistema.

En Windows, con PowerShell:

.venv\Scripts\Activate.ps1

En Windows, con cmd:

.venv\Scripts\activate.bat

En macOS y Linux:

source .venv/bin/activate

Sabrás que ha funcionado porque el prompt de la terminal cambia y aparece el nombre del entorno entre paréntesis delante:

(.venv) erwin@portatil curso-python %

Ese (.venv) es toda la señal que tienes. Si no está, el entorno no está activo y todo lo que instales irá a parar al Python del sistema.

Para salir, en cualquier sistema:

deactivate

Instalar bibliotecas con pip#

Con el entorno activo, pip instala lo que le pidas dentro del entorno, sin tocar nada del sistema:

pip install requests

Collecting requests
  Downloading requests-2.34.2-py3-none-any.whl.metadata (4.8 kB)
Collecting charset_normalizer<4,>=2 (from requests)
  Downloading charset_normalizer-3.5.1-cp314-cp314-macosx_10_15_universal2.whl.metadata (45 kB)
Collecting idna<4,>=2.5 (from requests)
  Downloading idna-3.20-py3-none-any.whl.metadata (7.2 kB)
Collecting urllib3<3,>=1.26 (from requests)
  Downloading urllib3-2.8.0-py3-none-any.whl.metadata (7.4 kB)
Collecting certifi>=2023.5.7 (from requests)
  Downloading certifi-2026.7.22-py3-none-any.whl.metadata (2.5 kB)
Installing collected packages: urllib3, idna, charset_normalizer, certifi, requests
Successfully installed certifi-2026.7.22 charset_normalizer-3.5.1 idna-3.20 requests-2.34.2 urllib3-2.8.0

Fíjate en que has pedido una biblioteca y se han instalado cinco. Las otras cuatro son dependencias: cosas que requests necesita por dentro. Es normal y no tienes que hacer nada al respecto.

Las órdenes de pip que usarás a diario:

Para ver qué hay dentro del entorno:

pip list

Package            Version
------------------ ---------
certifi            2026.7.22
charset-normalizer 3.5.1
idna               3.20
pip                26.2.1
requests           2.34.2
urllib3            2.8.0

Congelar y restaurar: requirements.txt#

Tu proyecto no viaja con la carpeta .venv, pero sí tiene que viajar con la lista de lo que hay que instalar. Esa lista se genera con pip freeze:

pip freeze > requirements.txt

El fichero que sale es texto plano, una biblioteca por línea con su versión exacta:

certifi==2026.7.22
charset-normalizer==3.5.1
idna==3.20
requests==2.34.2
urllib3==2.8.0

Ese fichero sí se sube al repositorio, porque es la receta. Cuando alguien clone tu proyecto (o cuando lo hagas tú en otro ordenador), solo tiene que crear su entorno e instalar la receta:

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

Installing collected packages: urllib3, idna, charset-normalizer, certifi, requests
Successfully installed certifi-2026.7.22 charset-normalizer-3.5.1 idna-3.20 requests-2.34.2 urllib3-2.8.0

Y tendrá exactamente las mismas versiones que tú. Se acabó el "en mi ordenador funciona".

Seleccionar el intérprete en Visual Studio Code#

El editor necesita saber qué Python estás usando. Si no se lo dices, te subrayará en amarillo los import de todo lo que hayas instalado en el entorno, porque estará mirando el Python del sistema.

1. Abre la carpeta del proyecto en Visual Studio Code, no un fichero suelto.
2. Pulsa Ctrl + Shift + P (en macOS, Cmd + Shift + P).
3. Escribe Python: Select Interpreter y pulsa Intro.
4. En la lista, elige el que lleve .venv en la ruta. Suele aparecer marcado como Recommended.

Abajo a la derecha, en la barra de estado, verás la versión y el entorno seleccionados. Desde ese momento, cada terminal que abras dentro del editor se activará sola.

El entorno y git#

La carpeta .venv no se sube al repositorio nunca. Pesa cientos de megas, contiene rutas absolutas de tu ordenador y no sirve en una máquina distinta. Añade esta línea a tu .gitignore:

.venv/

De hecho, python3 -m venv crea un .gitignore dentro de la propia carpeta .venv para protegerte del descuido. Aun así, pon la línea también en el .gitignore del proyecto: es lo que espera ver cualquiera que mire tu código.

Lo que sí se sube es requirements.txt. Regla sencilla: se sube la receta, no el pastel.

Los dos errores de siempre#