C# NodaTime
last modified November 15, 2026
This article shows how to work with dates and times in C# using NodaTime. We cover instants and time zones, calendar arithmetic, daylight saving gaps and overlaps, formatting and parsing, and conversion to and from the built-in date types.
The built-in DateTime and DateTimeOffset can
represent almost anything, which is exactly the problem: the same value may
mean a local time, a UTC time, or a point in time, and the
Kind property is easy to ignore. Adding a day to a
DateTime always adds twenty-four hours, even when the time zone
skips an hour, and a local time during the autumn transition exists twice.
NodaTime makes each concept a separate type. An Instant
is a point on the UTC timeline, a LocalDate or
LocalDateTime has no zone at all, and a
ZonedDateTime combines a local value with a zone and the offset
that the zone rules produce. Duration measures exact elapsed
time, while Period counts calendar units such as months and
days. The examples use NodaTime 3.3.7, which is Apache-2.0 licensed; add it
with dotnet add package NodaTime.
Instants and time zones
An Instant is the simplest type: a number of ticks since the
Unix epoch, with no zone or calendar attached. To show it to a user, it must
be placed in a time zone.
using NodaTime; Instant instant = Instant.FromUtc(2026, 11, 15, 9, 30); DateTimeZone zone = DateTimeZoneProviders.Tzdb["Europe/Bratislava"]; ZonedDateTime zoned = instant.InZone(zone); Console.WriteLine(instant); Console.WriteLine(zoned); Console.WriteLine(zoned.Offset); Console.WriteLine(zoned.ToInstant() == instant);
The instant is 09:30 UTC. Bratislava is one hour ahead in November, so the
zoned value is 10:30 with an offset of +01. The last line
confirms that placing an instant in a zone does not change the instant
itself.
ZonedDateTime zoned = instant.InZone(zone);
InZone looks up the zone rules for that instant and attaches
the result. A ZonedDateTime stores the local date and time, the
zone, and the offset; the offset is derived data, not something the caller
sets. ToInstant() returns the original point on the timeline,
so converting to a zone and back is lossless.
Zone identifiers are IANA names such as Europe/Bratislava or
America/New_York. The indexer throws
DateTimeZoneNotFoundException for an unknown name; use
GetZoneOrNull when the identifier comes from user input.
$ dotnet run 2026-11-15T09:30:00Z 2026-11-15T10:30:00 Europe/Bratislava (+01) +01 True
Calendar arithmetic
A LocalDate has a year, a month, and a day, and nothing else.
Arithmetic on it follows the calendar: adding a month to January 31 gives
the last day of February, because February has no 31st. A
Duration, by contrast, is a fixed amount of elapsed time.
using NodaTime;
using System.Globalization;
LocalDate start = new LocalDate(2026, 1, 31);
LocalDate nextMonth = start.PlusMonths(1);
LocalDate plusThirty = start.PlusDays(30);
Period period = Period.Between(start, nextMonth);
Duration duration = Duration.FromDays(30);
Console.WriteLine(start.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture));
Console.WriteLine(nextMonth.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture));
Console.WriteLine(plusThirty.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture));
Console.WriteLine($"period: {period}");
Console.WriteLine($"duration: {duration}");
Console.WriteLine((start + period).ToString("yyyy-MM-dd", CultureInfo.InvariantCulture));
One month after January 31 is February 28, while thirty fixed days later is March 2. The period between the two dates is one month, and a duration of thirty days is written as thirty days, hours, minutes, and seconds. Adding the period back to the start date returns February 28.
LocalDate nextMonth = start.PlusMonths(1);
PlusMonths clamps to the end of the target month instead of
overflowing into March. Period.Between returns the difference
in calendar units, so it is the right type for "one month later" or "two
years and three days". Duration is the right type for elapsed
time, timeouts, and differences between instants. Mixing the two is the most
common source of date bugs, and NodaTime keeps them apart.
The explicit ToString pattern and the invariant culture keep
the output stable. Without a pattern, LocalDate.ToString uses
the current culture and may print a long date with a weekday name.
$ dotnet run 2026-01-31 2026-02-28 2026-03-02 period: P1M duration: 30:00:00:00 2026-02-28
DST gaps and overlaps
Daylight saving time creates two kinds of local times that a naive
DateTime cannot express. When clocks move forward, a range of
local times is skipped; when they move back, a range occurs twice. NodaTime
exposes both cases through MapLocal.
using NodaTime;
DateTimeZone ny = DateTimeZoneProviders.Tzdb["America/New_York"];
LocalDateTime skipped = new LocalDateTime(2026, 3, 8, 2, 30);
LocalDateTime ambiguous = new LocalDateTime(2026, 11, 1, 1, 30);
var gap = ny.MapLocal(skipped);
Console.WriteLine($"gap count: {gap.Count}");
Console.WriteLine($"lenient gap: {skipped.InZoneLeniently(ny)}");
var overlap = ny.MapLocal(ambiguous);
Console.WriteLine($"overlap count: {overlap.Count}");
Console.WriteLine($"first: {overlap.First()}");
Console.WriteLine($"last: {overlap.Last()}");
Console.WriteLine($"lenient overlap: {ambiguous.InZoneLeniently(ny)}");
On March 8, 2026, New York moves from 02:00 to 03:00, so 02:30 does not
exist. On November 1, the clock moves back from 02:00 to 01:00, so 01:30
occurs twice, once at -04 and once at -05.
var gap = ny.MapLocal(skipped);
MapLocal returns a ZoneLocalMapping whose
Count is 0 for a skipped time, 1 for a normal time, and 2 for an
ambiguous one. First() and Last() give the earlier
and later interpretations of an overlap. InZoneLeniently makes
a decision for you: a skipped time is shifted forward by the size of the
gap, and an overlap uses the earlier offset. InZoneStrictly
throws instead, which is preferable when the value came from a user or a
protocol and silently changing it would be wrong.
$ dotnet run gap count: 0 lenient gap: 2026-03-08T03:30:00 America/New_York (-04) overlap count: 2 first: 2026-11-01T01:30:00 America/New_York (-04) last: 2026-11-01T01:30:00 America/New_York (-05) lenient overlap: 2026-11-01T01:30:00 America/New_York (-04)
Calendar days across DST
Adding one calendar day is not the same as adding twenty-four hours. A meeting at noon local time stays at noon the next day, even when the clocks change in between, so the elapsed time is twenty-three or twenty-five hours.
using NodaTime; DateTimeZone ny = DateTimeZoneProviders.Tzdb["America/New_York"]; var before = new LocalDateTime(2026, 3, 7, 12, 0).InZoneStrictly(ny); var after = before.LocalDateTime.PlusDays(1).InZoneLeniently(ny); Console.WriteLine(before); Console.WriteLine(after); Console.WriteLine((after.ToInstant() - before.ToInstant()).TotalHours);
The local time stays at 12:00, but the offset changes from -05
to -04, so only 23 hours pass between the two instants. Adding
a Duration of 24 hours to the first value would produce 13:00
local time instead.
var after = before.LocalDateTime.PlusDays(1).InZoneLeniently(ny);
There is no PlusDays on ZonedDateTime, because the
operation is ambiguous: it could mean a calendar day or an exact duration.
The code chooses the calendar interpretation by taking the local date and
time, adding a day, and resolving it back in the zone. Noon is never skipped
or ambiguous here, so the lenient resolution is safe; for times near a
transition, check MapLocal first.
$ dotnet run 2026-03-07T12:00:00 America/New_York (-05) 2026-03-08T12:00:00 America/New_York (-04) 23
Formatting and parsing
NodaTime does not use the .NET format strings for its types. Each type has a
pattern class in NodaTime.Text, and the pattern is created for a
specific culture. Parsing returns a ParseResult<T> that
reports failure without throwing.
using NodaTime;
using NodaTime.Text;
var datePattern = LocalDatePattern.CreateWithInvariantCulture("dd MMMM yyyy");
var instantPattern = InstantPattern.ExtendedIso;
LocalDate date = new LocalDate(2026, 11, 15);
Instant instant = Instant.FromUtc(2026, 11, 15, 9, 30);
Console.WriteLine(datePattern.Format(date));
Console.WriteLine(instantPattern.Format(instant));
ParseResult<LocalDate> parsed = datePattern.Parse("15 November 2026");
Console.WriteLine(parsed.Success);
Console.WriteLine(datePattern.Format(parsed.Value));
The date pattern writes and reads 15 November 2026, and the
ISO pattern writes the instant with a trailing Z. Parsing the
same text returns a successful result whose value formats back to the
original string.
var datePattern = LocalDatePattern.CreateWithInvariantCulture("dd MMMM yyyy");
CreateWithInvariantCulture binds month names to English, so the
pattern behaves the same on every machine. A pattern created with a specific
culture accepts that culture's month names. ParseResult<T>
has Success, Value, and Exception;
reading Value on a failed result throws. The patterns are
immutable and can be cached in static fields and shared between threads.
$ dotnet run 15 November 2026 2026-11-15T09:30:00Z True 15 November 2026
Interop with DateTime
Most libraries still speak DateTime and
DateTimeOffset. NodaTime converts at the boundary, but only
when the meaning of the built-in value is clear: an instant needs a UTC
DateTime, and an offset value needs a fully specified
DateTimeOffset.
using NodaTime;
DateTime utc = new DateTime(2026, 11, 15, 9, 30, 0, DateTimeKind.Utc);
Instant instant = Instant.FromDateTimeUtc(utc);
DateTime back = instant.ToDateTimeUtc();
Console.WriteLine(instant);
Console.WriteLine(back.ToString("O"));
Console.WriteLine(back.Kind);
DateTimeOffset offset = new DateTimeOffset(2026, 11, 15, 10, 30, 0, TimeSpan.FromHours(1));
OffsetDateTime odt = OffsetDateTime.FromDateTimeOffset(offset);
Console.WriteLine(odt);
Console.WriteLine(odt.ToDateTimeOffset().ToString("O"));
The UTC DateTime becomes an instant and converts back with
Kind set to Utc. The
DateTimeOffset becomes an OffsetDateTime, which
keeps the local time and the offset but has no zone rules.
Instant instant = Instant.FromDateTimeUtc(utc);
FromDateTimeUtc requires DateTimeKind.Utc and
throws for a local or unspecified value, because those do not identify a
unique instant by themselves. A DateTime with
Kind.Unspecified is a local date and time without a zone; to
turn it into an instant, choose a zone explicitly with
LocalDateTime.FromDateTime(...).InZone(...). An
OffsetDateTime is the right type for timestamps that arrive
with an offset, such as ISO-8601 strings in a protocol, when the original
zone is unknown.
$ dotnet run 2026-11-15T09:30:00Z 2026-11-15T09:30:00.0000000Z Utc 2026-11-15T10:30:00+01 2026-11-15T10:30:00.0000000+01:00
Choosing the right type
The type names map directly to the questions a program asks. Use
Instant for a moment in time, such as the timestamp of an
event or the expiry of a token. Use LocalDate for a birthday or
a holiday, LocalTime for an opening hour, and
ZonedDateTime when the user's wall clock matters, such as a
recurring meeting. Use Duration for elapsed time and
Period for calendar arithmetic.
Store instants in UTC and convert to a zone only for display or when a rule depends on the local calendar. Keep the zone identifier with the value when the local time must survive a round trip, because converting to UTC and back loses the original zone. Time zone rules change with government decisions, so the tz database that ships with the runtime should be updated together with the application.
The DateTime, TimeZoneInfo, DateOnly, and TimeSpan tutorials describe the built-in types that NodaTime replaces or complements.
Source
In this article we have used NodaTime for dates and times in C#. See also the DateTime, TimeZoneInfo, DateOnly, and TimeSpan tutorials.
Author
List all C# tutorials.