Pendulum

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 Install core library
• pip install "pendulum[test]" Install with testing helpers

Imports

• datetime

  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

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