Hora Unix para data — converter qualquer epoch numa data legível

A hora Unix para data numa linha

Aqui está a tarefa toda num exemplo: o timestamp Unix 1700000000 torna-se 2023-11-14T22:13:20Z — terça-feira, 14 de novembro de 2023, às 22:13:20 UTC. Um timestamp Unix conta os segundos desde 1 de janeiro de 1970 UTC; convertê-lo consiste em decodificar essa contagem como UTC e formatá-la no fuso horário pretendido. A única coisa que estraga as conversões é a unidade: 10 dígitos são segundos, 13 milissegundos, 16 microssegundos. A tabela abaixo é a instrução pronta a copiar para cada linguagem e ferramenta deste guia.

• Abrir o conversor de timestamp Unix
• No sentido inverso — data para timestamp Unix

O que significa converter a hora Unix numa data

Um timestamp Unix é o número de segundos desde 1 de janeiro de 1970 UTC. Para convertê-lo numa data, decodifica-se como UTC e depois formata-se em qualquer fuso horário. É esse o problema todo numa frase — o resto deste guia é apenas a sintaxe em cada linguagem. Todas as linguagens de programação modernas trazem uma função integrada que recebe um valor epoch Unix e devolve um objeto data; a única coisa a vigiar é se a linguagem espera segundos (Python, PHP, Linux date), milissegundos (JavaScript Date) ou microssegundos (PostgreSQL, BigQuery).

A regra rápida de conversão

Conte os dígitos do seu valor. Um número de 10 dígitos está em segundos Unix. Um número de 13 dígitos está em milissegundos Unix. Um número de 16 dígitos está em microssegundos Unix. A epoch Unix começou a 1 de janeiro de 1970 — por isso os valores de 10 dígitos hoje (em 2026) começam por 17 ou 18; os milissegundos começam por 175 ou 176 seguidos de 10 dígitos; os microssegundos começam por 1758 ou 1759. Detete a unidade antes de passar o valor a uma função de conversão, e a sua saída cairá no dia certo em vez de 1970.

• 10 dígitos → segundos Unix (intervalo 2001 a 2286)
• 13 dígitos → milissegundos Unix (intervalo 2001 a 2286)
• 16 dígitos → microssegundos Unix (intervalo 2001 a 2286)
• Números próximos de 10^9 (1.000.000.000) são segundos anteriores a 2001 — continuam a ser hora Unix válida
• Inteiros negativos são datas anteriores a 1970 — a maioria das linguagens lida com eles; verifique
• Números acima de 2^31 em colunas INT atingem o limite do ano 2038 — ver abaixo

• Milissegundos vs segundos — o guia completo das unidades

Converter a hora Unix numa data em JavaScript

O construtor Date do JavaScript espera milissegundos, por isso um valor em segundos Unix deve ser multiplicado primeiro por 1000. O resultado é um objeto Date; formate-o com toISOString() para ISO 8601 em UTC, ou com Intl.DateTimeFormat para uma cadeia legível com fuso horário. Passe sempre uma opção timeZone explícita — sem ela, o JavaScript usa o fuso horário local do ambiente, que difere entre os portáteis de desenvolvimento e os servidores de produção.

• new Date(1700000000 * 1000).toISOString() // '2023-11-14T22:13:20.000Z'
• new Date(1700000000 * 1000).toLocaleString('en-US', { timeZone: 'America/New_York' }) // tz-aware
• new Date(1700000000000).toISOString() // milliseconds — no × 1000 needed
• new Intl.DateTimeFormat('en-US', { timeZone: 'Asia/Tokyo', dateStyle: 'full', timeStyle: 'long' }).format(new Date(ms))
• Detect unit at runtime: const toDate = ts => new Date(ts < 1e11 ? ts * 1000 : ts)

• MDN — construtor Date()
• Formatação de datas correta por fuso horário em JavaScript (guia complementar)

Converter a hora Unix numa data em Python

datetime.fromtimestamp(ts, tz=timezone.utc) é a conversão canónica em Python. O argumento tz é obrigatório para um resultado em UTC; sem ele, o Python devolve o timestamp no fuso horário local do sistema — uma fonte frequente de bugs de desvio de fuso em servidores. utcfromtimestamp() está obsoleto desde o Python 3.12 porque devolvia um datetime ingénuo, fácil de usar mal. Para milissegundos, divida por 1000; para microssegundos, por 1.000.000 — o Python aceita frações de segundo diretamente.

