Python pytz

The pytz module brings the Olson timezone database into Python and enables accurate and timezone-aware datetime operations. It is especially useful in applications that serve a global user base, allowing you to convert and manipulate datetimes across different time zones reliably.

Installation

You can install the pytz module using any of the following methods:

Using pip:

pip install pytz

Using tarball:

python setup.py install

Using setuptools:

easy_install --upgrade pytz

Converting timezones

The astimezone() function is used to convert a timezone-aware datetime object from one timezone to another.

Syntax:

datetime_obj.astimezone(target_timezone)

Example: 

from datetime import datetime
from pytz import timezone

fmt = "%Y-%m-%d %H:%M:%S %Z%z"

# Get current UTC time
utc_now = datetime.now(timezone('UTC'))
print(utc_now.strftime(fmt))

# Convert to Asia/Kolkata timezone
ist_now = utc_now.astimezone(timezone('Asia/Kolkata'))
print(ist_now.strftime(fmt))

2025-05-09 10:15:40 UTC+0000
2025-05-09 15:45:40 IST+0530

Explanation:

• datetime.now(timezone('UTC')): Gets the current time in UTC with timezone awareness.
• astimezone(timezone('Asia/Kolkata')): Converts the UTC time to Asia/Kolkata (IST) timezone.
• strftime(fmt): Formats the datetime into a readable string showing date, time, timezone abbreviation, and offset.

Python pytz attributes 

There are some attributes in pytz module to help us find the supported timezone strings. These attributes will help understand this module better.

1. all_timezones

It returns the list all the available timezones with pytz.all_timezones:

import pytz

print('the supported timezones by the pytz module:', pytz.all_timezones, '\n')

Output:

Explanation: This code imports the pytz module and prints all the supported timezones using pytz.all_timezones, which returns a list of timezone names available in the module.

2. all_timezones_set

It returns the set of all the available timezones with pytz.all_timezones_set:

import pytz

print('all the supported timezones set:', pytz.all_timezones_set, '\n')

Output

Explanation: This code prints all the supported timezones as a set using pytz.all_timezones_set, which provides the same timezones as all_timezones but in an unordered, unique set format.

3. Common_timezones, Common_timezones_set 

It returns the list and set of commonly used timezones with pytz.common_timezones, pytz.common_timezones_set.

import pytz

print('Commonly used time-zones:', 
      pytz.common_timezones, '\n')

print('Commonly used time-zones-set:',
      pytz.common_timezones_set, '\n')

Output

Explanation:

• pytz.common_timezones: returns a list of frequently used timezone names.
• pytz.common_timezones_set: returns the same timezones as an unordered set.

4. country_names 

It returns a dict of country ISO Alpha-2 Code and country name as a key-value pair.

import pytz

print('country_names =')

for key, val in pytz.country_names.items():
    print(key, '=', val, end=',')
    
print('\n')
print('equivalent country name to the input code: =', pytz.country_names['IN'])

Output

Explanation: This code prints a dictionary of country ISO codes and their country names using pytz.country_names. It also retrieves the country name for the code 'IN', which corresponds to India.

5. country_timezones

It returns a dictionary of country ISO Alpha-2 Code as key and list of supported time-zones for a particular input key (country code) as value

import pytz

print('country_timezones =')

for key, val in pytz.country_timezones.items():
    print(key, '=', val, end=',')
    
print('\n')
print('Time-zones supported by Antarctica =', pytz.country_timezones['AQ'])

Output

Explanation:

• pytz.country_timezones.items() lists each country code with its associated timezones.
• pytz.country_timezones['AQ'] specifically shows all the timezones used in Antarctica.

Python pytz example

Example 1: creating datetime instance with timezone information

This code demonstrates how to get the current time in different timezones using the pytz module in Python.

import pytz
import datetime
from datetime import datetime

utc = pytz.utc

kiev_tz = pytz.timezone('Europe/Kiev')
print('UTC Time =', datetime.now(tz=utc))
print('IST Time =', datetime.now(tz=kiev_tz))

UTC Time = 2025-05-09 10:57:48.768744+00:00
IST Time = 2025-05-09 13:57:48.768794+03:00

Explanation:

• pytz.utc: Retrieves the UTC timezone object.
• pytz.timezone('Europe/Kiev'): Loads the timezone for Kiev, Ukraine.
• datetime.now(tz=...): Returns the current time localized to the given timezone (UTC and Kiev in this case).
• The output shows both UTC time and Kiev time with their respective timezone offsets.

Example 2: Formatting Datetime

This code shows how to format a datetime object into human-readable and ISO 8601 string formats using Python's datetime module.

import pytz
import datetime

d = datetime.datetime(1984, 1, 10, 23, 30)

d1 = d.strftime("%B %d, %Y")

d2 = d.isoformat()
print(d1)
print(d2)

January 10, 1984
1984-01-10T23:30:00

Explanation:

• d = datetime.datetime(1984, 1, 10, 23, 30): Creates a naive datetime object for January 10, 1984, at 11:30 PM.
• d.strftime("%B %d, %Y"): Formats the date as a readable string like "January 10, 1984".
• d.isoformat(): Converts the datetime to ISO 8601 format: "1984-01-10T23:30:00".
• The two formats are printed to show different representations of the same datetime.

Using localize() to Make Naive Datetime Timezone-Aware

The localize() function is used to assign a timezone to a naive datetime object. This is crucial when you receive a datetime input without timezone info and need to assign one correctly.

Example1:

import pytz
import datetime
from datetime import datetime

ist = pytz.timezone('Asia/Kolkata')
utc = pytz.utc
local_datetime = ist.localize(datetime.now())

print('IST Current Time =', local_datetime.strftime('%Y-%m-%d %H:%M:%S %Z%z'))
print('Wrong UTC Current Time =', utc.localize(
    datetime.now()).strftime('%Y-%m-%d %H:%M:%S %Z%z'))

IST Current Time = 2025-05-09 11:01:04 IST+0530
Wrong UTC Current Time = 2025-05-09 11:01:04 UTC+0000

Explanation:

• datetime.now() creates a naive datetime (without timezone info).
• ist.localize(datetime.now()): Converts the current naive datetime to IST (Asia/Kolkata).
• utc.localize(datetime.now()): Converts a separate naive datetime to UTC.

Example2:

from datetime import datetime
from pytz import timezone

naive = datetime(2019, 8, 19, 12, 0)

aware = timezone('UTC').localize(naive)
print(aware)

2019-08-19 12:00:00+00:00

Explanation:

• datetime(2019, 8, 19, 12, 0): Creates a naive datetime for August 19, 2019 at 12:00 PM.
• timezone('UTC').localize(naive): Converts the naive datetime to UTC timezone-aware using pytz.localize().
• print(aware): Displays the datetime with timezone info → 2019-08-19 12:00:00+00:00.