pendulum

library3.2.0pypypi✓ verified 35d ago

Pendulum is a Python package designed to simplify datetime manipulation, offering a more intuitive API and robust timezone handling than Python's native `datetime` module. It provides drop-in replacements for standard datetime classes, making integration seamless. Currently at version 3.2.0, Pendulum maintains an active release cadence, often aligning with new Python versions or significant feature enhancements.

serialization

github ↗package ↗homepage ↗docs ↗

Install & Compatibility

Where this runs

tested against v3.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.950 runs

installs and imports cleanly · install 0.0s · import 0.116s · 24.2MB

glibc

py 3.10–3.950 runs

installs and imports cleanly · install 2.0s · import 0.117s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Pendulum's `datetime` (accessed via `pendulum.datetime`) is the primary class and a drop-in replacement for the native `datetime.datetime`, offering enhanced features like automatic timezone awareness.

import pendulum dt = pendulum.datetime(2026, 3, 28, 10, 0, 0, tz='UTC')

Use `pendulum.now()` to get the current datetime, optionally specifying a timezone.

import pendulum current_time = pendulum.now('Europe/Paris')

Automatically parses various date and time string formats.

import pendulum dt = pendulum.parse('2026-03-28T10:00:00+02:00')

This quickstart demonstrates how to create timezone-aware `DateTime` objects, perform common operations like adding time, calculating human-readable differences, and converting between timezones.

import pendulum # Get current time in a specific timezone now_paris = pendulum.now('Europe/Paris') print(f"Current time in Paris: {now_paris}") # Create a specific datetime birthday = pendulum.datetime(1990, 7, 15, tz='America/New_York') print(f"My birthday: {birthday}") # Add time next_week = now_paris.add(weeks=1, days=2) print(f"Next week and two days: {next_week}") # Calculate difference in a human-readable format diff = next_week.diff_for_humans(now_paris) print(f"Difference: {diff}") # Convert to another timezone now_london = now_paris.in_timezone('Europe/London') print(f"Current time in London: {now_london}")

Debug

Known footguns

breakingPendulum 3.0.0 dropped support for Python 2.7, 3.5, 3.6, and 3.7. Version 3.1.0 further dropped support for Python 3.8. The library now requires Python >= 3.9.

breakingThe `Period` class and its associated `period` helper were renamed to `Interval` and `interval` respectively in Pendulum 3.0.0.

breakingThe default string representation (`str(dt)`) of `DateTime` instances changed in 3.0.0 to align with Python's standard library `datetime` output (e.g., from `T` separator to space).

breakingExisting testing helpers like `pendulum.test()` and `pendulum.set_test_now()` were removed in 3.0.0. New testing helpers, which rely on the `time-machine` library, were introduced and require installing Pendulum with the `[test]` extra (e.g., `pip install "pendulum[test]"`).

gotchaThe `tz` argument for `pendulum.datetime()` is keyword-only since Pendulum 2.x, differing from Python's native `datetime` constructor.

deprecatedThe `Timezone` class in Pendulum 3.0.0 now relies on Python's native `zoneinfo.ZoneInfo` class (available from Python 3.9+). While not a direct breaking change, users on older Python versions (not applicable for Pendulum 3.x's requirements) previously relied on Pendulum's internal timezone handling which has been streamlined.

deprecatedThe `pytz` dependency was removed in Pendulum 3.2.0, streamlining timezone management to rely on standard library features (`zoneinfo`).

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

16 hits · last 30 days

gptbot

amazonbot

ahrefsbot