• from datetime import datetime, timezone
• datetime.fromtimestamp(1700000000, tz=timezone.utc) # 2023-11-14 22:13:20+00:00
• datetime.fromtimestamp(1700000000.123, tz=timezone.utc) # fractional seconds work
• datetime.fromtimestamp(ms / 1000, tz=timezone.utc) # from milliseconds
• datetime.fromtimestamp(us / 1_000_000, tz=timezone.utc) # from microseconds
• Avoid: datetime.utcfromtimestamp(ts) — deprecated in 3.12; returns naive datetime

• Python — datetime.fromtimestamp

Converter a hora Unix numa data em PHP

gmdate(format, timestamp) em PHP devolve uma cadeia de data em UTC para os segundos Unix dados; date(format, timestamp) devolve o mesmo instante no fuso horário local do servidor (controlado por date_default_timezone_set ou php.ini). A classe DateTime com DateTimeZone oferece a API moderna e imutável e suporta qualquer nome de fuso IANA. O PHP trabalha em segundos por omissão, por isso divida primeiro os valores em milissegundos por 1000.

• gmdate('c', 1700000000) // '2023-11-14T22:13:20+00:00' (UTC ISO 8601)
• date('Y-m-d H:i:s', 1700000000) // server-local — depends on date.timezone setting
• new DateTime('@1700000000') // immutable, UTC by default with the @ prefix
• (new DateTime('@1700000000'))->setTimezone(new DateTimeZone('Asia/Tokyo'))->format('c')
• DateTime::createFromFormat('U.u', '1700000000.123456') // sub-second precision

• PHP — referência de gmdate()

Converter a hora Unix numa data em Java

A API java.time do Java (Java 8+) converte segundos Unix com Instant.ofEpochSecond(s), que devolve um instante UTC — Instant está sempre em UTC, por isso não há surpresa oculta com o fuso local. Use Instant.ofEpochMilli(ms) para entrada em milissegundos, anexe um fuso com atZone(ZoneId.of(...)) para uma representação de relógio de parede, e formate com DateTimeFormatter. O construtor herdado java.util.Date espera milissegundos, como o JavaScript — multiplique primeiro os segundos por 1000L.

• Instant.ofEpochSecond(1700000000) // 2023-11-14T22:13:20Z (UTC)
• Instant.ofEpochMilli(1700000000000L) // from milliseconds
• Instant.ofEpochSecond(1700000000).atZone(ZoneId.of("Asia/Tokyo")) // tz-aware
• DateTimeFormatter.ISO_INSTANT.format(Instant.ofEpochSecond(s)) // ISO 8601
• new java.util.Date(1700000000L * 1000) // legacy API — expects milliseconds

• Timestamps Unix em Java — referência completa

Converter a hora Unix numa data em C# (.NET)

Em .NET, DateTimeOffset.FromUnixTimeSeconds(s) é a conversão moderna — devolve um DateTimeOffset ancorado em UTC (+00:00). Use FromUnixTimeMilliseconds(ms) para entrada em milissegundos. Leia .UtcDateTime para um DateTime em UTC, ou converta para um fuso específico com TimeZoneInfo.ConvertTime. Formate com o especificador de ida e volta "o" para ISO 8601. Os métodos Unix integrados (adicionados no .NET 4.6) tratam do cálculo da epoch, por isso evite o antigo padrão DateTime.AddSeconds-desde-1970.

• DateTimeOffset.FromUnixTimeSeconds(1700000000) // 2023-11-14 22:13:20 +00:00
• DateTimeOffset.FromUnixTimeMilliseconds(1700000000000) // from milliseconds
• DateTimeOffset.FromUnixTimeSeconds(s).UtcDateTime // DateTime in UTC
• TimeZoneInfo.ConvertTime(dto, tzInfo) // tz-aware rendering
• DateTimeOffset.FromUnixTimeSeconds(s).ToString("o") // ISO 8601 round-trip

• Timestamps Unix em C# — referência completa

Converter a hora Unix numa data em Go

time.Unix(sec, nsec) em Go constrói um Time a partir de segundos Unix (mais nanossegundos opcionais), mas devolve o valor no fuso horário local — chame .UTC() para ancorá-lo. O Go 1.17 adicionou time.UnixMilli(ms) e time.UnixMicro(us), por isso já não divide à mão. Formate com a constante RFC3339 para ISO 8601, e use .In(loc) com time.LoadLocation para um fuso específico.

• time.Unix(1700000000, 0).UTC() // 2023-11-14 22:13:20 +0000 UTC
• time.UnixMilli(1700000000000).UTC() // from milliseconds (Go 1.17+)
• time.UnixMicro(1700000000000000).UTC() // from microseconds (Go 1.17+)
• time.Unix(1700000000, 0).Format(time.RFC3339) // ISO 8601 string
• time.Unix(s, 0).In(loc) // tz-aware; loc from time.LoadLocation

