Overview
Modern Java should use java.time.Instant for Unix timestamp work. Instant represents a point on the UTC timeline and can convert cleanly between epoch seconds, milliseconds, and formatted zoned dates.
This guide focuses on practical implementation choices: how values should be stored, how they should cross API boundaries, and where developers most often introduce timezone or precision bugs. The safest pattern is to keep the stored value unambiguous, document the unit, and format the date only when it reaches a human-facing interface.
When to use it
Use Instant in APIs, persistence layers, event systems, and scheduled jobs. Convert to ZonedDateTime only when displaying in a specific timezone.
For production systems, also consider how the value will be indexed, logged, serialized, and read by other teams. A timestamp field that is obvious in one programming language can become ambiguous when it is consumed by JavaScript, SQL, mobile clients, or third-party integrations.
Developer examples
Use examples like this as a starting point, then adapt the timezone and precision to your application contract.
Instant instant = Instant.ofEpochSecond(1717243200L);
System.out.println(instant.toString());
long now = Instant.now().getEpochSecond();Common pitfalls
Avoid old Date/Calendar APIs for new code when java.time is available. Be explicit about seconds versus milliseconds.
Most timestamp bugs come from hidden assumptions: local time treated as UTC, seconds treated as milliseconds, formatted strings parsed without offsets, or narrow integer columns copied from old examples. Add tests for boundary dates and document the expected unit beside every external timestamp field.
FAQ
What Java type should store a Unix timestamp?
Use Instant for instants, or a long when you intentionally need raw epoch seconds or milliseconds.
Is Instant UTC?
Instant represents an absolute moment on the UTC timeline.