PythonBeginner-friendly

pendulum

Drop-in datetime replacement with first-class timezone support, DST awareness, and intuitive arithmetic.

datetimetimezoneutilitiesparsing

The Problem

Timezone handling in Python is notoriously tricky — DST transitions, ambiguous local times, and converting between zones are error-prone with stdlib. You want a datetime object that just does the right thing.

Mental Model

pendulum.DateTime is a subclass of Python's datetime — so it works anywhere datetime does. pendulum.now() always returns a timezone-aware object. Arithmetic respects DST. You get .diff() for precise durations and .in_timezone() for safe conversions.

60-second start

Work with timezones safely

import pendulum

now_utc = pendulum.now('UTC')
now_nyc = now_utc.in_timezone('America/New_York')
now_tok = now_utc.in_timezone('Asia/Tokyo')

print(now_utc.to_iso8601_string())
print(now_nyc.format('ddd MMM D, h:mm A zz'))

# Arithmetic respects DST
meetingtime = pendulum.datetime(2024, 3, 10, 12, 0, 0, tz='America/New_York')
day_later = meetingtime.add(days=1)  # correctly crosses DST boundary

Use it when

Scheduling apps, calendar features, time-series data across timezones, any app where DST bugs would be costly.

Skip it when

Simple UTC-only timestamps where datetime.now(timezone.utc) is sufficient. pendulum is heavier than stdlib.

Alternatives

arrowMore humanize features, slightly simpler API

dateutilStdlib-compatible, great for parsing

datetimeZero dep for simple cases

Ready to explore the full API?

See every class, function, and relationship in an interactive graph.