Problemas Comunes al Instalar Librerías con pip

Problemas Comunes al Instalar Librerías con pip

📘 Este artículo forma parte de nuestra Guía Completa de Inteligencia Artificial 2026 y complementa a Cómo actualizar todas las bibliotecas instaladas en Python. Si trabajas con Python, esas guías son tu punto de partida.

Introducción

pip es el gestor de paquetes estándar de Python, y también una de las mayores fuentes de frustración para desarrolladores de todos los niveles. ¿Quién no se ha enfrentado alguna vez a un:

  • ERROR: Could not build wheels for...
  • ModuleNotFoundError: No module named 'X'
  • PermissionError: [Errno 13] Permission denied
  • ERROR: Dependency resolution failed

Estos errores pueden arruinarte el día y hacerte perder horas. La buena noticia: el 95% de los problemas tienen soluciones conocidas.

En esta guía completa vas a aprender:

  • Los 20 problemas más comunes al instalar con pip.
  • Cómo diagnosticarlos paso a paso.
  • Soluciones probadas para cada uno.
  • Herramientas modernas (uv, pipx, pip-tools).
  • Buenas prácticas para evitar problemas.
  • Entornos virtuales: por qué son obligatorios.
  • Cómo leer los errores de pip.
  • Alternativas a pip cuando todo falla.
  • FAQ con las preguntas más frecuentes.

Si estás empezando con Python, consulta Aprende a programar en Python desde cero. Para actualizar librerías, Cómo actualizar todas las bibliotecas.


Índice de contenidos

  1. Por qué falla pip tan a menudo
  2. Cómo leer los errores de pip
  3. Problemas de permisos
  4. Problemas de compilación
  5. Problemas de dependencias
  6. Problemas de red y SSL
  7. Problemas de versión de Python
  8. Problemas con paquetes específicos
  9. Problemas de caché
  10. Problemas de entorno virtual
  11. Alternativas a pip
  12. Buenas prácticas
  13. FAQ
  14. Conclusión

1. Por qué falla pip tan a menudo

1.1 El ecosistema Python

Complejidad:

  • +500.000 paquetes en PyPI.
  • +3.000 nuevos cada mes.
  • Dependencias anidadas (paquetes que dependen de otros).
  • Diferentes sistemas operativos.
Problemas Comunes al Instalar Librerías con pip

1.2 Paquetes con código compilado

Muchos paquetes incluyen código C/C++/Rust:

  • NumPy, Pandas (C).
  • TensorFlow, PyTorch (C++/CUDA).
  • cryptography (Rust).
  • psycopg2 (C).

En Windows suele haber «wheels» precompilados.
En Linux algunos requieren compilación local.

1.3 Entornos heterogéneos

Cada usuario tiene:

  • Python diferente (3.9, 3.10, 3.11, 3.12, 3.13).
  • Sistema operativo distinto.
  • Compiladores instalados o no.
  • Librerías del sistema distintas.

Resultado: lo que funciona en mi máquina, falla en la tuya.

1.4 Gestión de dependencias compleja

Ejemplo:

proyecto → pandas → numpy
proyecto → scikit-learn → scipy → numpy
proyecto → matplotlib → numpy

Si numpy tiene 3 versiones requeridas distintas → conflicto.

1.5 El error más común: no usar entorno virtual

Sin entorno virtual:

  • Paquetes van al sistema.
  • Conflictos con otros proyectos.
  • Problemas de permisos.
  • Rompe el Python del sistema.

Consulta Cómo actualizar todas las bibliotecas.


2. Cómo leer los errores de pip

2.1 Anatomía de un error

Collecting numpy==1.24.0
  Using cached numpy-1.24.0.tar.gz (10.5 MB)
  Preparing metadata (setup.py) ... error
  error: subprocess-exited-with-error
  
  × python setup.py egg_info did not run successfully.
  │ exit code: 1
  ╰─> [15 lines of output]
      Traceback (most recent call last):
        File "<string>", line 2, in <module>
        File "<pip-setuptools-caller>", line 34, in <module>
        File "/tmp/pip-install-xxx/numpy_xxx/setup.py", line 400
          f"'{sys.executable}'", 
      SyntaxError: invalid syntax
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: subprocess-exited-with-error

