This library differs from the documented Python API for tzinfo implementations; if you want to create local wallclock times you need to use the localize() method documented in this document. In addition, if you perform date arithmetic on local times that cross DST boundaries, the result may be in an incorrect timezone (ie. subtract 1 minute from 2002-10-27 1:00 EST and you get 2002-10-27 0:59 EST instead of the correct 2002-10-27 1:59 EDT). A normalize() method is provided to correct this. Unfortunately these issues cannot be resolved without modifying the Python datetime implementation (see PEP-431).

pytz brings the Olson tz database into Python. This library allows accurate and cross platform timezone calculations using Python 2.4 or higher. It also solves the issue of ambiguous times at the end of daylight saving time, which you can read more about in the Python Library Reference ( datetime.tzinfo ).

If you are installing from a tarball, run the following command as an administrative user:

If you are installing using pip , you don’t need to download anything as the latest version will be downloaded for you from PyPI:

This package can either be installed using pip or from a tarball using the standard Python distutils.

The maintainers of pytz and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more. .

If is_dst is not specified, ambiguous timestamps will raise an pytz.exceptions.AmbiguousTimeError exception.

The is_dst parameter is ignored for most timestamps. It is only used during DST transition ambiguous periods to resolve that ambiguity.

The tzinfo instances returned by the timezone() function have been extended to cope with ambiguous times by adding an is_dst parameter to the utcoffset() , dst() && tzname() methods.

Problems with Localtime

The major problem we have to deal with is that certain datetimes may occur twice in a year. For example, in the US/Eastern timezone on the last Sunday morning in October, the following sequence happens:

01:00 EDT occurs

1 hour later, instead of 2:00am the clock is turned back 1 hour and 01:00 happens again (this time 01:00 EST)

In fact, every instant between 01:00 and 02:00 occurs twice. This means that if you try and create a time in the ‘US/Eastern’ timezone the standard datetime syntax, there is no way to specify if you meant before of after the end-of-daylight-saving-time transition. Using the pytz custom syntax, the best you can do is make an educated guess:

>>> loc_dt = eastern.localize(datetime(2002, 10, 27, 1, 30, 00)) >>> loc_dt.strftime(fmt) '2002-10-27 01:30:00 EST-0500'

As you can see, the system has chosen one for you and there is a 50% chance of it being out by one hour. For some applications, this does not matter. However, if you are trying to schedule meetings with people in different timezones or analyze log files it is not acceptable.

The best and simplest solution is to stick with using UTC. The pytz package encourages using UTC for internal timezone representation by including a special UTC implementation based on the standard Python reference implementation in the Python documentation.

The UTC timezone unpickles to be the same instance, and pickles to a smaller size than other pytz tzinfo instances. The UTC implementation can be obtained as pytz.utc, pytz.UTC, or pytz.timezone(‘UTC’).

>>> import pickle, pytz >>> dt = datetime(2005, 3, 1, 14, 13, 21, tzinfo=utc) >>> naive = dt.replace(tzinfo=None) >>> p = pickle.dumps(dt, 1) >>> naive_p = pickle.dumps(naive, 1) >>> len(p) - len(naive_p) 17 >>> new = pickle.loads(p) >>> new == dt True >>> new is dt False >>> new.tzinfo is dt.tzinfo True >>> pytz.utc is pytz.UTC is pytz.timezone('UTC') True

Note that some other timezones are commonly thought of as the same (GMT, Greenwich, Universal, etc.). The definition of UTC is distinct from these other timezones, and they are not equivalent. For this reason, they will not compare the same in Python.

>>> utc == pytz.timezone('GMT') False

See the section What is UTC, below.

If you insist on working with local times, this library provides a facility for constructing them unambiguously:

>>> loc_dt = datetime(2002, 10, 27, 1, 30, 00) >>> est_dt = eastern.localize(loc_dt, is_dst=True) >>> edt_dt = eastern.localize(loc_dt, is_dst=False) >>> print(est_dt.strftime(fmt) + ' / ' + edt_dt.strftime(fmt)) 2002-10-27 01:30:00 EDT-0400 / 2002-10-27 01:30:00 EST-0500

If you pass None as the is_dst flag to localize(), pytz will refuse to guess and raise exceptions if you try to build ambiguous or non-existent times.

For example, 1:30am on 27th Oct 2002 happened twice in the US/Eastern timezone when the clocks where put back at the end of Daylight Saving Time:

>>> dt = datetime(2002, 10, 27, 1, 30, 00) >>> try: ... eastern.localize(dt, is_dst=None) ... except pytz.exceptions.AmbiguousTimeError: ... print('pytz.exceptions.AmbiguousTimeError: %s' % dt) pytz.exceptions.AmbiguousTimeError: 2002-10-27 01:30:00

Similarly, 2:30am on 7th April 2002 never happened at all in the US/Eastern timezone, as the clocks where put forward at 2:00am skipping the entire hour:

>>> dt = datetime(2002, 4, 7, 2, 30, 00) >>> try: ... eastern.localize(dt, is_dst=None) ... except pytz.exceptions.NonExistentTimeError: ... print('pytz.exceptions.NonExistentTimeError: %s' % dt) pytz.exceptions.NonExistentTimeError: 2002-04-07 02:30:00

Both of these exceptions share a common base class to make error handling easier:

>>> isinstance(pytz.AmbiguousTimeError(), pytz.InvalidTimeError) True >>> isinstance(pytz.NonExistentTimeError(), pytz.InvalidTimeError) True

A special case is where countries change their timezone definitions with no daylight savings time switch. For example, in 1915 Warsaw switched from Warsaw time to Central European time with no daylight savings transition. So at the stroke of midnight on August 5th 1915 the clocks were wound back 24 minutes creating an ambiguous time period that cannot be specified without referring to the timezone abbreviation or the actual UTC offset. In this case midnight happened twice, neither time during a daylight saving time period. pytz handles this transition by treating the ambiguous period before the switch as daylight savings time, and the ambiguous period after as standard time.

>>> warsaw = pytz.timezone('Europe/Warsaw') >>> amb_dt1 = warsaw.localize(datetime(1915, 8, 4, 23, 59, 59), is_dst=True) >>> amb_dt1.strftime(fmt) '1915-08-04 23:59:59 WMT+0124' >>> amb_dt2 = warsaw.localize(datetime(1915, 8, 4, 23, 59, 59), is_dst=False) >>> amb_dt2.strftime(fmt) '1915-08-04 23:59:59 CET+0100' >>> switch_dt = warsaw.localize(datetime(1915, 8, 5, 00, 00, 00), is_dst=False) >>> switch_dt.strftime(fmt) '1915-08-05 00:00:00 CET+0100' >>> str(switch_dt - amb_dt1) '0:24:01' >>> str(switch_dt - amb_dt2) '0:00:01'

The best way of creating a time during an ambiguous time period is by converting from another timezone such as UTC:

>>> utc_dt = datetime(1915, 8, 4, 22, 36, tzinfo=pytz.utc) >>> utc_dt.astimezone(warsaw).strftime(fmt) '1915-08-04 23:36:00 CET+0100'

The standard Python way of handling all these ambiguities is not to handle them, such as demonstrated in this example using the US/Eastern timezone definition from the Python documentation (Note that this implementation only works for dates between 1987 and 2006 - it is included for tests only!):

>>> from pytz.reference import Eastern # pytz.reference only for tests >>> dt = datetime(2002, 10, 27, 0, 30, tzinfo=Eastern) >>> str(dt) '2002-10-27 00:30:00-04:00' >>> str(dt + timedelta(hours=1)) '2002-10-27 01:30:00-05:00' >>> str(dt + timedelta(hours=2)) '2002-10-27 02:30:00-05:00' >>> str(dt + timedelta(hours=3)) '2002-10-27 03:30:00-05:00'

Notice the first two results? At first glance you might think they are correct, but taking the UTC offset into account you find that they are actually two hours appart instead of the 1 hour we asked for.

>>> from pytz.reference import UTC # pytz.reference only for tests >>> str(dt.astimezone(UTC)) '2002-10-27 04:30:00+00:00' >>> str((dt + timedelta(hours=1)).astimezone(UTC)) '2002-10-27 06:30:00+00:00'