• Timestamps Unix em Go — referência completa

Converter a hora Unix numa data no shell (Linux / macOS)

No Linux, o comando GNU date usa -d @ts para converter a partir de segundos Unix; no macOS, o comando BSD date usa -r ts para a mesma tarefa. As flags diferem consoante a implementação histórica — o cálculo da epoch em si é idêntico. A flag -u força uma saída em UTC independentemente da variável de ambiente TZ. Ambas as implementações suportam formatos de saída arbitrários através do argumento +%FORMAT; as cadeias de formato mais úteis estão resumidas abaixo.

• GNU (Linux): date -u -d @1700000000 // 'Tue Nov 14 22:13:20 UTC 2023'
• GNU: date -u -d @1700000000 +'%Y-%m-%dT%H:%M:%SZ' // ISO 8601 UTC
• BSD (macOS): date -u -r 1700000000 // same result, different flag
• BSD: date -u -r 1700000000 +'%Y-%m-%dT%H:%M:%SZ'
• Both: omit -u to use TZ environment variable; export TZ=America/New_York to override
• Sub-second: date -u -d @1700000000.123 +'%Y-%m-%dT%H:%M:%S.%3NZ' (GNU only)

• man date(1) — referência do comando date do Linux

Converter a hora Unix numa data em SQL (Postgres, MySQL, SQLite, BigQuery)

Cada grande dialeto SQL tem uma função integrada para converter segundos Unix (ou milissegundos, ou microssegundos) numa coluna timestamp nativa. Os nomes das funções variam, mas a unidade que cada uma espera está documentada e é consistente dentro de uma base de dados. Use a função dedicada em vez de calcular o resultado à mão com aritmética de datas — as funções integradas tratam corretamente dos anos bissextos, da precisão inferior ao segundo e da conversão de fuso horário.

• PostgreSQL: TO_TIMESTAMP(1700000000) // returns TIMESTAMPTZ
• PostgreSQL: TO_TIMESTAMP(unix_us / 1000000.0) // for microsecond input
• MySQL: FROM_UNIXTIME(1700000000) // returns DATETIME in session timezone
• MySQL: CONVERT_TZ(FROM_UNIXTIME(ts), @@session.time_zone, 'UTC') // force UTC
• SQLite: datetime(1700000000, 'unixepoch') // returns TEXT 'YYYY-MM-DD HH:MM:SS'
• SQLite: datetime(ms / 1000, 'unixepoch') // from milliseconds
• BigQuery: TIMESTAMP_SECONDS(1700000000), TIMESTAMP_MILLIS(ms), TIMESTAMP_MICROS(us)
• ClickHouse: toDateTime(1700000000), fromUnixTimestamp(1700000000)

• PostgreSQL — funções de formatação de tipos de dados
• Como armazenar timestamps Unix numa base de dados (guia complementar)

Converter a hora Unix numa data no Excel

O Excel armazena as datas como números de série — o número de dias desde 1 de janeiro de 1900. Converter um timestamp Unix numa data do Excel é apenas conversão de unidade: divida os segundos Unix por 86.400 (segundos por dia) e some a data de 1 de janeiro de 1970, depois formate a célula como data. A fórmula =A1/86400 + DATE(1970,1,1) é a resposta canónica e funciona em todas as versões modernas do Excel. Para milissegundos, divida por 86.400.000. Depois de introduzir a fórmula, selecione a célula, abra Formatar células (Ctrl+1) e escolha um formato de data no separador Número.

• Seconds: =A1/86400 + DATE(1970,1,1) // when A1 holds the Unix seconds value
• Milliseconds: =A1/86400000 + DATE(1970,1,1)
• Microseconds: =A1/86400000000 + DATE(1970,1,1)
• Format cell as Date after entering the formula (Ctrl+1 → Number → Date)
• Caveat: Excel's epoch is 1900-01-01, not 1970, hence the + DATE(1970,1,1) offset
• Reverse direction (date to Unix): =(A1 - DATE(1970,1,1)) * 86400

• Microsoft — função DATE

Converter a hora Unix numa data no Google Sheets

O Google Sheets aceita a mesma fórmula canónica do Excel e oferece ainda uma função EPOCHTODATE dedicada. A forma curta é =EPOCHTODATE(A1, 1), onde o segundo argumento é o código de unidade: 1 para segundos, 2 para milissegundos, 3 para microssegundos. A saída é uma data ancorada em UTC que o Sheets apresenta conforme as definições regionais da folha. Para folhas partilhadas entre equipas em fusos diferentes, documente no cabeçalho da coluna que fuso as datas devem representar.

