jdatetime - Jalali (Persian) datetime library

5.2.0 verified Mon Apr 27 auth: no python

jdatetime provides Jalali (Persian, Solar Hijri) calendar support for Python, mirroring Python's datetime interface. Current version 5.2.0 supports Python >=3.9. Release cadence is irregular; major versions drop old Python versions.

pip install jdatetime

Common errors

error AttributeError: module 'jdatetime' has no attribute 'datetime' ↓

cause Importing jdatetime alone does not expose datetime class directly; you must import from jdatetime.

fix

Use from jdatetime import datetime or import jdatetime; jdatetime.datetime.

error TypeError: can't compare datetime.datetime to jdatetime.datetime ↓

cause jdatetime and standard datetime types are incompatible for comparison.

fix

Convert one side: jdt.togregorian() or compare after conversion.

error ValueError: day is out of range for month ↓

cause Jalali months have different lengths; using Gregorian day numbers directly can cause this.

fix

Ensure you are using correct Jalali month/day values when constructing jdatetime objects.

Warnings

breaking In jdatetime >=5.0.0, the strftime/strptime escape handling changed: %% is treated as an escape sequence. Previously %% might not have been handled correctly. ↓

fix Review code that uses %% in format strings; ensure it is intended as a literal percent.

breaking Python 3.8 support dropped in v5.1.0. jdatetime 5.0.0 was the last version supporting Python 3.8. ↓

fix Upgrade to Python 3.9+ or pin jdatetime to <5.1.0 if stuck on Python 3.8.

gotcha jdatetime.date and jdatetime.datetime are not subclasses of Python's datetime.date/datetime; direct comparison or arithmetic with standard datetime types may raise TypeError or produce unexpected results. ↓

fix Convert via .togregorian() method before mixing with standard datetime objects.

gotcha jdatetime.datetime.fromtimestamp() accepts a POSIX timestamp (seconds since epoch) but returns a Jalali datetime. Many users expect it to return Gregorian. ↓

fix Ensure you need Jalali output; use standard datetime.fromtimestamp() for Gregorian.

deprecated The alias 'JalaliDate' and 'JalaliDatetime' are deprecated since v4.0.0 and may be removed in future versions. ↓

fix Use 'date' and 'datetime' from jdatetime directly.

Imports

jdatetime
wrong
```
from jdatetime import JalaliDatetime
```
correct
```
import jdatetime
```
JalaliDatetime is an alias but import jdatetime is the canonical way.
date
wrong
```
from jdatetime.jalali import JalaliDate
```
correct
```
from jdatetime import date
```
Direct import of date class is simpler; internal module path is not public.
datetime
wrong
```
from jdatetime import JalaliDatetime
```
correct
```
from jdatetime import datetime
```
JalaliDatetime is an alias; datetime is the class name.

Quickstart

Create and format Jalali dates and times.

import jdatetime
today = jdatetime.date.today()
print(today)
dt = jdatetime.datetime(1402, 12, 1, 10, 30, 0)
print(dt.strftime('%Y-%m-%d %H:%M:%S'))