Tecnología · GUÍA PRÁCTICA
¿Python no encuentra la zona horaria? Distinga los datos ausentes de una clave incorrecta
Compare una clave de control con la zona necesaria en el intérprete que falla y verifique los datos del despliegue en un proceso nuevo.
Que una excepción mencione UTC no significa que deba sustituir UTC. Primero compruebe si el proceso puede acceder a los datos horarios y si existe la clave solicitada.
1. Conserve el entorno que falla y la clave prevista
Guarde el traceback completo y la clave exacta, incluidas mayúsculas y barras bajas. Ejecute el diagnóstico mediante el mismo ejecutable, cuenta de servicio, contenedor o entorno virtual. Registre sys.executable, sys.version, zoneinfo.TZPATH y os.environ.get('PYTHONTZPATH'). Que funcione en otra consola es una comparación, no una prueba de reparación.
Compruebe también importlib.util.find_spec('tzdata') en ese entorno. Un paquete visible para un intérprete puede faltar en otro. No cambie la zona del negocio, desactive su soporte ni sustituya reglas regionales por un desplazamiento fijo solo para arrancar.
2. Compare el control con la clave necesaria
En un proceso nuevo pruebe ZoneInfo('UTC') y después la clave exacta requerida. Si ambas fallan, investigue primero la disponibilidad de datos. Si UTC funciona y la otra no, revise la escritura, el conjunto desplegado y si contiene esa clave. Es una bifurcación diagnóstica, no una explicación universal de los fallos con UTC.
Use una clave IANA verificada, como America/New_York si esa es la región prevista. En nuestra prueba aislada, America/NewYork y UTC+8 fallaron incluso con tzdata disponible. Copiar otra ciudad que funcione puede cambiar desplazamientos históricos o el horario de verano.
3. Demuestre qué fuente de datos usa el despliegue
zoneinfo busca en los directorios configurados del sistema y después en el paquete Python tzdata. Windows suele necesitar el paquete; una imagen Linux mínima también puede carecer de archivos del sistema. Decida qué dependencia aportará los datos e inclúyala en una compilación reproducible de la aplicación o imagen.
Si usa el paquete, invoque el instalador autorizado con el intérprete real: por ejemplo, ese ejecutable Python seguido de -m pip install tzdata. Declare además la dependencia en el manifiesto normal. En entornos administrados, cambie la configuración de construcción en lugar de usar sudo o indicadores de evasión. Si usa datos del sistema, su responsable debe provisionar el conjunto compatible.
4. Compare procesos aislados, sin alterar la caché activa
Ejecutamos cuatro casos en CPython 3.12.14 sobre Linux. Sin paquetes site pero con rutas del sistema, UTC y America/New_York funcionaron. Al vaciar también PYTHONTZPATH, ambos fallaron. Con site normal y PYTHONTZPATH vacío, ambos funcionaron mediante el paquete disponible. Una ruta relativa produjo InvalidTZPathWarning y no dejó una ruta de sistema utilizable en esa prueba.
No tener el paquete y no encontrar datos son observaciones distintas. No se probó Windows localmente. Use la ruta vacía solo como comparación controlada del mecanismo alternativo; no la despliegue sin decidir la política de versiones. reset_tzpath no elimina los objetos ZoneInfo existentes: valide en un proceso nuevo en vez de vaciar la caché de un servicio activo.
5. Verifique el lanzamiento real y las estaciones
Reinicie con el lanzador original después de la reparación mínima. Cargue la misma clave, ejecute la operación que fallaba y guarde el resultado. Para una región, contraste fechas representativas de invierno y verano con las reglas esperadas. En la prueba basada solo en el paquete, Nueva York dio UTC−05:00 el 15 de enero de 2026 y UTC−04:00 el 15 de julio. No es una prueba histórica completa.
Registre ejecutable, imagen o entorno, dependencia elegida, clave exacta y resultados anteriores y posteriores. Si funciona en una consola nueva pero falla como servicio, recopile el mismo registro dentro del servicio. Si hay datos conocidos y la clave sigue fallando, examine nombre y versión: deje de adivinar ciudades o reinstalar en entornos ajenos.
