Python Pendulum Date Arithmetic and Duration
Learn how to add and subtract time, calculate differences, and handle timezone-aware arithmetic with Pendulum's DateTime, Duration, and Period objects.

When you need date arithmetic and durations in Python, the Pendulum library provides a DateTime class that makes date manipulation more readable and less error-prone than the standard library's datetime. Pendulum's API is designed around intuitive methods and a clear separation between durations (fixed lengths of time) and periods (spans between two instants). This article covers the core operations: adding and subtracting time, calculating differences, and handling timezone-aware arithmetic.
Adding and Subtracting Durations
Pendulum's DateTime objects support the add() and subtract() methods, which accept a Duration object or keyword arguments for common units. For example, to add three days and two hours to a specific date:
import pendulum
dt = pendulum.datetime(2025, 3, 10, 12, 0, 0)
result = dt.add(days=3, hours=2)
print(result) # 2025-03-13 14:00:00The Duration class is used when you need to reuse a fixed time span. You can create one and apply it to multiple dates:
delay = pendulum.duration(days=1, hours=4)
start = pendulum.datetime(2025, 3, 10, 9, 30)
end = start.add(delay)Subtraction works symmetrically with subtract(). Both methods return a new DateTime instance; Pendulum objects are immutable, so the original is unchanged. This immutability avoids accidental mutation bugs when you pass dates around.
Calculating Differences Between Dates
To find the span between two DateTime instances, use the diff() method. It returns a Period object that exposes the difference in years, months, days, hours, and so on. For example:
start = pendulum.datetime(2025, 1, 1, 0, 0, 0)
end = pendulum.datetime(2025, 3, 1, 12, 30, 0)
period = start.diff(end)
print(period.days) # 59
print(period.hours) # 12diff() also accepts an optional unit argument to get the difference in a specific unit directly, such as start.diff(end, 'hours') returning the total hours as a float. This is useful when you need a single numeric value for calculations.
Duration vs Period: What's the Difference?
Pendulum distinguishes between a Duration and a Period. A Duration represents a fixed amount of time, like 2 hours or 3 days. It is independent of any calendar context. A Period, on the other hand, is the exact span between two specific instants. Because of timezone transitions and daylight saving time, a day can be 23 or 25 hours long. When you subtract two DateTime objects, you get a Period that reflects the actual elapsed time, not just the calendar difference.
# A Duration is fixed
two_hours = pendulum.duration(hours=2)
# A Period is the real span between instants
p = start.diff(end)This distinction matters when you perform arithmetic across DST boundaries. Adding a Duration of 24 hours to a timezone-aware DateTime may not land on the same wall-clock time if a DST shift occurs. Pendulum's behavior here is deliberate: add() with a Duration adds the exact number of seconds, while add() with keyword arguments like days=1 adds one calendar day, preserving the local time where possible.
Timezone-Aware Date Arithmetic
Pendulum DateTime objects are timezone-aware by default. When you create one with pendulum.datetime(), you can pass a timezone name. Arithmetic respects the timezone's rules, which is critical for applications that schedule events across DST changes.
ny = pendulum.datetime(2025, 3, 8, 12, 0, 0, tz='America/New_York')
# Add one day: DST starts on March 9, 2025
next_day = ny.add(days=1)
print(next_day) # 2025-03-09 12:00:00-04:00The wall-clock time remains 12:00, but the UTC offset changes from -05:00 to -04:00. If you instead added pendulum.duration(hours=24), the result would be 13:00 local time because 24 hours of actual time have passed. This distinction is a common source of bugs when migrating from the standard library, which often treats naive datetime arithmetic as if timezones did not exist.
Comparing Date and Time Values
Pendulum DateTime instances support the standard comparison operators (<, >, ==, etc.) and they work correctly across timezones because comparisons are based on the underlying UTC instant. You can also use the is_between() method to check if a date falls within a range:
start = pendulum.datetime(2025, 1, 1)
end = pendulum.datetime(2025, 12, 31)
candidate = pendulum.datetime(2025, 6, 15)
print(candidate.is_between(start, end)) # TrueEquality checks compare the exact instant, so two DateTime objects representing the same moment in different timezones are considered equal. This is usually the behavior you want, but be aware that it differs from comparing wall-clock strings.
Common Pitfalls and Edge Cases
One recurring issue is mixing naive and aware DateTime objects. Pendulum does not allow arithmetic between a naive and an aware object; it raises a TypeError to force you to make the timezone explicit. This is a safety feature, but it means you must consistently attach a timezone to all values in a calculation.
Another edge case is adding months or years. Pendulum's add(months=1) handles month-end rollover explicitly. For example, adding one month to January 31 yields February 28 (or 29 in a leap year), not March 2. This is often the desired behavior for calendar-based scheduling, but it can surprise developers who expect a fixed 30-day span. If you need a fixed number of days, use add(days=30) instead.
Leap years are handled correctly by the underlying date logic, so February 29 plus one year becomes February 28 in a non-leap year.
Performance and Production Considerations
Pendulum's rich API and timezone handling come with a cost compared to the standard library's datetime for very simple operations. If your application performs millions of trivial date additions in a tight loop, the overhead of Pendulum's object model and timezone calculations may be measurable. In most web applications, however, the readability and reduced bug rate outweigh this overhead.
For production use, be deliberate about where you use Pendulum. It is an excellent choice for business logic that involves scheduling, timezone conversion, or human-readable differences. For high-throughput data processing where only the standard library's basic arithmetic is needed, sticking with datetime and timedelta can be more efficient. The decision should be based on the complexity of your timezone rules and the maintainability of the codebase, not on micro-optimizations.
When you do use Pendulum, avoid creating DateTime objects repeatedly in loops; reuse a single instance when possible. Also, be consistent with timezone handling: either always attach a timezone or always use UTC internally and convert only at the boundaries of your application.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.