ZetCode

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.

Program.cs
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.

Program.cs
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.

Program.cs
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.

Program.cs
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.

Program.cs
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.

Program.cs
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

NodaTime

NodaTime API reference

NodaTime on GitHub

In this article we have used NodaTime for dates and times in C#. See also the DateTime, TimeZoneInfo, DateOnly, and TimeSpan tutorials.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all C# tutorials.