whenever

library0.10.5pypypi✓ verified 28d ago

Whenever is a modern datetime library for Python, aiming to provide an intuitive and consistent API for working with dates and times, with a focus on correctness and ease of use. It is currently at version 0.10.0 and has an active development cadence with regular releases.

serialization

pip install whenever

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · WHENEVER

whenever

serializationpythonv0.10.5

Install

2.0s avg

Import

21ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.10.5 · 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.95 runs

installs and imports cleanly · install 0.0s · import 0.022s · 21MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.0s · import 0.020s · 21MB

19MB installed

● package 19MB

Code

Verified usage

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

ZonedDateTime

✓ from whenever import ZonedDateTime

OffsetDateTime

✓ from whenever import OffsetDateTime

LocalDateTime

✓ from whenever import LocalDateTime

Date

✓ from whenever import Date

Time

✓ from whenever import Time

now

✓ from whenever import now

today

✓ from whenever import today

ItemizedDelta

✓ from whenever import ItemizedDelta

✗ from whenever import DateTimeDelta

DateTimeDelta and DateDelta were removed in 0.10.0, replaced by ItemizedDelta and ItemizedDateDelta.

This quickstart demonstrates how to get current datetimes in the local system timezone or a specified timezone, create a specific date, add durations using the new keyword arguments for flexible delta calculations, and calculate differences between datetimes.

import whenever # Get the current datetime in the system's local timezone local_now = whenever.now() print(f"Local Now: {local_now}") # Get current UTC datetime utc_now = whenever.now('UTC') print(f"UTC Now: {utc_now}") # Get current datetime in a specific timezone paris_now = whenever.now('Europe/Paris') print(f"Paris Now: {paris_now}") # Create a specific date my_date = whenever.date(2023, 10, 27) print(f"My Date: {my_date}") # Add 2 years and 3 months to a datetime # Use the new add method with keyword arguments future_datetime = utc_now.add(years=2, months=3) print(f"Future Datetime (UTC): {future_datetime}") # Calculate difference between two datetimes using 'until' delta = utc_now.until(future_datetime) print(f"Delta: {delta}")

Debug

Known issues

breakingThe `DateTimeDelta` and `DateDelta` classes were removed in version 0.10.0. They have been replaced by `ItemizedDelta` and `ItemizedDateDelta` respectively. The helper functions `years()`, `months()`, `weeks()`, `days()` for creating calendar deltas are also deprecated.

fix

Migrate to `whenever.ItemizedDelta` or `whenever.ItemizedDateDelta`. For simple additions/subtractions, prefer using `add(years=X, months=Y)` methods directly on datetime objects, or `subtract()`.

affects: >=0.10.0

breakingThe `SystemDateTime` class was removed in version 0.9.0. Its functionality has been fully integrated into `ZonedDateTime`, which now serves as the canonical class for all timezone-aware datetimes, including those based on the system's local timezone.

fix

Replace usages of `SystemDateTime` with `whenever.ZonedDateTime`. For example, `SystemDateTime.now()` becomes `whenever.ZonedDateTime.now()` (or `whenever.now()`), which defaults to the system's local timezone.

affects: >=0.9.0

deprecatedThe top-level calendar delta helper functions (`whenever.years()`, `whenever.months()`, `whenever.weeks()`, `whenever.days()`) were deprecated in 0.10.0.

fix

Instead of `whenever.now() + whenever.years(1)`, use the more explicit `whenever.now().add(years=1)`. For more complex deltas, use `whenever.ItemizedDelta` directly: `whenever.ItemizedDelta(years=1, months=2)`.

affects: >=0.10.0

gotchaBe mindful of the distinction between `LocalDateTime`, `OffsetDateTime`, and `ZonedDateTime`. `LocalDateTime` is timezone-naive, `OffsetDateTime` has a fixed UTC offset, and `ZonedDateTime` is timezone-aware and handles Daylight Saving Time (DST) changes.

fix

Always use `whenever.ZonedDateTime` for representing specific points in time across different geographic regions or when dealing with DST. Use `LocalDateTime` only when a date and time are sufficient without timezone context, or `OffsetDateTime` for fixed UTC offsets.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'whenever'

The `whenever` library has not been installed in your Python environment.

fix

pip install whenever

AttributeError: module 'whenever' has no attribute 'Datetime'

The `Datetime` class is not directly available as an attribute of the top-level `whenever` module and must be imported explicitly.

fix

from whenever import Datetime

AttributeError: 'Datetime' object has no attribute 'strftime'

The `whenever.Datetime` object uses `to_string()` for formatting instead of the standard `datetime.strftime()` method.

fix

from whenever import Datetime
d = Datetime.now()
formatted_string = d.to_string('%Y-%m-%d %H:%M:%S')

ValueError: time data '27-10-2023' does not match format '%Y-%m-%d'

The provided date string does not conform to the specified format string when using `Datetime.from_string()`.

fix

from whenever import Datetime
date_obj = Datetime.from_string('27-10-2023', '%d-%m-%Y')

TypeError: expected <class 'whenever.zone.Zone'> for keyword argument 'zone', got <class 'pytz.tz.DstTzInfo'>

The `whenever` library expects its own `whenever.Zone` objects for timezone specifications, not `pytz` or `zoneinfo` objects.

fix

from whenever import Datetime, Zone
date_obj = Datetime.now(zone=Zone.from_name('America/New_York'))

Upgrade

Version history

0.10.5latest on PyPI · released Aug 7, 2026

Audit

Dependencies

pytz-works-for-all-timezonesrequiredProvides robust timezone data and functionality, wrapping pytz and tzdata.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ariebovenberg/whenever ↗

packagehttps://pypi.org/project/whenever/ ↗

docshttps://whenever.readthedocs.io ↗

changeloghttps://github.com/ariebovenberg/whenever/blob/main/CHANGELOG.md ↗