Skip to content
ProgramaciónPro

Python: pip instala pero el import falla — diagnóstico paso a paso

19 noviembre, 2026

Si pip dice que un paquete está instalado pero tu programa termina con ModuleNotFoundError, compara primero el Python que ejecuta el archivo con el Python asociado a la instalación. Reinstalar varias veces sin mirar las rutas puede repetir el mismo problema.

Esta práctica permite distinguir tres situaciones: el módulo no está en la ruta de búsqueda, el programa usa otro entorno o un archivo de tu proyecto está ocupando el nombre que esperabas importar. Incluye un diagnóstico que no instala paquetes ni cambia la configuración del equipo.

1. Copia el nombre que realmente falta

Lee la última línea del error y guarda también la línea de tu programa que hace el import. Si aparece No module named 'requests', el nombre de importación que vas a comprobar es requests. Si falta un submódulo, conserva el mensaje completo: esta práctica comprueba únicamente nombres principales, sin puntos.

Un nombre de distribución de pip y un nombre de importación pueden ser diferentes. Por ejemplo, no deduzcas el nombre que debes instalar cambiando signos al azar: compruébalo en la documentación oficial del proyecto. Tampoco instales automáticamente todo nombre que aparezca en un error de un programa desconocido.

2. Comprueba las dos rutas antes de instalar

En la misma terminal desde la que ejecutas el programa, usa el comando de Python que ya utilizas para ese proyecto. Si es python:

python -c "import sys; print(sys.executable); print(sys.version.split()[0])"
python -m pip --version
python -m pip show requests

En macOS o Linux puede ser python3; en ese caso sustituye python por python3 en las tres líneas. requests es solo un ejemplo: utiliza el nombre de distribución que indique el proyecto. pip show consulta información; no instala.

Compara el ejecutable y la ubicación mostrada por pip con el entorno que querías usar. Que dos ejecutables tengan la misma versión no los convierte en el mismo entorno. La documentación de Python explica el uso de pip mediante el intérprete elegido.

Si ejecutas desde un editor o un cuaderno, escribe también dentro de ese entorno import sys; print(sys.executable). La terminal integrada y el botón Ejecutar pueden utilizar intérpretes distintos. Conserva las rutas localmente: pueden contener tu nombre de usuario; no necesitas publicarlas para completar el diagnóstico.

3. Ejecuta este diagnóstico sin instalar nada

Guarda el siguiente archivo con el nombre exacto diagnostico_import.py en una carpeta de práctica. No lo llames sys.py, re.py, pathlib.py ni importlib.py, porque son nombres utilizados por el propio ejercicio.

import importlib.util
from pathlib import Path
import re
import sys

if len(sys.argv) != 2 or not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", sys.argv[1]):
    print("Uso: diagnostico_import.py nombre_modulo (sin puntos)")
    raise SystemExit(2)

nombre = sys.argv[1]
print("Python:", sys.executable)
print("Version:", sys.version.split()[0])
print("Entorno virtual:", sys.prefix != sys.base_prefix)
spec = importlib.util.find_spec(nombre)
if spec is None:
    print("Resultado: NO_LOCALIZADO")
    raise SystemExit(1)

origen = spec.origin
print("Origen:", origen)
if origen in ("built-in", "frozen"):
    print("Resultado: MODULO_DEL_INTERPRETE")
elif origen is None:
    print("Resultado: PAQUETE_SIN_ARCHIVO_UNICO")
else:
    carpeta_script = Path(__file__).resolve().parent
    archivo = Path(origen).resolve()
    if archivo.parent == carpeta_script:
        print("Resultado: ARCHIVO_JUNTO_AL_SCRIPT; revisa si oculta otro paquete")
    else:
        print("Resultado: LOCALIZADO; esto no demuestra que importarlo funcione")

Ejecuta python diagnostico_import.py requests con el mismo intérprete del paso anterior. El script usa find_spec para localizar el nombre; no importa deliberadamente el módulo objetivo. Encontrarlo no certifica que cargue bien: aún puede fallar una dependencia o una biblioteca nativa. No es una herramienta para ejecutar proyectos desconocidos.

ResultadoQué revisar
NO_LOCALIZADOEl nombre no se localizó desde ese intérprete. Confirma nombre, entorno y dependencias declaradas.
ARCHIVO_JUNTO_AL_SCRIPTRevisa si es tu módulo intencional o un archivo que oculta el paquete buscado. No borres archivos por recibir este aviso.
LOCALIZADOCompara la ruta con la esperada. Después prueba el import real de tu proyecto de confianza.
MODULO_DEL_INTERPRETEEs un módulo incorporado o congelado. No necesitas buscar un paquete de pip con ese nombre.
PAQUETE_SIN_ARCHIVO_UNICOPuede ser un paquete de espacio de nombres. No significa ausencia ni corrupción por sí solo.

4. Prueba controlada: un módulo presente y otro ausente

Junto al diagnóstico crea saludo_demo.py con una sola línea:

MENSAJE = "Hola desde el ejercicio"

Ejecuta python diagnostico_import.py saludo_demo. Debe localizar el archivo junto al script y mostrar el aviso para revisarlo. Aquí sabemos que es intencional: acabas de crearlo. A continuación, python diagnostico_import.py modulo_webs_ausente_20261118 debe indicar NO_LOCALIZADO si no existe un módulo con ese nombre en tu entorno.

Por último ejecuta python -c "import saludo_demo; print(saludo_demo.MENSAJE)" desde esa carpeta. Debe mostrar Hola desde el ejercicio. Es una prueba de localización e importación de un archivo propio, no una simulación de instalación con pip.

5. Si necesitas un entorno aislado

Crea una carpeta nueva para la práctica y, dentro, un entorno con python -m venv .venv o python3 -m venv .venv, según el comando disponible. No reutilices una carpeta .venv que contenga archivos importantes.

Puedes invocar su intérprete directamente, sin activar el entorno ni cambiar políticas de PowerShell:

# Windows PowerShell, desde la carpeta del proyecto
.\.venv\Scripts\python.exe diagnostico_import.py requests
.\.venv\Scripts\python.exe -m pip --version

# macOS o Linux
./.venv/bin/python diagnostico_import.py requests
./.venv/bin/python -m pip --version

Si necesitas instalar dependencias, utiliza las instrucciones o el archivo de requisitos de un proyecto de confianza con ese mismo ejecutable. No uses privilegios de administrador, sudo pip ni desactives protecciones para resolver una simple discrepancia de entorno. La guía oficial de venv explica el aislamiento y las rutas de cada plataforma.

Qué se comprobó y qué queda por comprobar en tu equipo

El diagnóstico y el ejercicio local se probaron en macOS ARM64 con Python 3.15.2: nombre ausente, módulo incorporado, archivo junto al script, paquete de espacio de nombres y módulo ubicado en site-packages de un entorno diferente. No se probaron aquí las interfaces de Windows, un editor concreto ni la instalación de paquetes externos. Las rutas de Windows siguen la documentación de Python.

Da el problema por resuelto cuando el programa de confianza se ejecute con el intérprete previsto y el import real funcione. Que desaparezca una advertencia de pip no es esa comprobación. Si apenas empiezas con el lenguaje, puedes volver a la introducción a Python; este ejercicio se ocupa de diagnosticar el entorno, sin repetir sus conceptos generales.

Fuentes adicionales: sys.executable y prefijos y distribución frente a paquete importable. Documentación revisada el 18 de noviembre de 2026. Los nombres de demostración son sintéticos.