Cómo solucionar el error pip install non-zero exit status en Python

El mensaje de fallo con código de salida distinto de cero indica que la herramienta pip no ha podido instalar un paquete porque la compilación del código fuente ha fallado o faltan dependencias del sistema. Este problema suele ocurrir cuando una librería requiere compilar módulos en C o C++ y el sistema no encuentra las cabeceras de desarrollo o los compiladores necesarios. La solución más rápida consiste en instalar los paquetes precompilados (wheels) o configurar las herramientas de compilación de tu sistema operativo.

Qué significa el error

El error CalledProcessError: Command returned non-zero exit status o error: command failed with exit status 1 aparece durante el proceso de ejecución de pip install. Indica que un subproceso invocado por pip (como gcc, clang, msvc o setup.py) se ha interrumpido de forma inesperada devolviendo un código de error distinto de 0. Afecta a entornos de Windows, Linux y macOS al intentar instalar librerías pesadas como pandas, numpy, psycopg2 o cffi desde paquetes de código fuente (sdist) en lugar de binarios ejecutables.

Causas más habituales

Falta de herramientas de compilación (Build Tools de Visual Studio en Windows o build-essential en Linux).
Ausencia de archivos de cabecera de desarrollo de Python (como python3-dev).
Intentar instalar una versión de un paquete incompatible con la versión de Python en uso.
Problemas de permisos al intentar escribir en directorios del sistema sin un entorno virtual.
Librerías de C/C++ externas no presentes en el sistema operativo (como libpq-dev o libssl-dev).
Versión obsoleta de las herramientas base pip, setuptools y wheel.

Antes de empezar

Antes de aplicar cualquier cambio, asegúrate de utilizar un entorno virtual para no comprometer la instalación global del sistema operativo. Si la instalación requiere modificar librerías del sistema en Linux, necesitarás privilegios de administrador (sudo). Verifica la versión exacta de Python que estás ejecutando escribiendo python --version o python3 --version en tu terminal.

1. Actualizar las herramientas fundamentales de instalación

Las versiones antiguas de pip, setuptools y wheel a menudo intentan compilar paquetes desde el código fuente cuando ya existen versiones binarias precompiladas (wheels) compatibles con tu sistema en PyPI. Al actualizar estos tres componentes, obligas a pip a descargar la versión precompilada, evitando el proceso de compilación local.

Abre tu consola de comandos o terminal.
Si usas un entorno virtual, asegúrate de tenerlo activado.
Ejecuta el siguiente comando para actualizar las herramientas clave:

python -m pip install --upgrade pip setuptools wheel

En sistemas Linux o macOS donde python apunte a una versión antigua, utiliza el comando explícito:

python3 -m pip install --upgrade pip setuptools wheel

Prueba de nuevo la instalación del paquete que fallaba. En la mayoría de los casos, este paso evita que pip intente compilar archivos en C.

2. Instalar herramientas de compilación en el sistema operativo

Si la librería que necesitas no dispone de un fichero wheel para tu arquitectura o versión de Python, pip intentará compilar el código. Si tu sistema carece de compilador, la instalación devolverá un estado de salida no nulo.

En Windows:

Descarga e instala Build Tools para Visual Studio desde la página oficial de Microsoft.
Durante la instalación, selecciona la carga de trabajo Desarrollo para el escritorio con C++.
Asegúrate de que los componentes MSVC v143 - C++ x64/x86 build tools y Windows 11 SDK (o Windows 10 SDK) estén marcados.
Reinicia el ordenador tras completar la instalación y vuelve a intentar la descarga con pip.

En Ubuntu / Debian:

Abre la terminal y actualiza el índice de paquetes:

sudo apt update

Instala los compiladores básicos y las cabeceras de desarrollo de Python:

sudo apt install build-essential python3-dev python3-pip -y

En macOS:

Abre la terminal e instala las herramientas de línea de comandos de Xcode ejecutando:

xcode-select --install

Sigue las instrucciones en pantalla para aceptar la licencia y completar la instalación.

3. Instalar librerías de desarrollo específicas del paquete

Determinados paquetes de Python son adaptadores para bibliotecas escritas en C. Por ejemplo, psycopg2 necesita la librería cliente de PostgreSQL, y Cryptography requiere las cabeceras de OpenSSL. Si estas dependencias no están instaladas en el sistema operativo, pip fallará al compilar.

Revisa el log de error justo encima de la línea que indica el fallo de salida. Busca mensajes del tipo fatal error: header.h: No such file or directory.
Instala la biblioteca del sistema correspondiente según el módulo que necesites:

Para bases de datos PostgreSQL (psycopg2):
```
sudo apt install libpq-dev
```
Para criptografía y SSL (cryptography, pyOpenSSL):
```
sudo apt install libssl-dev libffi-dev
```
Para procesamiento de imágenes (Pillow):
```
sudo apt install libjpeg-dev zlib1g-dev
```

