Pendulum

What it is

Pendulum is a Python library for handling dates, times, and time zones. It provides a cleaner and more intuitive API than the standard `datetime` module, with precise parsing, formatting, and manipulation of date and time objects.

Pendulum allows creating and manipulating dates and times, handling time zones, formatting, parsing strings, and performing arithmetic with durations. It is fully compatible with Python's `datetime` module but offers additional convenience methods and immutability.

Installation

pip install pendulum

Getting started

The smallest useful thing you can do with it, and what each part means.

Creating a datetime

python

import pendulum
now = pendulum.now()
print(now)

Gets the current date and time with timezone awareness.

Creating a specific datetime

python

import pendulum
dt = pendulum.datetime(2025, 8, 21, 15, 30)
print(dt)

Creates a specific datetime object for 21st August 2025 at 15:30.

Parsing a datetime string

python

import pendulum
dt = pendulum.parse('2025-08-21T15:30:00')
print(dt)

Parses an ISO-8601 formatted string into a Pendulum datetime object.

Advanced usage

Where the library earns its place over a simpler alternative.

Time zone conversion

python

1234import pendulum
now = pendulum.now('UTC')
ny = now.in_tz('America/New_York')
print(ny)

Converts a UTC datetime to another timezone (New York).

Date arithmetic

python

123456import pendulum
now = pendulum.now()
later = now.add(days=5, hours=3)
print(later)
previous = now.subtract(weeks=2)
print(previous)

Adds or subtracts time intervals to perform date arithmetic easily.

Durations

python

import pendulum
duration = pendulum.duration(days=2, hours=3)
print(duration.in_hours())

Creates a duration and converts it into hours.

Formatting dates

python

1234import pendulum
now = pendulum.now()
print(now.to_iso8601_string())
print(now.format('dddd, MMMM D, YYYY'))

Formats datetime objects into ISO 8601 strings or human-readable formats.

Difference between two dates

python

12345import pendulum
d1 = pendulum.date(2025, 8, 21)
d2 = pendulum.date(2025, 9, 1)
print(d2 - d1)
print((d2 - d1).in_days())

Calculates the difference between two dates and converts it into days.

Errors and fixes

The failures you are most likely to hit, and what actually resolves them.

pendulum.parsing.exceptions.ParserError: Ensure the datetime string matches the expected format when parsing.
ValueError: Check that date and time components are within valid ranges (e.g., month 1-12, day 1-31).

Best practices

Prefer `pendulum.now()` over `datetime.now()` for timezone-aware datetimes.
Use immutable datetime objects to avoid accidental modifications.
Leverage human-friendly formatting for logging and reporting.
Always specify a timezone when creating or converting datetime objects.
Use duration objects for arithmetic instead of manual calculations.

Background

Why it exists, and what it was reacting to.

Pendulum was created by Sébastien Règne to address the limitations and complexities of Python’s built-in `datetime` module. It focuses on simplicity, correctness, and timezone awareness, making it suitable for applications where robust date and time handling is critical.

Related libraries

Others in Developer Utilities for Python.

Pydantic

Celery

tox

Click

Typer

Rich