TimeZone

This package provides the IANA time zone database and time zone aware DateTime class, TZDateTime.

The current time zone database version is 2025b. See the announcement for details.

You can update to the current IANA time zone database by running tool/refresh.sh.

Initialization

TimeZone objects require time zone data, so the first step is to load one of our time zone databases.

We provide three different APIs to load a database: one which is embedded into a Dart library, one for browsers, and one for standalone environments.

Database variants

We offer three different variants of the IANA database:

• default: doesn't contain deprecated and historical zones with some exceptions like "US/Eastern" and "Etc/UTC"; this is about 75% the size of the all database.
• all: contains all data from the IANA time zone database.
• 10y: default database truncated to contain historical data from 5 years ago until 5 years in the future; this database is about 25% the size of the default database.

Initialization from Dart library

This is the recommended way to initialize a time zone database for non-browser environments. Each Dart library found in lib/data, for example lib/data/latest.dart, contains a single no-argument function, initializeTimeZones.

import 'package:timezone/data/latest.dart' as tz;
                void main() {
                  tz.initializeTimeZones();
                }
                

To initialize the all database variant, import 'package:timezone/data/latest_all.dart'. To initialize the 10y database variant, import 'package:timezone/data/latest_10y.dart'.

Initialization for browser environment

Import package:timezone/browser.dart library and run async function Future initializeTimeZone([String path]).

import 'package:timezone/browser.dart' as tz;
                
                Future<void> setup() async {
                  await tz.initializeTimeZone();
                  var detroit = tz.getLocation('America/Detroit');
                  var now = tz.TZDateTime.now(detroit);
                }
                

To initialize the all database variant, call initializeTimeZone('packages/timezone/data/latest_all.tzf'). To initialize the 10y database variant, call initializeTimeZone('packages/timezone/data/latest_10y.tzf').

Initialization for standalone environment

Import package:timezone/standalone.dart library and run async function Future initializeTimeZone([String path]).

import 'package:timezone/standalone.dart' as tz;
                
                Future<void> setup() async {
                  await tz.initializeTimeZone();
                  var detroit = tz.getLocation('America/Detroit');
                  var now = tz.TZDateTime.now(detroit);
                }
                

Note: This method likely will not work in a Flutter environment.

To initialize the all database variant, call initializeTimeZone('data/latest_all.tzf'). To initialize the 10y database variant, call initializeTimeZone('data/latest_10y.tzf').

Local Location

By default, when library is initialized, local location will be UTC.

To overwrite local location you can use setLocalLocation(Location location) function.

Future<void> setup() async {
                  await tz.initializeTimeZone();
                  var detroit = tz.getLocation('America/Detroit');
                  tz.setLocalLocation(detroit);
                }
                

API

Library Namespace

The public interfaces expose several top-level functions. It is recommended then to import the libraries with a prefix (the prefix tz is common), or to import specific members via a show clause.

Location

Each location in the database represents a national region where all clocks keeping local time have agreed since 1970. Locations are identified by continent or ocean and then by the name of the location, which is typically the largest city within the region. For example, America/New_York represents most of the US eastern time zone; America/Phoenix represents most of Arizona, which uses mountain time without daylight saving time (DST); America/Detroit represents most of Michigan, which uses eastern time but with different DST rules in 1975; and other entries represent smaller regions like Starke County, Indiana, which switched from central to eastern time in 1991 and switched back in 2006.

The tz database

Get location by tz database/Olson name

final detroit = tz.getLocation('America/Detroit');
                

See Wikipedia list for more database entry names.

We don't provide any functions to get locations by time zone abbreviations because of the ambiguities.

Alphabetic time zone abbreviations should not be used as unique identifiers for UTC offsets as they are ambiguous in practice. For example, "EST" denotes 5 hours behind UTC in English-speaking North America, but it denotes 10 or 11 hours ahead of UTC in Australia; and French-speaking North Americans prefer "HNE" to "EST".

The tz database

