Library / SDK
python-pendulum/pendulum avatar
python-pendulum/pendulum

pendulum makes every datetime aware, then charges you at the type() check

Python datetimes made easy

6,684 stars503 forksPythonMIT

At a glance

What is it?
pendulum is a drop-in subclass of the standard datetime whose instances are always timezone-aware, default to UTC, and can skip wall clock times a daylight saving jump removed. The price is a short list of libraries that inspect object types instead of reading values.
Who is it for?
pendulum is the right choice when your code passes datetimes across process boundaries and you want awareness guaranteed rather than remembered, provided you are on Python 3.10 or newer and can audit your dependencies for type() checks. It is the wrong choice if sqlite3, mysqlclient, PyMySQL or Django sit in your write path and you cannot add adapters, since the offset handling there is a documented failure rather than a rough edge.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 27 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • python-pendulum/pendulum6,684 ★ · +10
Star history
Repository2026-09-232026-11-22
python-pendulum/pendulum6.7k6.7k

10 Stars in the last 60 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Every instance is aware, and UTC is the default you inherit

The central design decision is stated in one line: pendulum removes the notion of naive datetimes, and every instance is timezone-aware and in UTC by default. That is the whole ergonomic pitch, and the first use looks like this:

python
>>> import pendulum
>>> now_in_paris = pendulum.now('Europe/Paris')
>>> now_in_paris
'2016-07-04T00:49:58.502116+02:00'

Because awareness is guaranteed rather than requested, switching is a method rather than a constructor argument, and arithmetic reads in the direction you want:

python
>>> now_in_paris.in_timezone('UTC')
'2016-07-03T22:49:58.502116+00:00'
>>> past = pendulum.now().subtract(minutes=2)
>>> past.diff_for_humans()
'2 minutes ago'

Subtracting two instances gives a timedelta subclass with the same treatment, which is where `delta.hours` and `delta.in_words(locale='en')` come from.

A wall clock time that never happened resolves forward to 03:30

The interesting arithmetic is at a daylight saving boundary, and the library shows both halves of it. Asking for a local time that the clock skipped does not raise:

python
>>> pendulum.datetime(2013, 3, 31, 2, 30, tz='Europe/Paris')
'2013-03-31T03:30:00+02:00'

The inline comment in the example names the case: 2:30 does not exist on that date in that zone. pendulum moves it forward rather than rejecting it, so a value you computed from a form or a feed becomes 03:30 with the new offset attached.

One microsecond before the transition the offset is still the old one, and adding a microsecond carries the clock across the jump:

python
>>> just_before = pendulum.datetime(2013, 3, 31, 1, 59, 59, 999999, tz='Europe/Paris')
'2013-03-31T01:59:59.999999+01:00'

The result is 03:00 with a different offset, which is the part a naive implementation gets wrong.

The Rust extension is optional, and PENDULUM_EXTENSIONS=0 proves it

The repository holds a `rust/` directory alongside `src/`, and the packaging configuration names a native module `pendulum._pendulum` built with the `pyo3/extension-module` feature through maturin. That sounds like a mandatory compiled dependency, and it is not treated as one. The Makefile runs the suite twice:

bash
PENDULUM_EXTENSIONS=0 poetry run pytest -q tests
poetry run pytest -q tests

The first pass switches the extension off, the second leaves it on, so both paths are exercised on every test run. `make clean` removes `src/pendulum/*.so` to get back to a state without the compiled artifact. A `time-machine` dependency appears in the test group and in an optional `test` extra, with the extra pinned to 3.x and excluded on PyPy.

So the extension is an optimisation with a bypass, not the implementation. If you package pendulum somewhere without a Rust toolchain, the Makefile's separate `lint-rust` and `format-rust` targets tell you the Rust side is treated as its own component with its own cargo fmt and clippy passes.

The checkout build runs Poetry groups, then maturin develop

The install steps in the README are aimed at working on the code, not at consuming it. Cloning and installing dependencies is all it takes:

bash
git clone [email protected]:sdispater/pendulum.git
poetry install

For a working development environment the Makefile is more selective:

bash
poetry install --only main --only test --only typing --only build --only lint
poetry run maturin develop

The group names are worth knowing because they mirror the repository's other moving parts: a doc group with mkdocs, pymdown-extensions, pygments and markdown-include, a typing group holding mypy and types-python-dateutil, a lint group on prek, a benchmark group on pytest-codspeed, and a dev group with babel, cleo and tox. A `tox.ini` sits in the root next to `prek.toml`, so `make lint` runs mypy and then the pre-commit hooks across all files.

For an end user this is a lot of machinery, and the README does not spell out a plain pip install line.

The type() check is the seam, and sqlite3 is where it shows first

pendulum subclasses datetime, which is what makes replacement cheap, and that inheritance is also where replacement breaks. Libraries that identify objects with the `type()` function do not see a datetime subclass as a datetime. The README names sqlite3 as the first case and gives the adapter:

python
from pendulum import DateTime
from sqlite3 import register_adapter

register_adapter(DateTime, lambda val: val.isoformat(' '))

The same seam shows up in `mysqlclient` (the former MySQLdb) and in PyMySQL, where the fix is to insert entries into each driver's conversion table, pointing at `MySQLdb.converters.DateTime2literal` and `pymysql.converters.escape_datetime` respectively.

