pip en Python: instalar paquetes, gestionar versiones y usar PyPI

Qué es pip realmente

pip es la herramienta que instala librerías de Python que no escribiste tú. Cuando ejecutas pip install requests, busca requests en PyPI (el Python Package Index), descarga la versión correcta para tu plataforma y la deposita en el directorio site-packages de tu instalación de Python. Después de eso, import requests funciona.

Cada instalación de Python 3 desde python.org, Homebrew o tu gestor de paquetes de Linux viene con pip ya instalado. Antes de instalar nada, verifica:

python -m pip --version

Deberías ver un número de versión y una ruta al módulo pip. Si el comando falla, el arreglo más fiable es:

python -m ensurepip --upgrade

Eso hace un bootstrap de pip en tu instalación de Python usando la copia que viene con el intérprete.

python -m pip vs pip

Verás ambas formas. Hacen casi lo mismo con una diferencia importante: python -m pip usa el python en tu PATH — el mismo que usan tus scripts. pip a secas usa el pip que aparezca primero, que no siempre es el mismo.

Cuando tienes más de un Python instalado (fácil de acabar así en macOS), pip a secas es cómo llegas a la situación confusa de "instalé la librería pero mi código sigue diciendo ModuleNotFoundError".

Regla general: usa python -m pip ... cuando quieras certeza sobre qué intérprete recibe el paquete. pip a secas está bien para trabajo rápido cuando estás seguro.

Instalar un paquete

El comando básico:

python -m pip install requests

Eso trae requests desde PyPI, junto con cualquier cosa de la que dependa, y los instala. Un minuto después puedes usarlo:

Instalar varios paquetes de una vez:

python -m pip install requests pandas rich

Fijar una versión específica:

python -m pip install "django==5.0.2"
python -m pip install "requests>=2.30,<3"

Las comillas importan en algunas shells — impiden que == y < se interpreten como operadores de shell.

Actualizar y desinstalar

python -m pip install --upgrade requests
python -m pip uninstall requests

--upgrade trae la versión más nueva que satisfaga la restricción que especifiques. uninstall quita el paquete pero no sus dependencias; esas se quedan hasta que las quitas explícitamente.

Para mantener pip en sí al día:

python -m pip install --upgrade pip

Vale la pena ejecutarlo una vez cada pocos meses. Las versiones más nuevas de pip cazan más problemas de instalación y resuelven mejor las dependencias.

Ver qué hay instalado

python -m pip list
python -m pip show requests

list muestra cada paquete instalado en el Python actual. show requests imprime la versión, ubicación, dependencias y licencia de ese paquete específico — útil cuando te preguntas "¿qué versión de esto estoy usando realmente?".

requirements.txt: apuntar tus dependencias

Cuando un proyecto tiene más de un par de librerías, apunta la lista. pip freeze lo hace por ti:

python -m pip freeze > requirements.txt

Eso produce un archivo con una dependencia fijada por línea:

django==5.0.2
requests==2.31.0
rich==13.7.1

Cualquiera que clone tu repo puede reproducir la instalación con:

python -m pip install -r requirements.txt

pip freeze captura todo lo instalado, incluidas las dependencias transitivas. Eso está bien para reproducibilidad exacta pero es ruidoso cuando solo quieres las librerías de nivel superior que tu código realmente importa. Muchos proyectos mantienen un requirements.txt escrito a mano con las dependencias directas, y dejan que pip resuelva las transitivas.

Para proyectos modernos, pyproject.toml (emparejado con herramientas como pip-tools, uv, poetry o hatch) está tomando el relevo de requirements.txt. El concepto es el mismo — "apunta las dependencias, ejecuta un comando para instalarlas" — pero el formato de archivo está más estructurado.

Instala siempre en un entorno virtual

Cada proyecto real de Python debería tener un entorno virtual. Es una carpeta local al proyecto con su propio python y sus propios paquetes instalados — así que pip install en un proyecto no afecta a ningún otro.

La configuración de dos líneas:

python -m venv .venv
source .venv/bin/activate    # macOS / Linux
# o .venv\Scripts\activate en Windows

Una vez activado, python -m pip install requests instala en el venv. Tu Python de sistema queda limpio. Lo cubrimos con más detalle en la página de Entornos Virtuales.

Si alguna vez ejecutas pip install y ves un aviso sobre instalar en el Python del sistema (o un mensaje diciéndote que pases --break-system-packages), para. Esa es tu señal para crear un venv en su lugar.

Cuando pip no puede instalar un paquete

Unas cuantas modalidades comunes de fallo y qué significan:

• Could not find a version that satisfies the requirement … — normalmente un typo en el nombre del paquete, o el paquete requiere un Python más nuevo del que tienes.
• error: Microsoft Visual C++ 14.0 or greater is required (Windows) — el paquete tiene una extensión nativa y necesita un toolchain de build de C++. O instala las Build Tools de Microsoft o busca un wheel precompilado (la mayoría de paquetes populares los traen).
• Permission denied — estás intentando instalar en el Python del sistema sin root. El arreglo correcto no es sudo pip install — es un entorno virtual.
• ModuleNotFoundError después de instalar — casi siempre un caso donde pip install aterrizó el paquete en un Python distinto del que está ejecutando tu script. Comprueba which python y which pip (macOS/Linux) o where python / where pip (Windows). O, más fiable, usa python -m pip install ....

Alternativas modernas a pip

Unas cuantas herramientas que verás mencionadas — todas son compatibles con pip y resuelven dolores específicos:

• uv — un instalador y resolver mucho más rápido. Reemplazo drop-in para la mayoría de comandos de pip.
• pipx — instala herramientas de línea de comandos (como black, ruff, httpie) en venvs aislados para que estén disponibles globalmente sin entrar en conflicto con las dependencias de proyectos.
• poetry y hatch — gestores de proyecto que combinan manejo de entornos virtuales, resolución de dependencias y build en una sola herramienta.

No necesitas ninguna el primer día. Aprende pip primero; recurre a las otras cuando el dolor que resuelven se vuelva tuyo.

Siguiente: entornos virtuales

Paquetes y entornos virtuales van juntos. Ya has visto por qué; la siguiente página te lleva por venv en detalle — crear, activar, desactivar y las pequeñas convenciones que mantienen los proyectos Python organizados.