Pendulum

3.2.0 verified Tue May 12 auth: no python install: verified quickstart: verified

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.

pip install pendulum

Common errors

error ModuleNotFoundError: No module named 'pendulum' ↓

cause The 'pendulum' library is not installed in the Python environment where the code is being executed, or the environment is not correctly activated.

fix

Ensure Pendulum is installed in your active Python environment using pip: pip install pendulum.

error AttributeError: 'DateTime' object has no attribute 'nanosecond' ↓

cause This error often occurs when a `pendulum.DateTime` object is passed to a library (like Pandas) that expects a native Python `datetime` object or has specific attribute expectations not present in `pendulum.DateTime` directly.

fix

Convert the pendulum.DateTime object to a standard datetime.datetime object before passing it to the external library: my_pendulum_dt.in_timezone('UTC').replace(tzinfo=None) # for naive datetime or my_pendulum_dt.in_timezone('UTC')._datetime # for timezone-aware datetime.datetime (though direct attribute access is generally discouraged, to_datetime_string() or isoformat() can also be used depending on the need to represent it as a string).

error pendulum.parsing.exceptions.ParserError: Unable to parse string [...] ↓

cause The `pendulum.parse()` method was unable to interpret the provided string into a valid date and time, often because the string format is not natively supported or is ambiguous.

fix

For non-standard or complicated strings, use pendulum.from_format() with an explicit format string, or pass exact=False (formerly strict=False) to pendulum.parse() to allow it to fall back on dateutil parsing: pendulum.parse('2023-01-01 10:30:00', exact=False) or pendulum.from_format('2023/01/01', 'YYYY/MM/DD').

error TypeError: datetime() got an unexpected keyword argument 'dst_rule' ↓

cause The `dst_rule` keyword argument was removed in Pendulum 3.0.0, which introduced breaking changes to simplify the API and improve standard library compatibility.

fix

Remove the dst_rule argument from your pendulum.datetime() calls. Pendulum 3.x handles DST transitions implicitly and correctly without this explicit parameter. If specific DST behavior is needed, leverage in_timezone() or ensure your timezone strings are correctly specified.

error AttributeError: 'DateTime' object has no attribute 'add_timedelta' ↓

cause The `add_timedelta` method was deprecated and removed in Pendulum 2.x and later, replaced by the more intuitive `add()` and `subtract()` methods, or direct arithmetic.

fix

Use the add() method with keyword arguments for time units or direct addition with datetime.timedelta objects: dt.add(hours=1, minutes=30) or dt + timedelta(hours=1, minutes=30).

Warnings

breaking Pendulum 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. ↓

fix Upgrade your Python environment to 3.9 or higher if you intend to use Pendulum 3.x.

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

fix Update all instances of `Period` to `Interval` and `pendulum.period()` to `pendulum.interval()` in your code.

breaking The 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). ↓

fix If your code relies on the exact string format, explicitly use `dt.isoformat()` for ISO 8601, or `dt.format('...')` with custom tokens to achieve the desired output.

breaking Existing 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]"`). ↓

fix Migrate to the new testing helpers and ensure the `[test]` extra is installed if you use time-traveling features.

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

fix Always pass the timezone using the `tz=` keyword argument: `pendulum.datetime(2026, 3, 28, tz='UTC')`.

deprecated The `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. ↓

fix This change primarily affects internals and improves compatibility. Ensure your Python environment meets the `>=3.9` requirement for optimal timezone handling.

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

fix No direct action required unless you were explicitly relying on `pytz` through Pendulum, in which case you should switch to `zoneinfo` or Pendulum's native timezone utilities.

Install

pip install "pendulum[test]"

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) test - - 0.13s 24.2M

3.10 alpine (musl) pendulum - - 0.10s 24.0M

3.10 slim (glibc) test - - 0.10s 24M

3.10 slim (glibc) pendulum - - 0.12s 24M

3.11 alpine (musl) test - - 0.23s 26.3M

3.11 alpine (musl) pendulum - - 0.19s 26.2M

3.11 slim (glibc) test - - 0.17s 26M

3.11 slim (glibc) pendulum - - 0.14s 26M

3.12 alpine (musl) test - - 0.12s 18.2M

3.12 alpine (musl) pendulum - - 0.12s 18.0M

3.12 slim (glibc) test - - 0.21s 18M

3.12 slim (glibc) pendulum - - 0.17s 18M

3.13 alpine (musl) test - - 0.11s 17.8M

3.13 alpine (musl) pendulum - - 0.13s 17.6M

3.13 slim (glibc) test - - 0.16s 18M

3.13 slim (glibc) pendulum - - 0.16s 18M

3.9 alpine (musl) test - - 0.10s 23.7M

3.9 alpine (musl) pendulum - - 0.10s 23.6M

3.9 slim (glibc) test - - 0.09s 24M

3.9 slim (glibc) pendulum - - 0.11s 24M

Imports

datetime
wrong
```
from datetime import datetime
dt = datetime(2026, 3, 28, 10, 0, 0)
```
correct
```
import pendulum
dt = pendulum.datetime(2026, 3, 28, 10, 0, 0, tz='UTC')
```
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.
now
```
import pendulum
current_time = pendulum.now('Europe/Paris')
```
Use `pendulum.now()` to get the current datetime, optionally specifying a timezone.

parse

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

Automatically parses various date and time string formats.

Quickstart verified last tested: 2026-04-23

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}")