• =EPOCHTODATE(A1, 1) // seconds — shorthand
• =EPOCHTODATE(A1, 2) // milliseconds
• =EPOCHTODATE(A1, 3) // microseconds
• =A1/86400 + DATE(1970,1,1) // canonical formula — works in Sheets too
• Reverse direction: =(A1 - DATE(1970,1,1)) * 86400
• Time zone applied is the sheet's locale; check File → Settings → Time zone

Data UTC vs data local — qual mostrar

Um timestamp Unix codifica um instante, não uma representação de relógio de parede. Dois visitantes em fusos diferentes veem o mesmo timestamp Unix como datas de relógio diferentes. O comportamento correto depende do que a data representa: os registos de eventos e os registos de auditoria devem ser mostrados em UTC para uma comparação entre regiões; as datas orientadas ao utilizador (prazos, horários de reunião, avisos de expiração) devem ser mostradas no fuso local do utilizador. Escolha sempre um e documente-o; nunca armazene uma cadeia já convertida para hora local sem armazenar também o fuso de onde veio.

• Registos de servidor → mostrar em UTC, rotular explicitamente a coluna ou o eixo do gráfico
• Prazos orientados ao utilizador → mostrar no fuso do utilizador (detetar automaticamente com Intl.DateTimeFormat().resolvedOptions().timeZone)
• Agendamentos recorrentes ('toda segunda 9h Eastern') → armazenar o fuso junto à regra, recalcular o próximo instante a cada disparo
• Respostas de API → ISO 8601 com sufixo Z (UTC) é o valor por omissão seguro; deixe o cliente converter
• Armazenamento em base de dados → sempre UTC; converter apenas na camada de apresentação

• Base de dados de fusos horários IANA (as regras que cada runtime usa)
• ISO 8601 — o formato de data para a saída

Casos limite: precisão inferior ao segundo, timestamps negativos e o ano 2038

Três casos limite fazem tropeçar código de resto correto. Os timestamps em microssegundos (16 dígitos) precisam de tratamento explícito da unidade; tratá-los como segundos dá uma data 1.000.000× demasiado longe no futuro. Os timestamps Unix negativos representam datas anteriores a 1970 — a maioria das linguagens lida com eles, mas o Excel, o Google Sheets e algumas funções SQL limitam-nos a 1970 ou devolvem erros. O problema do ano 2038 é o overflow do inteiro com sinal de 32 bits que ocorre a 19/01/2038 às 03:14:07 UTC; os valores posteriores exigem armazenamento BIGINT ou time_t de 64 bits.

• Microssegundos (16 dígitos) — dividir por 1.000.000 antes de passar às funções de segundos da linguagem
• Segundos negativos — datas anteriores a 1970; JavaScript Date, Python datetime e PHP DateTime lidam com todos
• Segundos negativos no Excel — produzem #### ou uma data errada; use a fórmula =A1/86400 + DATE(1970,1,1) apenas para valores positivos
• Ano 2038 — INT e time_t com sinal de 32 bits transbordam em 2147483647 = 2038-01-19 03:14:07 UTC
• Para além de 2038 — armazenar como BIGINT (o 64 bits com sinal cobre 292 mil milhões de anos de cada lado da epoch)
• Antes de 1900 no Excel — a aplicação não o sabe representar; converta para texto ou use uma biblioteca a montante que suporte datas a.C.

• O problema do ano 2038 (Y2K38) — guia completo

Bugs frequentes ao converter a hora Unix numa data

O mesmo bug aparece sempre que alguém converte a hora Unix numa data pela primeira vez: o resultado cai em 1970. A causa é quase sempre um × 1000 esquecido em JavaScript, ou o argumento tz em falta em Python, ou uma coluna numérica truncada automaticamente pelo Excel. O artigo complementar sobre bugs cataloga os 10 — cada um aparece em código que converte a hora Unix nalgum momento. Leia-o uma vez e a maioria nunca chegará à produção.

• A data mostra 1970 — passou segundos onde se esperavam milissegundos (construtor JS Date)
• A data está desfasada pelo seu offset UTC local — esqueceu-se de especificar tz=timezone.utc (Python) ou a opção timeZone (JS)
• O Excel mostra ##### ou um erro #VALOR! — a célula não está formatada como Data, ou o valor é negativo
• SQL FROM_UNIXTIME devolve o relógio de parede errado — o MySQL aplica @@session.time_zone; force UTC explicitamente
• Servidor vs portátil produzem datas diferentes — fusos de sistema diferentes; passe sempre tz explicitamente

• 10 bugs frequentes de timestamp Unix e como corrigi-los (complementar)