Información clave:

  • Paquete: numpy==1.24.0.
  • Fase: preparación de metadata (setup.py).
  • Error: SyntaxError.
  • Causa probable: versión de Python incompatible.

2.2 Verbose mode

Siempre útil:

pip install -v numpy

O:

pip install --verbose numpy

Muestra más detalles.

2.3 Log completo

pip install numpy 2> error.log
cat error.log

Ventaja: puedes buscar palabras clave.

2.4 Palabras clave a buscar

  • PermissionError: permisos.
  • ModuleNotFoundError: módulo faltante.
  • SyntaxError: incompatible con Python.
  • error: command ... failed: compilación.
  • Could not find a version: paquete no existe o no compatible.
  • No matching distribution: sin wheel para tu sistema.

2.5 Google es tu amigo

Copia el error exacto y búscalo en Google:

  • Stack Overflow.
  • GitHub Issues.
  • Documentación oficial.

Recomendación: el 90% de los errores ya han sido resueltos por otros.

Consulta Guía Completa de Linux.


3. Problemas de permisos

3.1 Permission denied

Error típico:

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: '/usr/lib/python3/dist-packages/...'

Causa: intentas instalar en el Python del sistema sin permisos.

3.2 La solución correcta: entorno virtual

Nunca uses sudo pip install. Rompe el sistema.

Solución:

python3 -m venv venv
source venv/bin/activate
pip install numpy

En Windows:

python -m venv venv
venv\Scripts\activate
pip install numpy

3.3 Instalación con –user (parche temporal)

Si no puedes usar venv:

pip install --user numpy

Instala en ~/.local/ en lugar de /usr/lib/.

⚠️ Limitaciones:

  • No es tan aislado.
  • Puede haber conflictos.
  • No ideal para proyectos.

3.4 La solución incorrecta: sudo

Lo que NO hacer:

sudo pip install numpy  <em># ❌ NUNCA</em>

Por qué es malo:

  • Rompe el Python del sistema.
  • Conflictos con gestor de paquetes.
  • Problemas en el futuro.

Excepción: algunas distros lo permiten con --break-system-packages (mala idea).

3.5 Permisos en venv

Si ya estás en venv y sigue fallando:

# Verificar que estás en venv
which python
# Debería mostrar .../venv/bin/python

# Verificar permisos
ls -la venv/

Si está corrupto:

rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install numpy

3.6 Problemas en Windows

PowerShell con ExecutionPolicy:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

O usar cmd.exe.


4. Problemas de compilación

4.1 «Could not build wheels»

Error típico:

ERROR: Could not build wheels for psycopg2, which is required to install pyproject.toml-based projects

Causa: el paquete requiere compilación C/C++ y no tienes las herramientas.

4.2 Solución: instalar herramientas de compilación

Ubuntu/Debian:

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

Fedora:

sudo dnf install -y gcc gcc-c++ python3-devel

macOS:

xcode-select --install

Windows: instala Visual Studio Build Tools:

4.3 Solución: usar wheels precompilados

Muchos paquetes tienen wheels binarios:

# Forzar wheel (no compilación)
pip install --only-binary :all: numpy

Si no hay wheel para tu plataforma → compilación.

4.4 Paquetes problemáticos comunes

PaqueteSolución
psycopg2pip install psycopg2-binary
mysqlclientpip install mysqlclient con libmysqlclient-dev
lxmlpip install lxml (wheels en la mayoría)
cryptographypip install cryptography (wheels)
pycryptousar pycryptodome
pycurlinstalar libcurl4-openssl-dev

4.5 «fatal error: Python.h: No such file»

Causa: falta python3-dev.

Solución:

sudo apt install python3-dev

O específico de tu versión:

sudo apt install python3.12-dev

4.6 «error: command ‘gcc’ failed»

