zoneinfo no Python: fusos horários

Leandro Hirt

Atualizado em: 23/07/2026

Publicado em: 29/07/2026

Tempo de leitura: 8 minutos

Trabalhar com datas parece simples até uma aplicação precisar atender usuários em países diferentes, converter horários de reuniões, registrar eventos em UTC ou lidar com mudanças de horário de verão. Um deslocamento fixo como -03:00 não representa todas as regras históricas e futuras de uma região. O módulo zoneinfo no Python resolve esse problema ao conectar objetos datetime à base de fusos horários da IANA.

Neste guia, você aprenderá a criar datas conscientes de fuso, converter horários com astimezone(), tratar instantes ambíguos com fold, instalar tzdata, validar chaves, armazenar datas corretamente e evitar erros comuns. O artigo complementa nossos conteúdos sobre listas em Python, collections, descriptors, otimização de scripts Python e uso de memória.

O que é zoneinfo

zoneinfo faz parte da biblioteca padrão desde o Python 3.9. Ele implementa datetime.tzinfo usando as regras da IANA Time Zone Database. Em vez de trabalhar apenas com deslocamentos fixos, você usa chaves como America/Sao_Paulo, Europe/Lisbon, America/New_York e Asia/Tokyo.

from datetime import datetime
from zoneinfo import ZoneInfo

agora_sp = datetime.now(ZoneInfo("America/Sao_Paulo"))
print(agora_sp)
print(agora_sp.tzname())

O objeto resultante é um datetime aware, ou seja, conhece seu fuso e deslocamento em relação ao UTC. Isso permite conversões e cálculos mais seguros.

Datas ingênuas e datas conscientes

Um datetime naive não possui tzinfo. Ele pode representar um horário local, UTC ou qualquer outra referência, mas o objeto não informa qual. Esse silêncio é uma fonte comum de bugs.

from datetime import datetime

naive = datetime(2026, 7, 29, 9, 0)
print(naive.tzinfo)  # None

Já um objeto consciente associa o horário a um fuso:

from datetime import datetime
from zoneinfo import ZoneInfo

aware = datetime(
    2026, 7, 29, 9, 0,
    tzinfo=ZoneInfo("America/Sao_Paulo"),
)
print(aware.utcoffset())

Em sistemas reais, deixe explícito o significado de cada data. Misturar objetos ingênuos e conscientes pode gerar exceções, ordenações incorretas e eventos executados no momento errado.

Criando um ZoneInfo

A classe principal recebe uma chave IANA:

from zoneinfo import ZoneInfo

sao_paulo = ZoneInfo("America/Sao_Paulo")
lisboa = ZoneInfo("Europe/Lisbon")
tokyo = ZoneInfo("Asia/Tokyo")

A chave diferencia maiúsculas de minúsculas e deve corresponder a uma zona disponível. Evite abreviações como EST, CST ou BRT, pois elas podem ser ambíguas ou não carregar todas as regras necessárias.

Convertendo horários com astimezone()

Uma prática segura é representar o instante em UTC e convertê-lo apenas na borda da aplicação, conforme o fuso do usuário.

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

instante_utc = datetime(2026, 7, 29, 12, 0, tzinfo=timezone.utc)

sp = instante_utc.astimezone(ZoneInfo("America/Sao_Paulo"))
madri = instante_utc.astimezone(ZoneInfo("Europe/Madrid"))
tokyo = instante_utc.astimezone(ZoneInfo("Asia/Tokyo"))

print(sp)
print(madri)
print(tokyo)

Os três valores representam o mesmo instante. O que muda é a apresentação local, incluindo deslocamento e possíveis regras de horário de verão.

replace(tzinfo=…) não converte o instante

Um erro frequente é usar replace(tzinfo=...) para converter um horário já associado a outra zona. Esse método apenas troca ou adiciona metadados; ele não ajusta hora e minuto para preservar o instante.

horario = datetime(2026, 7, 29, 9, 0)
localizado = horario.replace(tzinfo=ZoneInfo("America/Sao_Paulo"))

