# timezone 0.11.2

Time zone databases and time zone aware `DateTime`.




## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com
flutter pub add timezone
```
Published: 2026-10-12T13:20:31.340351Z
Expected archive SHA-256: 9f4e5a1a0e4fef7dd3424842c0575db01bfb7a11730e8d55753fcd5c5c98767b

Available in cache; verification: upstream_checksum
## Direct dependencies
- http: ^1.6.0
- path: ^1.9.1

## Package README (untrusted upstream documentation)
[![package:timezone](https://github.com/dart-lang/labs/actions/workflows/timezone.yml/badge.svg)](https://github.com/dart-lang/labs/actions/workflows/timezone.yml)
[![pub package](https://img.shields.io/pub/v/timezone.svg)](https://pub.dev/packages/timezone)
[![package publisher](https://img.shields.io/pub/publisher/timezone.svg)](https://pub.dev/packages/timezone/publisher)

# TimeZone

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

The current time zone database version is [2025c]. See [the announcement] for
details.

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

Getting the current timezone of the device that the app is running on is  
highly platform dependent and is not a goal of this package. 

## Initialization

[`TimeZone`] objects require time zone data, so the first step is to load
one of our [time zone databases](#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`.

```dart
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])`.

```dart
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])`.

```dart
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.

```dart
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](https://www.iana.org/time-zones)

#### Get location by tz database/Olson name

```dart
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](https://www.iana.org/time-zones)

### TimeZone

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

```dart
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.

```dart
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.

```dart
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:

```dart
import 'package:timezone/data/latest.dart' as tz;
import 'package:timezone/timezone.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"
}
```

## <a name="databases"></a> Time Zone databases

We are using [IANA Time Zone Database](https://www.iana.org/time-zones)
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.

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

Note, on Windows, you may need to follow [these
steps](https://github.com/srawlins/timezone/issues/60#issuecomment-638411716)
which use WSL.

[2025b]: https://data.iana.org/time-zones/releases/tzdb-2025b.tar.lz
[IANA time zone database]: https://www.iana.org/time-zones
[Wikipedia list]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
[`TZDateTime`]: https://pub.dartlang.org/documentation/timezone/latest/timezone.standalone/TZDateTime-class.html
[`TimeZone`]: https://pub.dartlang.org/documentation/timezone/latest/timezone.standalone/TimeZone-class.html
[the announcement]: https://lists.iana.org/hyperkitty/list/tz-announce@iana.org/thread/TAGXKYLMAQRZRFTERQ33CEKOW7KRJVAK/

## Changelog
## 0.11.2

- Update timezone database to 2026c.
- Validate header offsets and lengths in tzdb deserializer.
- Update timezone database to 2026d.
- Update timezone database to 2026e.

## 0.11.1

- Specify `Etc/UTC` as the default timezone (replaces `UTC`)

## 0.11.0

- Make `Location.offset` a `Duration` instead of an `int`.
- Generate list of common locations fom IANA data.
- Move to `dart-lang/labs` monorepo.
- Add timezone data version to generated headers.

# 0.10.2

- Upgrade minimum SDK to `^3.10.0` and the databases to [2025c].

[2025c]: https://lists.iana.org/hyperkitty/list/tz-announce@iana.org/thread/TAGXKYLMAQRZRFTERQ33CEKOW7KRJVAK/

# 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!

[2025a]: https://lists.iana.org/hyperkitty/list/tz-announce@iana.org/thread/MWII7R3HMCEDNUCIYQKSSTYYR7UWK4OQ/
[2025b]: https://lists.iana.org/hyperkitty/list/tz-announce@iana.org/thread/6JVHNHLB6I2WAYTQ75L6KEPEQHFXAJK3/

# 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].

[2024b]: https://lists.iana.org/hyperkitty/list/tz-announce@iana.org/thread/IZ7AO6WRE3W3TWBL5IR6PMQUL433BQIE/

# 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].

[2023d]: https://mm.icann.org/pipermail/tz-announce/2023-December.txt
[2024a]: https://mm.icann.org/pipermail/tz-announce/2024-February.txt


# 0.9.2

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

[2023a]: https://mm.icann.org/pipermail/tz-announce/2023-March/000077.html
[2023b]: https://mm.icann.org/pipermail/tz-announce/2023-March/000078.html
[2023c]: https://mm.icann.org/pipermail/tz-announce/2023-March/000079.html

# 0.9.1

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

[2022d]: https://mm.icann.org/pipermail/tz-announce/2022-September/000073.html
[2022e]: https://mm.icann.org/pipermail/tz-announce/2022-October/000074.html
[2022f]: https://mm.icann.org/pipermail/tz-announce/2022-October/000075.html
[2022g]: https://mm.icann.org/pipermail/tz-announce/2022-November/000076.html

# 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_*`.

[2022a]: https://mm.icann.org/pipermail/tz-announce/2022-March/000070.html
[2022b]: https://mm.icann.org/pipermail/tz-announce/2022-August/000071.html
[2022c]: https://mm.icann.org/pipermail/tz-announce/2022-August/000072.html

# 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.

[2021b]: https://mm.icann.org/pipermail/tz-announce/2021-September/000066.html
[2021c]: https://mm.icann.org/pipermail/tz-announce/2021-October/000067.html
[2021d]: https://mm.icann.org/pipermail/tz-announce/2021-October/000068.html
[2021e]: https://mm.icann.org/pipermail/tz-announce/2021-October/000069.html

# 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`.

[2021a]: https://mm.icann.org/pipermail/tz-announce/2021-January/000065.html


# 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].

[2020d]: https://mm.icann.org/pipermail/tz-announce/2020-October/000062.html

# 0.5.8

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

[2020b]: https://mm.icann.org/pipermail/tz-announce/2020-October/000059.html

# 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.

[2020a]: https://mm.icann.org/pipermail/tz-announce/2020-April/000058.html

# 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.

[2019c]: https://mm.icann.org/pipermail/tz-announce/2019-September/000057.html

# 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`

[2019b]: https://mm.icann.org/pipermail/tz-announce/2019-July/000056.html

# 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].

[2019a]: https://mm.icann.org/pipermail/tz-announce/2019-March/000055.html

# 0.5.2

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

[2018h]: https://mm.icann.org/pipermail/tz-announce/2018-December/000053.html
[2018i]: https://mm.icann.org/pipermail/tz-announce/2018-December/000054.html

# 0.5.1

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

[2018d]: https://mm.icann.org/pipermail/tz-announce/2018-March/000049.html
[2018e]: https://mm.icann.org/pipermail/tz-announce/2018-May/000050.html
[2018f]: https://mm.icann.org/pipermail/tz-announce/2018-October/000051.html
[2018g]: https://mm.icann.org/pipermail/tz-announce/2018-October/000052.html

# 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].

[2015c]: https://mm.icann.org/pipermail/tz-announce/2015-April/000030.html
[2015d]: https://mm.icann.org/pipermail/tz-announce/2015-April/000031.html
[2015e]: https://mm.icann.org/pipermail/tz-announce/2015-June/000032.html
[2015f]: https://mm.icann.org/pipermail/tz-announce/2015-August/000033.html
[2015g]: https://mm.icann.org/pipermail/tz-announce/2015-October/000034.html
[2016a]: https://mm.icann.org/pipermail/tz-announce/2016-January/000035.html
[2016b]: https://mm.icann.org/pipermail/tz-announce/2016-March/000036.html
[2016c]: https://mm.icann.org/pipermail/tz-announce/2016-March/000037.html
[2016d]: https://mm.icann.org/pipermail/tz-announce/2016-April/000038.html
[2016e]: https://mm.icann.org/pipermail/tz-announce/2016-June/000039.html
[2016f]: https://mm.icann.org/pipermail/tz-announce/2016-July/000040.html
[2016g]: https://mm.icann.org/pipermail/tz-announce/2016-September/000041.html
[2016h]: https://mm.icann.org/pipermail/tz-announce/2016-October/000042.html
[2016i]: https://mm.icann.org/pipermail/tz-announce/2016-November/000043.html
[2017a]: https://mm.icann.org/pipermail/tz-announce/2017-February/000045.html
[2017b]: https://mm.icann.org/pipermail/tz-announce/2017-March/000046.html
[2017c]: https://mm.icann.org/pipermail/tz-announce/2017-October/000047.html
[2018c]: https://mm.icann.org/pipermail/tz-announce/2018-January/000048.html

# 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.