Verifica gcc:

gcc --version

Si falta:

sudo apt install build-essential

4.7 «Microsoft Visual C++ 14.0 required» (Windows)

Solución: instala Visual Studio Build Tools.

Alternativa: busca wheel precompilado.

En muchas webs: https://www.lfd.uci.edu/~gohlke/pythonlibs/ (no oficial).

Consulta Cómo configurar CUDA y cuDNN (aplicable a compilación).


5. Problemas de dependencias

5.1 «Dependency resolution failed»

Error típico:

ERROR: Cannot install packageA and packageB because these package versions have conflicting dependencies.

Causa: dos paquetes requieren versiones incompatibles.

5.2 Diagnóstico

pip install -v numpy pandas

Busca qué paquete requiere qué versión.

Herramienta:

pip install pipdeptree
pipdeptree --warn silence

Muestra el árbol de dependencias.

5.3 Soluciones

1. Actualizar todo:

pip install --upgrade --upgrade-strategy eager numpy pandas

2. Instalar versiones compatibles:

pip install "numpy>=1.24,<1.27" "pandas>=2.0,<2.3"

3. Usar pip-tools:

pip install pip-tools
pip-compile requirements.in
pip-sync requirements.txt

4. Usar uv:

uv pip install numpy pandas

Consulta Cómo actualizar todas las bibliotecas.

5.4 «No matching distribution found»

Error típico:

ERROR: Could not find a version that satisfies the requirement numpy==1.24.0
ERROR: No matching distribution found for numpy==1.24.0

Causas:

  • Versión no existe.
  • No compatible con tu Python.
  • No compatible con tu plataforma.
  • Problema de red.

Soluciones:

# Verificar que existe
pip index versions numpy

# Ver Python
python --version

# Buscar sin versión
pip install numpy

5.5 «Requires a version of Python»

Error:

ERROR: Package 'foo' requires a different Python: 3.10.0 not in '>=3.11'

Solución: actualiza Python o usa versión compatible del paquete.

pip install "foo==1.2.0"  <em># Versión compatible</em>

5.6 Instalar versión específica

pip install numpy==1.24.0

O rango:

pip install "numpy>=1.24,<1.26"

O última compatible:

pip install --upgrade --upgrade-strategy only-if-needed numpy

6. Problemas de red y SSL

6.1 «SSL: CERTIFICATE_VERIFY_FAILED»

Error típico:

ERROR: Could not fetch URL https://pypi.org/simple/numpy/: There was a problem confirming the ssl certificate

Causas:

  • Proxy corporativo.
  • Firewall.
  • Certificados desactualizados.
  • Antivirus interceptando SSL.

6.2 Solución 1: Actualizar certifi

pip install --upgrade certifi

6.3 Solución 2: Usar trusted-host (temporal)

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org numpy

⚠️ Solo como diagnóstico, no permanente.

6.4 Solución 3: Configurar proxy

Si estás en empresa con proxy:

pip install --proxy http://user:pass@proxy:8080 numpy

Permanente en ~/.pip/pip.conf (Linux) o %APPDATA%\pip\pip.ini (Windows):

[global]
proxy = http://user:pass@proxy:8080
trusted-host = pypi.org
               files.pythonhosted.org

6.5 Solución 4: Timeout

Si la descarga es lenta:

pip install --timeout 300 numpy

Permanente:

[global]
timeout = 300

6.6 «Read timed out»

Solución:

pip install --timeout 60 --retries 5 numpy

6.7 «Connection reset by peer»

Causas:

  • Firewall.
  • Proxy.
  • Antivirus.

Solución:

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org numpy

Si persiste: cambiar DNS a 1.1.1.1 o usar VPN.

6.8 Usar índice alternativo

PyPI mirror:

pip install -i https://pypi.org/simple numpy

China (más rápido desde allí):

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy

Consulta Guía Completa de Redes.


7. Problemas de versión de Python

7.1 «ModuleNotFoundError: No module named ‘X'»

Error típico después de instalar:

ModuleNotFoundError: No module named 'numpy'

Aunque instalaste con pip install numpy.

Causas:

  • Instalaste en otro Python.
  • Otro intérprete activo.
  • Conflicto de versiones.

7.2 Diagnóstico

# ¿Qué Python uso?
which python
python --version

# ¿Qué pip uso?
which pip
pip --version

# ¿Dónde está instalado numpy?
pip show numpy

Verifica que las rutas coinciden.

7.3 Solución: usar python -m pip

Siempre:

python -m pip install numpy

O con versión específica:

python3.11 -m pip install numpy

Ventaja: garantiza el pip del Python que estás usando.

7.4 Múltiples versiones de Python

Si tienes 3.10 y 3.12:

python3.10 -m pip install numpy  # Para 3.10
python3.12 -m pip install numpy  # Para 3.12

Recomendación: usa pyenv para gestionar versiones:

curl https://pyenv.run | bash
pyenv install 3.12.0
pyenv global 3.12.0

7.5 Verificar compatibilidad

python --version
pip install numpy
# Verificar que numpy soporta esta versión

Consulta: https://pypi.org/project/numpy/#supported-python-versions

7.6 pip y Python desincronizados

Si pip --version dice una versión y python --version otra:

# Reinstalar pip del Python actual
python -m ensurepip --upgrade
python -m pip install --upgrade pip

8. Problemas con paquetes específicos

8.1 NumPy

Problema: Could not build wheels for numpy.

Solución:

# Actualizar pip primero
python -m pip install --upgrade pip

# Instalar con wheel
pip install --only-binary :all: numpy

Si persiste: verifica compiladores (sección 4).

8.2 Pandas

Problema: Could not build wheels for pandas.

Solución:

# Verificar que es versión compatible
pip install --upgrade pip setuptools wheel
pip install pandas

En sistemas viejos:

pip install --only-binary :all: pandas

8.3 PyTorch

Problema: Could not find a version that satisfies torch.

Solución:

Usar el índice oficial:

# CPU
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# CUDA 12.1
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# CUDA 12.4
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

Ver: https://pytorch.org/get-started/locally/

Consulta PyTorch para CUDA 12.4.

8.4 TensorFlow

Problema: Could not find a version that satisfies tensorflow.

Solución:

# Windows: solo versiones específicas
pip install tensorflow==2.15.0

# Linux/macOS: más flexibilidad
pip install tensorflow

Ver: https://www.tensorflow.org/install

8.5 OpenCV

Problema: Could not build wheels for opencv-python.

Solución:

# Versión precompilada
pip install opencv-python-headless

# O con GUI
pip install opencv-python

8.6 psycopg2

Problema: Could not build wheels for psycopg2.

Solución:

pip install psycopg2-binary

O:

sudo apt install libpq-dev
pip install psycopg2

8.7 lxml

Problema: Could not build wheels for lxml.

Solución:

sudo apt install libxml2-dev libxslt-dev
pip install lxml

O:

pip install --only-binary :all: lxml

8.8 pillow

Problema: Could not build wheels for pillow.

Solución:

sudo apt install libjpeg-dev zlib1g-dev
pip install pillow

O:

pip install --only-binary :all: pillow

8.9 cryptography

Problema: errores de compilación con Rust.

Solución:

pip install --upgrade pip
pip install --only-binary :all: cryptography

8.10 mysqlclient

Problema: Could not build wheels for mysqlclient.

Solución:

sudo apt install default-libmysqlclient-dev
pip install mysqlclient

O:

pip install pymysql  <em># Alternativa pura Python</em>

9. Problemas de caché

9.1 Caché corrupta

Síntoma: instalación falla aunque el paquete existe.

Solución:

pip cache purge
pip install numpy

Ver caché:

pip cache list
pip cache info

9.2 Forzar descarga

pip install --no-cache-dir numpy

Ventaja: descarga fresca.

Desventaja: más lento.

9.3 «Using cached …» pero falla

Solución:

pip install --no-cache-dir --force-reinstall numpy

9.4 Caché en ubicación rara

Ver:

pip cache dir

En Linux: ~/.cache/pip/
En macOS: ~/Library/Caches/pip/
En Windows: %LocalAppData%\pip\Cache\

Borrar:

rm -rf ~/.cache/pip/

Consulta Guía Completa de Linux.


10. Problemas de entorno virtual

10.1 ¿Estoy en un entorno virtual?

Verificar:

which python
# Debería mostrar .../venv/bin/python

# O
echo $VIRTUAL_ENV

Si no hay VIRTUAL_ENV: no estás en venv.

10.2 Activar entorno virtual

Linux/macOS:

source venv/bin/activate

Windows (cmd):

venv\Scripts\activate.bat

Windows (PowerShell):

venv\Scripts\Activate.ps1

Si PowerShell falla:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

10.3 Crear entorno virtual

python3 -m venv venv

Con herramientas específicas:

# Con virtualenv
pip install virtualenv
virtualenv venv

# Con uv (más rápido)
uv venv venv

# Con Poetry
poetry new mi-proyecto

10.4 Entorno virtual corrupto

Síntoma: errores raros, pip no funciona.

Solución:

deactivate  # Si estás dentro
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip

10.5 Entorno virtual de otro Python

Síntoma:

Fatal error in launcher: Unable to create process using ...

Causa: venv creado con Python diferente.

Solución: recrear con el Python actual.

10.6 venv con –system-site-packages

Si quieres acceso al sistema:

python3 -m venv venv --system-site-packages

⚠️ Cuidado: puede causar conflictos.

10.7 pipx para aplicaciones

Para CLI tools (no librerías):

pip install pipx
pipx install black
pipx install jupyter

Ventaja: cada tool en su propio venv.

Consulta Cómo instalar JupyterLab en Ubuntu.


11. Alternativas a pip

11.1 uv (el más rápido)

Instalación:

curl -LsSf https://astral.sh/uv/install.sh | sh

Uso:

uv pip install numpy
uv pip compile requirements.in
uv pip sync requirements.txt

Ventaja: 10-100x más rápido.
Resuelve problemas de velocidad y dependencias.

Consulta Cómo actualizar todas las bibliotecas.

11.2 pip-tools

Para proyectos reproducibles:

pip install pip-tools
pip-compile requirements.in
pip-sync requirements.txt

Ventaja: resolución de dependencias.

11.3 Poetry

Gestión completa:

pip install poetry
poetry new mi-proyecto
poetry add numpy
poetry install

Ventaja: todo en uno.

11.4 Conda / Miniconda

Para ciencia de datos:

# Instalar Miniconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

# Uso
conda create -n mi-env python=3.12
conda activate mi-env
conda install numpy pandas

Ventaja: gestiona binarios complejos (CUDA, MKL).
Desventaja: más lento, más pesado.

11.5 pipx

Para aplicaciones CLI:

pipx install black
pipx install jupyter

Ventaja: aislamiento por herramienta.

11.6 Tabla comparativa

HerramientaVelocidadDependenciasIdeal para
pipMediaBásicaTodo
uvMuy rápidaCompletaProyectos modernos
pip-toolsMediaCompletaReproducibilidad
PoetryLentaCompletaLibrerías
CondaLentaCompletaData science
pipxMediaAisladaCLI tools

12. Buenas prácticas

12.1 Siempre entorno virtual

Regla de oro: nunca instales en el Python del sistema.

python3 -m venv venv
source venv/bin/activate

12.2 Actualiza pip primero

python -m pip install --upgrade pip

12.3 Usa python -m pip

python -m pip install numpy

Evita conflictos entre pip y python.

12.4 Fija versiones

requirements.txt:

numpy==1.26.4
pandas==2.2.0
requests==2.32.0

Ventaja: reproducibilidad.

12.5 Usa lock files

pip-tools:

pip-compile requirements.in

Poetry:

poetry lock

uv:

uv lock

12.6 Prueba en entorno limpio

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