TimeZone

TimeZone objects represents time zone and contains offset, DST flag, and name in the abbreviated form.

var timeInUtc = DateTime.utc(1995, 1, 1);
                var timeZone = detroit.timeZone(timeInUtc.millisecondsSinceEpoch);
                

TimeZone aware DateTime

The TZDateTime class implements the DateTime interface from dart:core, and contains information about location and time zone.

var date = tz.TZDateTime(detroit, 2014, 11, 17);
                

Converting DateTimes between time zones

To convert between time zones, just create a new TZDateTime object using from constructor and pass Location and DateTime to the constructor.

var localTime = tz.DateTime(2010, 1, 1);
                var detroitTime = tz.TZDateTime.from(localTime, detroit);
                

This constructor supports any objects that implement DateTime interface, so you can pass a native DateTime object or our TZDateTime.

Listing known time zones

After initializing the time zone database, the timeZoneDatabase top-level member contains all of the known time zones. Examples:

import 'package:timezone/timezone.dart' as tz;
                import 'package:timezone/data/latest.dart' as tz;
                
                void main() {
                  tz.initializeTimeZones();
                  var locations = tz.timeZoneDatabase.locations;
                  print(locations.length); // => 429
                  print(locations.keys.first); // => "Africa/Abidjan"
                  print(locations.keys.last); // => "US/Pacific"
                }
                

Time Zone databases

We are using IANA Time Zone Database to build our databases.

We currently build three different database variants:

• default (doesn't contain deprecated and historical zones with some exceptions like US/Eastern). 361kb
• all (contains all data from the IANA time zone database). 443kb
• 10y (default database that contains historical data from the last and future 5 years). 85kb

Updating Time Zone databases

Script for updating Time Zone database, it will automatically download the IANA time zone database and compile into our native format.

$ chmod +x tool/refresh.sh
                $ tool/refresh.sh
                

Note, on Windows, you may need to follow these steps which use WSL.

0.10.1

• Time zone database updated to 2025b. For your convenience here is the announcement for 2025a, 2025b.
• Added a native getter for TZDateTime. Thanks @klondikedragon!

0.10.0

• Update time zone-updating script to use rearguard.zi.
• Convert browser.dart to use package:http instead of dart:html for HTTP requests.
• Time zone database updated to 2024b. For your convenience here is the announcement for 2024b.

0.9.4

• Support cross-isolate issues by overriding hashCode and operator == on class Location. (see #147)
• Fix incorrect DST transition. (see #166)

0.9.3

• Time zone database updated to 2024a. For your convenience here are the announcements for 2023d, 2024a.

0.9.2

• Time zone database updated to 2023c. For your convenience here are the announcements for 2023a, 2023b, 2023c.

0.9.1

• Time zone database updated to 2022g. For your convenience here are the announcements for 2022d, 2022e, 2022f, 2022g.

0.9.0

• Time zone database updated to 2022c. For your convenience here are the announcements for 2022a, 2022b, 2022c.
• Removed named database files in lib/data (for example, lib/data/2021e.tzf). The only supported database files are all now named latest_*.

0.8.1

• Time zone database updated to 2021e. For your convenience here are the announcements for 2021b, 2021c, 2021d, 2021e.
• Fixed encoding script to not skip a few missing time zones.

0.8.0

• Time zone database updated to 2021a. For your convenience here is the announcement for 2021a.
• Time zone databases encoded with UTF-16 instead of base64.
• Breaking change: Remove tool/encode.dart in favor of tool/encode_dart.dart.

0.7.0

• Breaking change: Change some of TimeZone's constructor parameters to be named instead of positional.
• Breaking change: Rename TimeZone.abbr to TimeZone.abbreviation.
• Deprecate LocationDatabase.isEmpty in favor of LocationDatabase.isInitialized.
• Removed new usage from examples and fixed a typo in the TZDateTime.from example.
• Migrate to Dart's null safety language feature.

0.6.1

• Updated the get script (now encode_tzf) to work with a zoneinfo directory (as created by the zic tool) as input. Fetching and compiling this directory is now done by a bash script (refresh.sh) using standard tools.

  This allows pointing the tool at a custom zoneinfo directory.

0.6.0

• Stopping internal versioning of time zone data. Only the latest data will be included, as there is no use case for using an outdated version.
• Renaming the _2015_2025 database to _10y for it to have a stable name. In the past latest_2010-2020.tzf had to be renamed to latest_2015-2025.tzf.

0.5.9

• Time zone database updated to 2020d. For your convenience here is the announcement for 2020d.

0.5.8

• Time zone database updated to 2020b. For your convenience here is the announcement for 2020b.

0.5.7

• Time zone database updated to 2020a. For your convenience here is the announcement for 2020a.
• Earlier null checking on some TZDateTime constructor arguments.
• Many internal changes; should not affect API.

0.5.6

• Time zone database updated to 2019c. For your convenience here is the announcement for 2019c.
• Dart-importable databases made available in lib/data. README.md has more details.

0.5.5

• Time zone database updated to 2019b. For your convenience here is the announcement for 2019b.
• Convenience database symlinks added for convenience at
  • lib/data/latest.tzf
  • lib/data/latest_2015-2025.tzf
  • lib/data/latest_all.tzf

0.5.4

• TZDateTime.utc is accessible before time zone database is initialized (thanks @jsmarr).
• Fix dropping microseconds when creating TZDateTime (thanks @jsmarr).

0.5.3

• Time zone database updated to 2019a. For your convenience here is the announcement for 2019a.

0.5.2

• Time zone database updated to 2018i. For your convenience here are the announcements for 2018h and 2018i.

0.5.1

• Time zone database updated to 2018g. For your convenience here are the announcements for 2018d, 2018e, 2018f, and 2018g.

0.5.0

• Support a package-directory-free environment. In Dart 1.19, timezone is now compatible with pub get --no-packages-dir.
• Breaking: Remove initializeTimeZoneSync method; it is incompatible with the async method for resolving package URIs.
• Fix all strong mode errors (thanks @har79).
• Add microsecond support (thanks @har79).
• Improve interaction between TZDateTime and native DateTime (thanks @har79).
• Fix TimeZone's == (thanks @har79).
• Many new dartdoc comments (thanks @har79).
• Fix for calling new TZDateTime.from() with a non-UTC DateTime object (thanks @tomaine2002).
• Support Dart 2.
• Time zone database updated to 2018c. For your convenience here are the announcements for 2015c, 2015d, 2015e, 2015f, 2015g, 2016a, 2016b, 2016c, 2016d, 2016e, 2016f, 2016g, 2016h, 2016i, 2017a, 2017b, 2017c, and 2018c.

0.4.3

• Fix Dart 1.14 incompatibility further.

0.4.2

• Bad pub publish. Ignore.

0.4.1

• Fix Dart 1.14 incompatibility with packageRoot returning null.

0.4.0

• Remove usage of tuple package.
• Upgrade unittest package to test.
• Fix database URL for "latest" database.
• Add tool/dartfmt for formatting source.

0.3.1

• generate_data_subset script is removed. It will be available as a separate package.

0.3.0

• Time zone database updated to 2015b.
• Removed local location detection heuristics (didn't worked properly). Local location is initialized with UTC location by default, use setLocalLocation to change local location.
• Time zone database format is changed; data is aligned.

0.2.5

• Fixed bug with String formatting (invalid offsets for minutes).

0.2.4

• Fixed bug with Calendar-type constructor.

0.2.3

• Added initializeTimeZoneSync function for standalone environments.
• Fixed bug with script path on Windows.

0.2.2

• TimeZone database updated to "2014j".
• "args" and "path" moved from dev dependencies to dependencies.

0.2.1

• tzfile library renamed to tzdata.
• Added zone1970.tab parser to tzdata library.
• Removed package:collection dependency.