pip y entornos virtuales en Python

La biblioteca estándar de Python es enorme, pero tarde o temprano necesitarás algo que no trae: hacer peticiones a una API, leer un Excel, crear una web con Flask o Django. Para eso existen cientos de miles de paquetes creados por la comunidad, y pip es la herramienta que los instala. En esta lección aprenderás a usar pip y, sobre todo, a hacerlo bien: dentro de un entorno virtual, para que cada proyecto tenga sus propias dependencias sin chocar con los demás.

PyPI y pip

PyPI (Python Package Index, en pypi.org) es el gran almacén público de paquetes de Python. pip es el programa que descarga paquetes de PyPI y los instala en tu ordenador, junto con los paquetes de los que a su vez dependen.

pip viene incluido con Python desde hace años. Compruébalo en la terminal:

python -m pip --version

En Windows puedes usar py en lugar de python, y en macOS y Linux suele ser python3. A lo largo de la lección escribimos python; cámbialo por el que funcione en tu equipo (lo viste en la introducción).

Consejo: escribe python -m pip en lugar de pip a secas. Así te aseguras de que pip instala en el mismo Python que luego ejecuta tu programa. Si tienes varias versiones instaladas, pip podría corresponder a otra. Dentro de un entorno virtual activado, los dos son equivalentes.

Los comandos básicos de pip

Instalar y desinstalar

python -m pip install requests            # la última versión
python -m pip install requests==2.32.3    # una versión exacta
python -m pip install "requests>=2.30"    # como mínimo esa versión
python -m pip install --upgrade requests  # actualizar a la última
python -m pip uninstall requests          # desinstalar (pide confirmación)

Al instalar requests, pip también instala sus dependencias (certifi, idna, urllib3 y charset-normalizer). Las comillas en "requests>=2.30" evitan que la terminal interprete > como una redirección.

Consultar lo que tienes

python -m pip list              # todos los paquetes instalados y su versión
python -m pip show requests     # información de un paquete concreto
python -m pip freeze            # lista en formato "paquete==versión"

La salida de pip show tiene este aspecto (las versiones y rutas cambian en cada equipo):

Name: requests
Version: 2.32.3
Summary: Python HTTP for Humans.
Location: /home/ana/tienda/.venv/lib/python3.12/site-packages
Requires: certifi, charset-normalizer, idna, urllib3
Required-by:

Requires indica de qué depende el paquete y Required-by, qué otros paquetes lo necesitan a él. Antes de desinstalar algo, mira esta última línea.

requirements.txt: compartir las dependencias

Si subes tu proyecto a GitHub o se lo pasas a un compañero, ¿cómo sabe qué paquetes necesita? Por convención se guarda una lista en un fichero llamado requirements.txt. La forma más rápida de generarlo es con freeze:

python -m pip freeze > requirements.txt

El fichero queda así:

certifi==2024.8.30
charset-normalizer==3.4.0
idna==3.10
requests==2.32.3
urllib3==2.2.3

Y quien descargue el proyecto instala exactamente esas versiones con un solo comando:

python -m pip install -r requirements.txt

Fijar versiones exactas con == garantiza que el programa funcione igual en todos los equipos. También puedes escribir el fichero a mano, solo con lo que usas directamente (requests>=2.32), y dejar que pip resuelva el resto.

Cuidado: pip freeze lista todo lo instalado en el entorno. Si lo ejecutas fuera de un entorno virtual, meterás en requirements.txt paquetes que tu proyecto no usa. Otra razón para lo que viene a continuación.

Por qué necesitas entornos virtuales

Sin entornos virtuales, todos los paquetes van a una única carpeta site-packages del Python del sistema (la viste en módulos, al hablar de sys.path). Eso da problemas enseguida:

• Conflictos de versiones: el proyecto de clase necesita Django 4 y el de prácticas, Django 5. Solo puede haber una versión instalada.
• Listas de dependencias sucias: no sabes qué paquete usa cada proyecto.
• Romper el sistema: en Linux y macOS, el propio sistema usa Python. Instalar o actualizar paquetes globales puede estropear herramientas del sistema.

Un entorno virtual es una carpeta con una copia aislada de Python y su propio site-packages. Lo que instalas dentro solo existe para ese proyecto. Es como tener una caja de herramientas distinta para cada trabajo.

Consejo: en versiones modernas de Linux y en Python de Homebrew, pip install fuera de un entorno virtual da el error externally-managed-environment. No es un fallo: el sistema te está pidiendo que uses un entorno virtual.

Crear y usar un entorno virtual

Crear el entorno

Python trae el módulo venv. Desde la carpeta de tu proyecto:

cd tienda
python -m venv .venv

Esto crea la carpeta .venv (el nombre es una convención muy extendida; el punto la oculta en macOS y Linux). Dentro hay un intérprete de Python, pip y una carpeta site-packages vacía:

tienda/
├── .venv/
│   ├── bin/          (en Windows se llama Scripts/)
│   ├── lib/
│   └── pyvenv.cfg
├── main.py
└── requirements.txt

En Debian y Ubuntu, si da error, instala antes el paquete python3-venv con apt.

Activarlo

Activar el entorno hace que los comandos python y pip de esa terminal apunten a los de .venv. Depende del sistema:

Sistema y terminal	Comando
Windows, PowerShell	.venv\Scripts\Activate.ps1
Windows, cmd	.venv\Scripts\activate.bat
macOS y Linux (bash, zsh)	source .venv/bin/activate

