Converter um datetime do Python em string com milissegundos

Use value.isoformat(timespec="milliseconds") quando um resultado no estilo ISO for adequado. Use strftime() com %f e remova os três últimos dígitos quando precisar de um layout personalizado. As duas abordagens truncam microssegundos para milissegundos em vez de arredondá-los.

A formatação altera a representação, não o valor datetime em si. Os exemplos usam entradas fixas para que a saída possa ser verificada exatamente; substitua esses construtores por um valor da sua aplicação depois de escolher o layout necessário. Se o sistema receptor espera um deslocamento, torne o valor consciente de fuso horário antes de formatá-lo.

Use isoformat() para precisão de milissegundos com três dígitos

datetime.isoformat() é a escolha mais clara para uma string no estilo ISO 8601. O argumento timespec="milliseconds" sempre emite exatamente três dígitos fracionários de segundo. Ele está disponível no Python 3.6 e posteriores.

Passe exatamente a string plural em minúsculas "milliseconds". Outros valores aceitos de timespec selecionam níveis de precisão diferentes, enquanto um valor desconhecido gera ValueError. Esse parâmetro explícito é preferível ao comportamento padrão "auto" quando um esquema posterior exige largura de campo consistente.

O exemplo determinístico a seguir usa um datetime com fuso horário, portanto o resultado também demonstra que isoformat() preserva o deslocamento UTC:

"""Show the recommended ISO-style millisecond formatting behavior."""

from datetime import datetime, timezone


value = datetime(2026, 9, 16, 12, 34, 56, 789654, tzinfo=timezone.utc)
print(value.isoformat(timespec="milliseconds"))

Saída:

2026-09-16T12:34:56.789+00:00

O valor microsecond de seis dígitos 789654 se torna .789. O Python não arredonda o valor para .790; timespec controla quais componentes aparecem, e os componentes de tempo excluídos são truncados.

Use um datetime com fuso horário quando a string precisa identificar um instante real entre sistemas. Um valor naive não tem deslocamento UTC, então seu texto formatado não distingue sozinho uma hora local de UTC ou de outra zona.

isoformat() preserva o deslocamento já anexado ao objeto; ele não converte o valor para UTC. Normalize o datetime primeiro se seu contrato de dados exigir UTC. Por outro lado, omita a conversão de fuso apenas quando o consumidor espera deliberadamente um valor de hora local.

Use strftime() para um layout personalizado

Use strftime() quando precisar controlar a ordem, os separadores ou outros campos. A diretiva %f produz seis dígitos de microssegundos. O fatiamento com [:-3] remove deliberadamente os três últimos dígitos e deixa precisão de milissegundos:

"""Show millisecond precision in a custom datetime string format."""

from datetime import datetime


value = datetime(2026, 9, 16, 12, 34, 56, 789654)
print(value.strftime("%Y-%m-%d %H:%M:%S.%f")[:-3])

Saída:

2026-09-16 12:34:56.789

Esse fatiamento é seguro porque %f sempre fornece um campo de seis dígitos preenchido com zeros, mesmo quando o valor original não tem microssegundos. Mantenha .%f no final do formato antes de usar [:-3]; caso contrário, a fatia pode remover caracteres de outro campo.

A operação trunca em vez de arredondar. Por exemplo, 789999 microssegundos ainda se torna 789 milissegundos. Se uma especificação exige arredondamento, arredonde o datetime antes de formatar e trate um possível transporte para o próximo segundo; apenas fatiar %f não implementa essa regra.

O estilo de importação determina como você chama a classe. Com from datetime import datetime, chame datetime.now(). Se em vez disso você escrever import datetime, chame datetime.datetime.now().

Entenda str() e os limites do fatiamento

str(value) simples equivale a value.isoformat(" "). Seu timespec="auto" padrão omite o campo fracionário quando microsecond é zero e, caso contrário, emite todos os seis dígitos de microssegundos. Portanto, str(value) não garante um campo de milissegundos com três dígitos, e aplicar [:-3] cegamente é inseguro.

Esse comportamento de largura variável é útil para exibição informal, mas inadequado para um campo de largura fixa. Verificar um ponto decimal antes de fatiar evitaria corromper os segundos, mas ainda duplicaria uma lógica já tratada por isoformat(timespec="milliseconds") e exigiria cuidado extra com sufixos de fuso horário.

Este exemplo de limite também mostra que a saída de milissegundos é truncada em 999999 microssegundos e que o valor singular "millisecond" é inválido:

"""Expose truncation, zero-microsecond slicing, and invalid-timespec boundaries."""

from datetime import datetime


almost_next_second = datetime(2026, 9, 16, 12, 34, 56, 999999)
without_fraction = datetime(2026, 9, 16, 12, 34, 56)

print(almost_next_second.isoformat(timespec="milliseconds"))
print(str(without_fraction))
print(str(without_fraction)[:-3])

try:
    without_fraction.isoformat(timespec="millisecond")
except ValueError as error:
    print(f"{type(error).__name__}: {error}")

Saída:

2026-09-16T12:34:56.999
2026-09-16 12:34:56
2026-09-16 12:34
ValueError: Unknown timespec value

A terceira linha não é uma conversão válida para milissegundos: ela remove :56 porque a entrada não tem campo fracionário. Prefira isoformat(timespec="milliseconds") ou use um formato contendo %f, em vez de fatiar o resultado de comprimento variável de str().

Escolha o método apropriado

Use isoformat(timespec="milliseconds") para carimbos de data e hora legíveis por máquina e intercâmbio padrão. Ele lida com microssegundos zero, truncamento e deslocamentos de fuso horário sem manipulação manual de strings. Use strftime() mais [:-3] quando um consumidor exigir um layout personalizado.

Escolha com base no contrato de saída, não na conveniência: isoformat() fornece um formato de data e hora padronizado, strftime() fornece um formato definido pelo chamador, e str() fornece um padrão amigável para humanos com precisão fracionária variável. Em todos os casos, documente se um deslocamento ausente significa hora local, UTC por convenção ou fuso horário desconhecido.

Esses métodos formatam um datetime existente; eles não o convertem em milissegundos desde a época Unix nem analisam uma string em um datetime. Lembre-se também de que três dígitos exibidos descrevem precisão de milissegundos, não necessariamente a exatidão do relógio ou do valor de origem armazenado.