Esse uso é correto apenas quando você sabe que o valor ingênuo já representa 09:00 em São Paulo. Para transformar um instante consciente entre zonas, use astimezone().

Aritmética e horário de verão

O manual oficial de zoneinfo mostra que objetos com ZoneInfo participam da aritmética de datetime e ajustam o deslocamento quando uma transição de horário de verão ocorre.

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

los_angeles = ZoneInfo("America/Los_Angeles")
antes = datetime(2020, 10, 31, 12, tzinfo=los_angeles)
depois = antes + timedelta(days=1)

print(antes, antes.tzname())
print(depois, depois.tzname())

O horário civil continua ao meio-dia, mas o deslocamento pode mudar. Essa diferença é importante: “amanhã às 12h” não é sempre o mesmo que “daqui a exatamente 24 horas” em regiões com transições.

Horários ambíguos e o atributo fold

Quando o relógio volta uma hora, um mesmo horário local pode acontecer duas vezes. Para distinguir as duas ocorrências, datetime usa o atributo fold. O valor padrão 0 escolhe o deslocamento anterior à transição; 1 seleciona o posterior.

from datetime import datetime
from zoneinfo import ZoneInfo

zona = ZoneInfo("America/Los_Angeles")
primeira = datetime(2020, 11, 1, 1, 30, tzinfo=zona, fold=0)
segunda = primeira.replace(fold=1)

print(primeira, primeira.utcoffset())
print(segunda, segunda.utcoffset())

Ao converter um instante UTC com astimezone(), o Python define fold corretamente. O cuidado maior aparece quando o usuário fornece diretamente uma data local durante uma faixa ambígua.

Horários inexistentes

Na transição oposta, o relógio avança e alguns horários locais nunca acontecem. Por exemplo, uma região pode saltar de 01:59 para 03:00. Construir diretamente um datetime com 02:30 não garante validação automática de inexistência.

Para agendas críticas, valide datas locais com uma estratégia de ida e volta: associe a zona, converta para UTC, converta novamente para a zona original e compare os componentes. Outra opção é pedir ao usuário um instante absoluto ou oferecer uma regra explícita para mover o evento ao próximo horário válido.

UTC como formato interno

Uma arquitetura robusta costuma armazenar instantes em UTC e guardar separadamente a chave do fuso quando a intenção local também importa.

evento = {
    "inicio_utc": "2026-07-29T12:00:00Z",
    "timezone": "America/Sao_Paulo",
}

Guardar apenas “09:00” perde o instante. Guardar apenas UTC pode perder a intenção de calendário. Em uma reunião recorrente, por exemplo, o usuário talvez queira sempre 09:00 local, mesmo quando o deslocamento muda. Por isso, o modelo deve distinguir um instante único de uma regra civil recorrente.

Serialização em ISO 8601

datetime.isoformat() inclui o deslocamento atual, mas não preserva necessariamente a chave IANA.

texto = agora_sp.isoformat()
print(texto)

O deslocamento -03:00 sozinho não informa todas as regras de America/Sao_Paulo. Quando futuras conversões dependem da zona original, armazene também a chave.

De onde vêm os dados de fuso

O módulo não incorpora toda a base IANA dentro do código do Python. Primeiro, ele procura os arquivos de zona disponíveis no sistema por meio de TZPATH. Se não encontrar, tenta usar o pacote oficial tzdata instalado pelo projeto.

Em muitos sistemas Unix, os dados já existem. No Windows, normalmente é prudente declarar a dependência:

python -m pip install tzdata

Para aplicações multiplataforma, incluir tzdata reduz diferenças entre ambientes de desenvolvimento, testes e produção.

Tratando ZoneInfoNotFoundError

Uma chave inválida ou a ausência da base gera ZoneInfoNotFoundError, subclasse de KeyError.

from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

try:
    zona = ZoneInfo("America/Cidade_Inexistente")
except ZoneInfoNotFoundError:
    print("Fuso horário não disponível")

Não aceite qualquer texto do usuário sem validação. Prefira uma lista controlada de zonas suportadas pela aplicação e registre erros de configuração separadamente de erros de entrada.