Ventaja: detecta problemas de dependencias.

12.7 Documenta dependencias del sistema

README.md:

## Requisitos

### Linux (Ubuntu)
```bash
sudo apt install build-essential python3-dev libpq-dev libxml2-dev
#### 12.8 Usa Docker para reproducibilidad

```dockerfile
FROM python:3.12-slim
RUN apt-get update && apt-get install -y build-essential
COPY requirements.txt .
RUN pip install -r requirements.txt

Consulta Qué es Docker.

12.9 Alterna con uv

Si pip es lento o falla:

uv pip install -r requirements.txt

12.10 Lee el changelog

Antes de actualizar:

pip show numpy | grep Home-page
# Abrir y leer

12.11 Ten un plan B

Si todo falla:

  • Docker.
  • Conda.
  • VM dedicada.
  • Otra versión de Python.

13. FAQ

¿Por qué falla pip al instalar?

Causas comunes:

  1. Permisos (sin entorno virtual).
  2. Compilación (falta gcc/python-dev).
  3. Dependencias conflictivas.
  4. Red/SSL (proxy, firewall).
  5. Versión de Python incompatible.

¿Debo usar sudo con pip?

NO. Nunca.

Consecuencias:

  • Rompe el Python del sistema.
  • Conflictos con el gestor de paquetes.
  • Problemas futuros.

Solución: entorno virtual.

¿Qué es un entorno virtual?

Espacio aislado con sus propias librerías.

python3 -m venv venv
source venv/bin/activate
pip install numpy

Ventaja: no afecta al sistema.

¿Cómo soluciono «Permission denied»?

Opción 1 (recomendada): entorno virtual.

python3 -m venv venv
source venv/bin/activate
pip install numpy

Opción 2: --user

pip install --user numpy

Nunca: sudo pip install.

¿Cómo soluciono «Could not build wheels»?

Instalar herramientas de compilación:

Ubuntu:

sudo apt install build-essential python3-dev

Fedora:

sudo dnf install gcc gcc-c++ python3-devel

macOS:

xcode-select --install

Windows: Visual Studio Build Tools.

¿Cómo soluciono «Python.h: No such file»?

Instalar python3-dev:

sudo apt install python3-dev

¿Cómo soluciono «SSL: CERTIFICATE_VERIFY_FAILED»?

Opción 1: actualizar certifi.

pip install --upgrade certifi

Opción 2: trusted-host (temporal).

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org numpy

Opción 3: configurar proxy.

¿Cómo soluciono «Dependency resolution failed»?

Opción 1: pip-tools.

pip install pip-tools
pip-compile requirements.in
pip-sync requirements.txt

Opción 2: uv.

uv pip install numpy pandas

Opción 3: versiones compatibles.

pip install "numpy>=1.24,<1.27"

¿Cómo soluciono «No matching distribution found»?

Causas:

  • Versión no existe.
  • Incompatible con Python.
  • Sin wheel para tu SO.

Verificar:

pip index versions numpy
python --version
pip install --only-binary :all: numpy

¿Cómo instalo una versión específica?

pip install numpy==1.24.0

Rango:

pip install "numpy>=1.24,<1.26"

¿Qué es pip cache?

Almacén de paquetes descargados.

Ver:

pip cache info

Limpiar:

pip cache purge

¿Cómo uso un proxy con pip?

pip install --proxy http://user:pass@proxy:8080 numpy

Permanente en pip.conf.

¿Qué es pipx?

Instalador de aplicaciones CLI aisladas.

pipx install black

Uso: para herramientas, no librerías.

¿Qué es uv?

Alternativa ultrarápida a pip (Rust).

uv pip install numpy

10-100x más rápido.

¿Qué es pip-tools?

Resolución de dependencias + requirements.txt reproducible.

pip install pip-tools
pip-compile requirements.in
pip-sync requirements.txt

¿Qué es Poetry?

Gestor completo de dependencias y entornos.

poetry add numpy
poetry install

¿Qué es Conda?