Para parseo XML/HTML (lxml):

sudo apt install libxml2-dev libxslt1-dev

Tras instalar la librería del sistema correspondiente, vuelve a ejecutar el comando pip install.

4. Utilizar un entorno virtual aislado

El intento de instalar paquetes directamente en el Python del sistema operativo puede provocar conflictos de permisos o interferir con paquetes gestionados por el gestor de software de la distribución (como apt o pacman), lo que deriva en errores de tipo non-zero exit status.

Navega hasta la carpeta de tu proyecto en la consola.
Crea un entorno virtual limpio:

python3 -m venv venv

Activa el entorno virtual:

En Linux / macOS:
```
source venv/bin/activate
```
En Windows (CMD):
```
venvininalize
```
o
```
venv
cinalize
```
En Windows (PowerShell):
```
venvininalize.ps1
```

Instala el paquete dentro del entorno virtual activo:

pip install nombre_del_paquete

Si tenías problemas previos relacionados con librerías cruzadas o rutas de importación, consultar la solución al error ModuleNotFoundError en Python te ayudará a estructurar correctamente tu entorno.

5. Utilizar versiones precompiladas alternativas (Conda o Binary Wheels)

Si la compilación local sigue fallando debido a incompatibilidades complejas del compilador, puedes recurrir a gestores de paquetes que distribuyen binarios previamente probados.

Si trabajas con paquetes de ciencia de datos (como OpenCV, PyTorch o TensorFlow), considera utilizar Conda en lugar de pip. Conda descarga los binarios ya compilados junto con todas sus dependencias en C:

conda install nombre_del_paquete

Si prefieres seguir usando pip, fuerza el uso exclusivo de paquetes binarios indicando que no intente compilar el código fuente:

pip install --only-binary :all: nombre_del_paquete

Si el paquete no tiene un binario disponible para tu versión de Python, este comando te advertirá de forma clara antes de intentar compilar nada.

Cómo comprobar que se ha solucionado

Para verificar que el paquete se ha instalado correctamente y es totalmente funcional, sigue estos pasos:

Abre el intérprete interactivo de Python escribiendo python o python3 en tu consola.
Importa el módulo recién instalado. Por ejemplo, si instalaste psycopg2:

import psycopg2  print(psycopg2.__version__)

Si el comando no devuelve ningún mensaje de error de compilación o de importación y muestra el número de versión, la instalación se ha completado con éxito. En caso de que se produzcan errores al ejecutar el código cargado, puedes consultar cómo solucionar un UnboundLocalError en Python para depurar el comportamiento del script.

Si nada de lo anterior funciona

Si el comando continúa fallando con un código de salida no nulo, debes examinar detenidamente la salida completa de la consola. La parte clave no es la última línea sobre el exit status, sino las líneas anteriores donde el compilador muestra el fallo detallado.

Busca la primera línea que contenga la palabra error: dentro del bloque de texto rojo o blanco extenso.
Verifica si la versión de Python que estás utilizando es demasiado reciente (por ejemplo, utilizar una versión Alpha o Beta) o demasiado antigua para el paquete que intentas instalar. Prueba a cambiar a una versión LTS de Python como 3.10 o 3.11.
Si estás trabajando en una arquitectura ARM (como ordenadores Mac con chips M1/M2/M3 o Raspberry Pi), comprueba en la documentación oficial del paquete si ofrecen soporte nativo para arm64 o si requieren ejecutar la terminal bajo emulación Rosetta 2.

Preguntas frecuentes

¿Por qué pip intenta compilar en lugar de bajar un ejecutable?

Esto sucede cuando los desarrolladores del paquete no han subido un archivo precompilado (wheel) compatible exactamente con tu versión de Python, tu sistema operativo o la arquitectura de tu procesador. En ese caso, pip descarga el código fuente (.tar.gz) e intenta compilarlo localmente.

¿Es seguro ejecutar pip con permisos de administrador o sudo?

No se recomienda usar sudo pip install. Hacerlo puede sobrescribir librerías críticas del sistema operativo y provocar fallos en el funcionamiento general del sistema. Es mucho más seguro utilizar siempre entornos virtuales con venv.

¿Qué significa el error command 'gcc' failed with exit status 1?

Significa que el compilador C de Linux (gcc) encontró un fallo durante la fase de compilación del paquete. Casi siempre se debe a que falta un archivo de cabecera (.h) del sistema, el cual se soluciona instalando el paquete -dev correspondiente mediante apt.

¿Cómo soluciono este error al desplegar en un contenedor Docker?

En imágenes base reducidas como python:alpine o python:slim, faltan los compiladores por defecto. Debes añadir comandos en tu Dockerfile como RUN apt-get update && apt-get install -y build-essential (en Debian/Ubuntu) o RUN apk add --no-cache build-base (en Alpine) antes de ejecutar pip install.