Pendulum

Common errors

• 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`.

• 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).

• 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')`.

• 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.

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

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

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