Sabrás que está activo porque el principio de la línea de la terminal muestra el nombre del entorno:

(.venv) PS C:\Users\ana\tienda>
(.venv) ana@portatil:~/tienda$

Cuidado: en PowerShell puede aparecer un error de que la ejecución de scripts está deshabilitada. Se soluciona una sola vez con Set-ExecutionPolicy -Scope CurrentUser RemoteSigned y respondiendo que sí.

Con el entorno activo, comprueba que todo apunta a .venv:

python -c "import sys; print(sys.prefix)"
# /home/ana/tienda/.venv
python -m pip list
# Package Version
# ------- -------
# pip     24.0

Un entorno recién creado solo tiene pip. A partir de aquí, todo lo que instales queda dentro de .venv.

Desactivarlo

deactivate

La terminal vuelve al Python del sistema. No hace falta desactivar para cerrar la terminal; la activación solo dura mientras la terminal está abierta, así que cada vez que abras una nueva tendrás que activarlo otra vez.

Consejo: Visual Studio Code detecta la carpeta .venv y te propone usarla. Si no, pulsa Ctrl+Mayús+P, busca Python: Select Interpreter y elige el de .venv. Su terminal integrada lo activará sola.

.venv no se sube a Git

El entorno virtual pesa mucho, contiene rutas de tu equipo y no funciona en otro ordenador. Nunca lo subas al repositorio: lo que se comparte es requirements.txt, y cada persona crea su propio entorno. Añade a tu .gitignore:

.venv/
__pycache__/

Si el entorno se estropea, no pasa nada: bórralo, créalo de nuevo e instala desde requirements.txt.

Ejemplo completo: un proyecto con requests

Vamos a crear un pequeño programa que consulta la API pública de GitHub. Primero, en la terminal (macOS o Linux; en Windows cambia la línea de activación):

mkdir consulta-github
cd consulta-github
python -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -m pip freeze > requirements.txt

Después, el archivo main.py:

import requests

url = "https://api.github.com/repos/python/cpython"

try:
    respuesta = requests.get(url, timeout=10)
    respuesta.raise_for_status()      # lanza un error si el código no es 2xx
except requests.RequestException as e:
    print("No se pudo consultar la API:", e)
else:
    datos = respuesta.json()          # convierte el JSON en un diccionario
    print(respuesta.status_code)      # 200
    print(datos["full_name"])         # python/cpython
    print(datos["language"])          # Python
    print(f"{datos['stargazers_count']} estrellas")   # el número cambia cada día

Y lo ejecutas con el entorno activo:

python main.py

Qué hace cada parte:

• requests.get hace la petición HTTP. El timeout evita que el programa se quede colgado si el servidor no responde.
• raise_for_status() convierte los errores HTTP (404, 500…) en una excepción, que capturamos con requests.RequestException como aprendiste en excepciones.
• respuesta.json() hace lo mismo que json.loads del módulo json, pero directamente sobre la respuesta.

Si ejecutas main.py sin activar el entorno, obtendrás ModuleNotFoundError: No module named 'requests': el paquete solo existe dentro de .venv. Es la prueba de que el aislamiento funciona.

Más allá de pip: uv y poetry

pip y venv son el estándar y vienen con Python, así que es lo primero que debes dominar. En proyectos profesionales verás también otras herramientas que automatizan el proceso:

• uv: muy rápido (está escrito en Rust). Con uv venv crea el entorno y con uv pip install requests instala usando los mismos comandos que ya conoces. Además, uv init y uv add requests gestionan el proyecto completo con un fichero pyproject.toml.
• poetry: gestiona dependencias y entornos a partir de pyproject.toml (poetry add requests) y guarda las versiones exactas en un fichero poetry.lock. Muy usado para crear y publicar librerías.

Todas persiguen lo mismo que has aprendido aquí: dependencias declaradas en un fichero y un entorno aislado por proyecto.

Errores frecuentes

• Instalar sin activar el entorno: el paquete acaba en el Python global y tu proyecto no lo encuentra, o al revés.
• ModuleNotFoundError tras instalar: el editor o la terminal usan otro intérprete. Comprueba con python -c "import sys; print(sys.executable)".
• Subir .venv al repositorio: añádelo a .gitignore.
• Olvidar actualizar requirements.txt después de instalar un paquete nuevo.
• Usar sudo pip install en Linux o macOS: puede romper el Python del sistema. Usa un entorno virtual.
• Mover o renombrar la carpeta del proyecto: el entorno guarda rutas absolutas y puede dejar de funcionar. Bórralo y créalo de nuevo.

Resumen

Tarea	Comando
Instalar un paquete	python -m pip install requests
Versión concreta	python -m pip install requests==2.32.3
Actualizar	python -m pip install --upgrade requests
Desinstalar	python -m pip uninstall requests
Ver instalados	python -m pip list
Detalles de un paquete	python -m pip show requests
Guardar dependencias	python -m pip freeze > requirements.txt
Instalar dependencias	python -m pip install -r requirements.txt
Crear entorno	python -m venv .venv
Activar (Windows)	.venv\Scripts\Activate.ps1 o .venv\Scripts\activate.bat
Activar (macOS/Linux)	source .venv/bin/activate
Desactivar	deactivate

Con esto ya puedes usar cualquier paquete de PyPI en tus proyectos de forma ordenada. Crear un entorno virtual por proyecto debería convertirse en un hábito desde el primer día.