Gestor de paquetes para data science.

conda install numpy pandas pytorch

Ventaja: binarios complejos (CUDA).

¿Cómo instalo PyTorch?

Siempre desde el índice oficial:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

Ver: https://pytorch.org/get-started/locally/

¿Cómo instalo TensorFlow?

pip install tensorflow

⚠️ Windows: solo versiones específicas (2.15.0).

Ver: https://www.tensorflow.org/install

¿Cómo instalo OpenCV?

pip install opencv-python

Sin GUI:

pip install opencv-python-headless

¿Cómo soluciono errores en Windows?

Opción 1: usar cmd.exe en lugar de PowerShell.

Opción 2: cambiar ExecutionPolicy.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Opción 3: Visual Studio Build Tools.

¿Cómo soluciono errores en macOS?

Instalar Xcode tools:

xcode-select --install

Homebrew:

brew install python

¿Qué Python debo usar?

Recomendación 2026:

  • 3.12: estable, ampliamente soportado.
  • 3.11: muy estable.
  • 3.10: estable (más antiguo).

Evita:

  • 3.13: muy nuevo, muchas librerías aún no soportan.
  • 3.8 o anterior: sin soporte.

¿Cómo sé qué Python uso?

which python
python --version

# O específico
which python3
python3 --version

¿Cómo gestiono múltiples versiones de Python?

pyenv:

curl https://pyenv.run | bash
pyenv install 3.12.0
pyenv global 3.12.0

¿Qué es un wheel?

Paquete binario precompilado (.whl).

Ventaja: no requiere compilación.

¿Qué es un sdist?

Paquete fuente (.tar.gz).

Requiere compilación al instalar.

¿Cómo forzar wheel?

pip install --only-binary :all: numpy

Falla si no hay wheel.

¿Cómo usar python -m pip?

python -m pip install numpy

Ventaja: usa el pip del Python actual.

¿Cómo soluciono «ModuleNotFoundError»?

Verificar:

which python
which pip
pip show numpy

Deben coincidir.

Solución:

python -m pip install numpy

¿Cómo instalo en un Python específico?

python3.12 -m pip install numpy

Ventaja: garantiza el intérprete.

¿Debo usar requirements.txt?

Sí, siempre.

pip freeze > requirements.txt
pip install -r requirements.txt

¿Qué es pip.conf?

Archivo de configuración de pip.

Linux/macOS: ~/.pip/pip.conf o ~/.config/pip/pip.conf.
Windows: %APPDATA%\pip\pip.ini.

Ejemplo:

[global]
timeout = 60
index-url = https://pypi.org/simple

¿Cómo instalo sin internet?

Descargar primero:

pip download numpy -d ./packages

Instalar offline:

pip install --no-index --find-links ./packages numpy

¿Qué es un mirror de PyPI?

Copia espejo de PyPI (más rápido en algunos países).

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy

Consulta Guía Completa de Redes.


14. Conclusión

pip es una herramienta poderosa, pero puede ser frustrante cuando falla. La buena noticia es que el 95% de los problemas tienen soluciones conocidas.

Puntos clave:

  1. Siempre entorno virtual.
  2. Nunca uses sudo con pip.
  3. Actualiza pip primero.
  4. Usa python -m pip.
  5. Instala herramientas de compilación.
  6. Lee los errores con cuidado.
  7. Busca en Google (ya resuelto por otros).
  8. pip-tools, Poetry o uv para proyectos serios.
  9. Docker para reproducibilidad total.
  10. Alternativas: conda, pipx, uv.

Recomendación para evitar problemas:

  1. Crea un venv.
  2. Actualiza pip.
  3. Usa python -m pip.
  4. Fija versiones.
  5. Usa lock files.
  6. Prueba en limpio.
  7. Documenta.

Cuando algo falla:

  1. Lee el error completo.
  2. Busca la palabra clave.
  3. Google + Stack Overflow.
  4. Prueba soluciones una a una.
  5. Rollback si es necesario.

Si quieres profundizar:

Deja un comentario