Tecnología · GUÍA PRÁCTICA
¿Uvicorn no puede importar el módulo? Demuestra APP, ruta de búsqueda y traceback interno
Separa el arranque en tres pruebas: si Python encuentra el módulo, si existe el atributo y si la importación termina sin otra excepción.
“Error loading ASGI app. Could not import module” no tiene una solución universal. Uvicorn analiza un objetivo como app.main:app, Python busca app.main y la ejecución de ese módulo puede lanzar otra excepción.
Antes de editar, conserva el comando exacto, el directorio, el intérprete y el primer traceback completo.
1. Congela el comando y el entorno
Registra pwd (o Get-Location), python -c "import sys; print(sys.executable)" y python -m uvicorn --version. En un contenedor o gestor, anota su directorio y comando reales.
python -m uvicorn usa el mismo intérprete. Si no puede importar uvicorn, corrige primero el entorno, no la ruta de la aplicación.
2. Analiza APP como module:attribute
En app.main:app, el módulo es app.main y el atributo es app. No añadas .py, barras ni nombres de raíz por intuición.
Si create_app es una factoría, nómbrala y usa --factory deliberadamente. Un atributo ausente no es un módulo ausente.
3. Demuestra que Python localiza el módulo
Ejecuta python -c "import importlib.util; print(importlib.util.find_spec('app.main'))" desde el mismo entorno. None significa que la ruta actual no lo localiza, no que el archivo no exista.
Python recorre sys.path y --app-dir añade una carpeta. Elige un contrato: app.main:app desde la raíz, main:app desde app, o cwd fijo con --app-dir absoluto.
4. Importa directamente para ver el traceback real
Si find_spec funciona, ejecuta python -c "import app.main". Un traceback de dependencia, sintaxis, configuración o ciclo prueba que el módulo fue localizado y falló al ejecutarse.
Añadir carpetas o renombrar main.py no corrige una dependencia ausente ni una importación circular.
5. Verifica el atributo sin iniciar el servidor
Usa python -c "import app.main as m; print(m.__file__); print(hasattr(m, 'app')); print(type(getattr(m, 'app', None)))". __file__ revela módulos homónimos y hasattr separa el atributo del módulo.
Si el objeto se llama application usa app.main:application; si es factoría usa su forma. Elimina primero cualquier módulo que oculte el archivo esperado.
6. Mantén iguales el paquete y el despliegue
El ejemplo multiarchivo de FastAPI usa un punto de entrada como app.main:app. Ejecutar main.py como script suelto e importar app.main como paquete admiten importaciones distintas.
Reproduce el comando con el cwd, Python, variables y montajes reales. Que funcione solo después de cd en una terminal no es todavía una reparación del servicio.
7. Sal con una prueba observable
Empieza sin reload ni varios workers para obtener un solo traceback. El éxito exige el archivo y atributo esperados, arranque completo y respuesta de una ruta conocida.
Si la importación directa falla, deja de cambiar opciones de Uvicorn. Si solo falla bajo el gestor, compara cwd, Python, entorno y montajes.
