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.

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.
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.
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.
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.
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.
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.
| Letter | Field | Example (repetition) | Output |
|---|---|---|---|
y | Year | yyyy | 2025 |
M | Month | MM | 03 |
d | Day of month | dd | 14 |
H | Hour of day (0-23) | HH | 15 |
m | Minute | mm | 30 |
s | Second | ss | 45 |
S | Fraction of second | SSS | 123 |
z | Zone name | z | CET |
Z | Zone offset | Z | +0100 |
XXX | ISO zone offset | XXX | +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.
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.
DateTimeFormatter formatter = new DateTimeFormatterBuilder()
.appendPattern("yyyy-MM")
.parseDefaulting(ChronoField.DAY_OF_MONTH, 1)
.toFormatter();
LocalDate firstOfMonth = LocalDate.parse("2025-03", formatter); // 2025-03-01Thread 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.
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().
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.
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 toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesJava Final Keyword: Usage and Behavior
How Java's final keyword works for variables, methods, and classes, with practical examples and decision guidance for using it.
Java Final Variable: Syntax, Behavior, and Use Cases
Understand what a final variable in Java means, how initialization works, and when to use it for constants, immutability, and clearer code.
Java Duration vs Period: When to Use Each
java duration vs period: Compare Java Duration and Period to handle time-based and date-based calculations correctly. Learn syntax, conversion, and pitfalls.
Instance vs Static Variables in Java: Key Differences
Understand the difference between instance and static variables in Java, including memory, lifecycle, and when to use each.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.