Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Java DateTimeFormatter: Formatting and Parsing Dates

Learn how to use Java's DateTimeFormatter to format and parse dates and times, including pattern letters, builder usage, thread safety, locales, and common pitfalls.

~5 min readJava
#DateTimeFormatter#Java time API#date formatting#date parsing
A Java DateTimeFormatter converting a date object to a formatted string and back.

Java's DateTimeFormatter is the standard API for converting between date-time objects and their string representations. It handles both formatting (object to string) and parsing (string to object) with a rich set of pattern letters and predefined ISO formats. Because DateTimeFormatter instances are immutable and thread-safe, they can be safely shared across threads, making them a reliable choice for production code.

Creating a DateTimeFormatter

The simplest way to obtain a DateTimeFormatter is through DateTimeFormatter.ofPattern(), which accepts a pattern string composed of specific letters. For example, DateTimeFormatter.ofPattern("yyyy-MM-dd") formats a date as 2025-03-14. You can also use predefined constants like DateTimeFormatter.ISO_LOCAL_DATE or DateTimeFormatter.ISO_OFFSET_DATE_TIME when you need standard ISO 8601 representations.

java
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd"); LocalDate date = LocalDate.of(2025, 3, 14); String formatted = date.format(formatter); // "2025-03-14"

The pattern letters are case-sensitive and each letter represents a specific field. For instance, y is year, M is month, d is day of month, H is hour of day, m is minute, s is second. Repeating a letter changes the width: yyyy gives a four-digit year, MM gives a two-digit month, and so on.

Formatting Date-Time Objects

DateTimeFormatter works with any TemporalAccessor, but you'll most often use it with LocalDate, LocalDateTime, ZonedDateTime, or OffsetDateTime. The format method is called on the formatter, passing the date-time object as an argument.

java
LocalDateTime now = LocalDateTime.of(2025, 3, 14, 15, 30, 45); DateTimeFormatter formatter = DateTimeFormatter.ofPattern("dd/MM/yyyy HH:mm:ss"); String formatted = now.format(formatter); // "14/03/2025 15:30:45"

For ZonedDateTime, you can include time zone information in the pattern. Letters like z represent the zone name (for example, CET), Z represents the numeric offset, and XXX produces an ISO-style offset like +01:00.

java
ZonedDateTime zoned = ZonedDateTime.of(2025, 3, 14, 15, 30, 45, 0, ZoneId.of("Europe/Paris")); DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss z"); String formatted = zoned.format(formatter); // "2025-03-14 15:30:45 CET"

Without an override zone, when the pattern does not include a zone or offset, formatting a ZonedDateTime simply prints the local date-time fields it contains; no time zone conversion happens. To control zone handling explicitly, use withZone() on the formatter.

Parsing Date-Time Strings

The parse method converts a string into a date-time object. The target type is determined by the TemporalQuery you pass, usually LocalDate::from, LocalDateTime::from, or ZonedDateTime::from. If the string does not match the pattern, a DateTimeParseException is thrown.

java
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd"); LocalDate date = LocalDate.parse("2025-03-14", formatter);

For strings that include a time and offset, you can parse into OffsetDateTime or ZonedDateTime.

java
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss XXX"); OffsetDateTime odt = OffsetDateTime.parse("2025-03-14 15:30:45 +01:00", formatter);

When the pattern is missing a field that the target type requires, parsing fails. For example, parsing LocalDate from a string that contains only a year and month will throw an exception because the day is missing. Use DateTimeFormatterBuilder with parseDefaulting to supply default values for missing fields.

Pattern Letters Reference

The following table lists the most commonly used pattern letters. Each letter is case-sensitive and its meaning depends on the number of repetitions.

LetterFieldExample (repetition)Output
yYearyyyy2025
MMonthMM03
dDay of monthdd14
HHour of day (0-23)HH15
mMinutemm30
sSecondss45
SFraction of secondSSS123
zZone namezCET
ZZone offsetZ+0100
XXXISO zone offsetXXX+01:00

Note that M and m are different: uppercase M is month, lowercase m is minute. Similarly, H is hour in 24-hour format, while h is hour in 12-hour format (used with a for AM/PM).

Using DateTimeFormatterBuilder for Complex Patterns

When a pattern is too complex or requires optional sections, DateTimeFormatterBuilder gives you fine-grained control. For example, you can parse a date that may or may not include a time.

java
DateTimeFormatter formatter = new DateTimeFormatterBuilder() .appendPattern("yyyy-MM-dd") .optionalStart() .appendLiteral(' ') .appendPattern("HH:mm") .optionalEnd() .toFormatter(); LocalDateTime dateTime = LocalDateTime.parse("2025-03-14 15:30", formatter); LocalDate date = LocalDate.parse("2025-03-14", formatter);

The builder also allows you to add default values for missing fields with parseDefaulting, which is useful when parsing partial dates.

java
DateTimeFormatter formatter = new DateTimeFormatterBuilder() .appendPattern("yyyy-MM") .parseDefaulting(ChronoField.DAY_OF_MONTH, 1) .toFormatter(); LocalDate firstOfMonth = LocalDate.parse("2025-03", formatter); // 2025-03-01

Thread Safety and Reuse

DateTimeFormatter is immutable and thread-safe. Once created, you can safely share it across multiple threads without synchronization. This makes it a good candidate for a static final constant in a utility class.

java
public class DateUtils { public static final DateTimeFormatter ISO_DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss"); }

Because the formatter holds no mutable state, reusing the same instance avoids the overhead of creating a new formatter for each call. This is especially important in high-throughput code where formatting or parsing happens frequently.

Handling Locale and Time Zone

By default, DateTimeFormatter uses the system locale for textual fields like month names and day-of-week names. To control this, use withLocale().

java
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("dd MMM yyyy", Locale.FRANCE); String formatted = LocalDate.of(2025, 3, 14).format(formatter); // "14 mars 2025"

Similarly, withZone() sets the time zone used when formatting a ZonedDateTime or when parsing a string that lacks a zone. This is useful when you want to display times in a specific zone regardless of the source object's zone.

java
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm z") .withZone(ZoneId.of("America/New_York")); ZonedDateTime zoned = ZonedDateTime.of(2025, 3, 14, 15, 30, 45, 0, ZoneId.of("Europe/Paris")); String formatted = zoned.format(formatter); // "2025-03-14 10:30 EDT"

withZone() sets an override zone on the formatter. It does not mutate the original date-time object, but when formatting an instant-based object such as a ZonedDateTime, it decides which zone's local date-time fields are printed. It is also useful when parsing a string that has no zone, because it supplies the zone for a zoned result.

Common Pitfalls and Edge Cases

One frequent mistake is using the wrong case for pattern letters, such as using M for minutes instead of m. This leads to a DateTimeParseException or incorrect output. Always verify the pattern against the DateTimeFormatter documentation.

Another issue is the difference between matching the pattern and resolving the resulting values. If the input string has extra characters or does not match the pattern, parsing fails. The default resolver style is ResolverStyle.SMART, not STRICT: it is generally safe for ordinary dates, but it can normalize some out-of-range values unless you request stricter validation. If exact validation matters, use withResolverStyle(ResolverStyle.STRICT). ResolverStyle.LENIENT is rarely recommended because it can silently adjust invalid dates such as February 30th instead of rejecting them.

When parsing strings that include a time zone offset, remember that LocalDateTime cannot store an offset. Use OffsetDateTime or ZonedDateTime instead. Similarly, if you parse a string with a zone but target LocalDateTime, the zone is ignored, which may hide data loss.

Performance Considerations

Creating a new DateTimeFormatter for every format or parse operation is wasteful. The pattern parsing and internal field setup happen each time, which adds unnecessary overhead. Reusing a single DateTimeFormatter instance is the simplest way to avoid this cost.

For very high-throughput scenarios, consider using predefined ISO formatters like ISO_LOCAL_DATE or ISO_INSTANT, because they avoid the one-time setup of a custom pattern. Custom patterns are still efficient, but their one-time setup cost is best amortized over many uses.

Also be aware that DateTimeFormatter is not null-safe: passing null to format or parse will throw a NullPointerException. Always check for null inputs in your own code to avoid unexpected failures in production.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.