The important caveat is stated in the same paragraph that introduces the list: it is explicitly non-exhaustive. Each additional driver you bring in is another `type()` call to audit, and the failure shows up at the database boundary rather than at import time.

Django cannot store the offset that isoformat() always emits

Django is the case that is not a type() check at all, and it is the one most likely to surprise a team. Django uses `isoformat()` when it stores datetimes in the database. Because pendulum instances are always aware, that call always returns the offset, and the offset is what raises the error, at least on MySQL databases.

The documented escape hatches are two: write your own `DateTimeField` subclass, or reuse the MySQLdb adapter workaround. The field subclass shown overrides `value_to_string`, pulling the value out of the object and converting a pendulum DateTime with `to_datetime_string()` so the offset never reaches the column:

python
from django.db.models import DateTimeField as BaseDateTimeField
from pendulum import DateTime

The field the project shows relies on `value_from_object`, an isinstance check against DateTime, and returns an empty string for None. Note the difference in kind from the sqlite3 case: there the driver rejects the type, here the framework accepts it and then cannot represent it.

New locales come from clock and split across two files

Localisation is where contributions are most welcome, and the mechanism is unusually explicit. A locale that does not exist yet is generated with a bundled utility called `clock`:

bash
./clock locale create <your-locale>

It creates a directory under `pendulum/locales` named after the locale, holding exactly two files: `locale.py` and `custom.py`. The division is strict. `locale.py` carries the translations from the CLDR database and must not be modified. `custom.py` holds the data pendulum needs that CLDR does not provide, and the project's own `en` custom file is offered as the reference for what belongs there.

Two consequences follow. Human-readable output, which is what `diff_for_humans` and `in_words(locale=...)` produce, draws on this data, so a locale you add is the locale you can render phrases in. And the expectation is a test alongside the change: the instructions ask for tests for the created or modified locale, which means every locale addition is a code change with a verification burden attached.

Two floors and one incomplete list decide whether this fits your build

The packaging metadata is small and gives you the adoption decision in three lines. `requires-python` is `>=3.10`, the classifiers run from 3.10 through 3.14, and there are exactly two runtime dependencies: `python-dateutil>=2.6` and `tzdata>=2020.1`.

The release history is worth reading before pinning. Versions 3.1.0, 3.2.0 and 3.3.0 shipped on 2025-04-19, 2026-01-30 and 2026-10-12, and the last push to the repository was on 2026-10-26. Work is landing after the latest tag, so the default branch and the newest release are not the same code.

Editorial conclusion

pendulum is the right choice when your code passes datetimes across process boundaries and you want awareness guaranteed rather than remembered, provided you are on Python 3.10 or newer and can audit your dependencies for type() checks. It is the wrong choice if sqlite3, mysqlclient, PyMySQL or Django sit in your write path and you cannot add adapters, since the offset handling there is a documented failure rather than a rough edge. Check three things before adopting it: that your dependency tree has no other library comparing types with type(), that your database driver has an adapter registered for DateTime, and that any locale you need for diff_for_humans and in_words already has a custom.py.

Frequently asked questions

Is pendulum a drop-in replacement for the standard datetime class?

Yes, with documented exceptions. DateTime inherits from datetime, so existing datetime instances can be swapped for DateTime ones, and pendulum also extends timedelta with more intuitive methods. The stated exceptions are libraries that inspect types with the type() function, such as sqlite3 and PyMySQL.

How do you store a pendulum DateTime in sqlite3?

Register an adapter for the DateTime class, because sqlite3 uses type() to decide what it is holding: from pendulum import DateTime from sqlite3 import register_adapter register_adapter(DateTime, lambda val: val.isoformat(' ')) The same approach applies to mysqlclient and PyMySQL through their converter tables.

What does pendulum do with a local time that a DST jump skipped?

It moves the value forward instead of raising. pendulum.datetime(2013, 3, 31, 2, 30, tz='Europe/Paris') returns 2013-03-31T03:30:00+02:00, because 2:30 does not exist in that zone on that date. Adding one microsecond to a moment just before the transition also carries the clock and offset across the jump.

Which Python versions does pendulum support?

Python 3.10 and newer. The packaging metadata sets requires-python to >=3.10 and carries classifiers for 3.10, 3.11, 3.12, 3.13 and 3.14. The test extra also excludes PyPy for its time-machine dependency.

Does pendulum require its compiled Rust extension?

The Makefile test target runs the suite twice, once with PENDULUM_EXTENSIONS=0 and once without, so both the pure Python path and the compiled module pendulum._pendulum are exercised. The extension is built through maturin with the pyo3 extension-module feature, and make clean deletes src/pendulum/*.so.

How do you add a new locale to pendulum?

Run ./clock locale create <your-locale>, which generates a directory under pendulum/locales containing locale.py and custom.py. locale.py holds the CLDR translations and must not be changed; custom.py is where pendulum-specific data goes. The project's instructions ask for tests with any new or modified locale.

Official sources

  1. License: MIT
  2. Project website
  3. python-pendulum/pendulum on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/python-pendulum-pendulum.svg)](https://hysenlabs.com/projects/python-pendulum-pendulum)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/python-pendulum-pendulum.svg)](https://hysenlabs.com/projects/python-pendulum-pendulum)

Was this useful?