Listando fusos disponíveis

available_timezones() retorna as chaves canônicas encontradas nas fontes disponíveis.

from zoneinfo import available_timezones

zonas = available_timezones()
print("America/Sao_Paulo" in zonas)

A função pode abrir muitos arquivos e recalcula o conjunto a cada chamada. Evite executá-la repetidamente em requisições. Além disso, chaves IANA são identificadores técnicos, não rótulos amigáveis. Para interfaces, associe-as a nomes traduzidos e cidades compreensíveis.

Cache de ZoneInfo

O construtor principal mantém cache. Chamadas repetidas com a mesma chave normalmente retornam a mesma instância:

a = ZoneInfo("Europe/Paris")
b = ZoneInfo("Europe/Paris")
print(a is b)  # True

Isso reduz custo e estabiliza a identidade dos objetos. ZoneInfo.no_cache() e ZoneInfo.clear_cache() existem, mas podem alterar a semântica de datas já criadas. Use essas APIs principalmente em testes muito específicos.

Testando código com fusos horários

Inclua casos próximos às transições, não apenas datas comuns. Teste conversões UTC-local, local-UTC, datas ambíguas, datas inexistentes, chaves inválidas e ambientes sem dados de zona.

def converter_para_usuario(instante_utc, chave):
    if instante_utc.tzinfo is None:
        raise ValueError("O instante deve ser consciente")
    return instante_utc.astimezone(ZoneInfo(chave))

Em testes, use instantes fixos. Evite depender diretamente de datetime.now(), pois o resultado varia com o relógio e torna falhas difíceis de reproduzir.

Agendamentos recorrentes

Há duas interpretações comuns. Uma tarefa pode ocorrer a cada 24 horas exatas ou todos os dias às 09:00 no fuso do usuário. Em regiões com horário de verão, essas regras produzem resultados diferentes.

Para recorrência civil, armazene data local, hora local e chave IANA; calcule cada próxima ocorrência usando a regra atualizada. Para intervalos absolutos, trabalhe em UTC com timedelta. Documente a intenção no modelo e nos nomes das funções.

Uso em APIs e bancos de dados

Ao receber uma data de API, exija deslocamento ou uma chave de zona separada. Rejeite valores ambíguos. No banco, escolha tipos que preservem o instante e normalize consultas para UTC. Ao exibir, converta para o fuso selecionado pelo usuário.

Também defina quem controla atualizações da base IANA. Governos podem mudar regras, e uma versão nova de tzdata pode alterar ocorrências futuras. Atualize dependências, execute testes e registre a versão usada em processos regulados.

Erros frequentes

Usar abreviações ambíguas em vez de chaves IANA.
Confundir replace(tzinfo=...) com conversão.
Comparar uma data ingênua com uma consciente.
Armazenar apenas o deslocamento e perder a zona original.
Somar 24 horas quando a regra é “mesmo horário local amanhã”.
Ignorar fold em horários repetidos.
Confiar que toda máquina possui a base IANA.
Chamar available_timezones() em cada requisição.

Boas práticas

Use UTC para instantes internos e chaves IANA para apresentação e recorrência.
Declare tzdata em aplicações multiplataforma.
Converta com astimezone().
Valide zonas permitidas.
Teste transições e casos ambíguos.
Armazene a intenção local quando necessário.
Atualize periodicamente os dados de fuso.
Leia também a documentação oficial de datetime.

Conclusão

O módulo zoneinfo no Python permite representar fusos horários reais sem bibliotecas externas para a lógica principal. Ele integra a base IANA ao datetime, aplica transições históricas, converte instantes com segurança e oferece suporte a horários repetidos por meio de fold.

O ponto central é modelar a intenção corretamente. Instantes únicos devem ser normalizados em UTC; compromissos ligados ao relógio local precisam preservar a chave IANA. Com validação, tzdata, testes de transição e uso correto de astimezone(), sua aplicação evita reuniões deslocadas, tarefas executadas fora de hora e dados impossíveis de interpretar.

Compartilhe: