Cómo solucionar el error ModuleNotFoundError en Python dentro de Virtualenv

El error ModuleNotFoundError: No module named 'nombre_modulo' es una de las excepciones más comunes en Python. Ocurre cuando el intérprete intenta importar una librería externa o módulo interno que no está presente en la ruta de búsqueda de paquetes (sys.path) de la instancia activa de Python.

La Solución Paso a Paso

1. 1

   Paso 1: Confirmar la activación del entorno virtual

   Comprueba si tu entorno virtual está activo y verifica cuál intérprete de Python se está ejecutando:

   BASH Copiar

   # En Linux / macOS: activar entorno virtual
   source venv/bin/activate
   
   # En Windows (PowerShell):
   .\venv\Scripts\Activate.ps1
   
   # Verificar qué intérprete está respondiendo
   which python    # En Linux/macOS
   where python    # En Windows
   

   (La salida debe apuntar a la ruta interna de tu carpeta venv/bin/python, no a /usr/bin/python).

2. 2

   Paso 2: Instalar la dependencia usando la sintaxis del módulo pip

   Para garantizar que los paquetes se instalen dentro del entorno virtual correspondiente y no en el sistema global, instala siempre usando python -m pip:

   BASH Copiar

   python -m pip install nombre_modulo
   

   Para verificar que la librería se instaló correctamente en el entorno activo:

   BASH Copiar

   python -m pip list
   

3. 3

   Paso 3: Configurar el intérprete de Python en tu IDE (VS Code / PyCharm)

   Si el script funciona desde la consola pero falla dentro de tu editor de código:

   • VS Code: Presiona Ctrl + Shift + P (o Cmd + Shift + P en Mac), escribe Python: Select Interpreter y selecciona el binario localizado dentro de la carpeta venv/bin/python.
   • PyCharm: Ve a Settings > Project > Python Interpreter y selecciona el entorno virtual creado en el proyecto.