---
id: jdatetime
version: "6.1.0"
license: PSF-2.0
license_treatment: permissive
maintenance: active
---

# jdatetime — Jalali datetime binding for python

License: permissive · Maintenance: active · Downloads: 357.9K/mo

## What it is and what it does

jdatetime is a drop-in Jalali calendar replacement for Python's datetime module, designed for applications that need to work with the Iranian calendar system. It provides date and datetime objects that behave identically to their standard library counterparts, but represent dates in the Jalali calendar instead of the Gregorian calendar. The package includes bidirectional conversion between Gregorian and Jalali dates, leap-year detection, and locale support for displaying dates in Farsi.

The library is built on top of jalali-core and follows Python's datetime API closely, so developers familiar with the standard library can use it with minimal learning curve. It supports per-instance and process-wide locale configuration, making it suitable for applications that need to display dates in both English and Farsi, or that serve users in different locales within the same process.

Use it for:

- Build applications for Iranian users that display dates in the Jalali calendar and Farsi language.
- Convert between Gregorian and Jalali dates when integrating with systems that use both calendar systems.
- Schedule events and store timestamps using the Iranian calendar in databases or APIs.
- Generate reports or invoices with dates formatted in the Jalali calendar for Persian-speaking markets.
- Handle date arithmetic while staying within the Jalali calendar system.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

jdatetime provides a Jalali (Persian) calendar implementation that mirrors Python's standard datetime module, allowing you to work with dates and times in the Iranian calendar system.

Yes. jdatetime is actively maintained, has no known vulnerabilities, installs with minimal friction, and fills a clear need for Persian calendar support. The permissive PSF-2.0 license and support for modern Python versions make it a safe choice for production use in applications serving Iranian users or handling Jalali dates.

## Install

pip install jdatetime
uv add jdatetime
poetry add jdatetime

## Installing jdatetime

Before you install: Low friction installation with a single runtime dependency (jalali-core). The project is actively maintained with a recent release and steady commit activity.

License in practice: Licensed under PSF-2.0 (permissive), allowing free use, modification, and distribution with minimal restrictions.

Quickstart:

pip install jdatetime

import jdatetime

# Get current Jalali date and time
print(jdatetime.datetime.now())
print(jdatetime.date.today())

# Convert from Gregorian
gregorian_date = jdatetime.date.fromgregorian(day=1, month=1, year=1)
print(gregorian_date)

Requires Python 3.9 or later.

Verify before relying:

- Whether locale support works reliably across all supported Python versions.
- Performance characteristics when handling large volumes of date conversions or arithmetic operations.
- Thread-safety guarantees for the per-thread locale setting mechanism mentioned in the documentation.

## Package facts

- License: PSF-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 357.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

jalali calendar datetime, persian date time library, iranian calendar python, gregorian to jalali conversion, farsi date formatting, jalali date arithmetic, persian calendar support, calendar, localization, persian

[View on SkillFed](https://skillfed.io/packages/jdatetime) · [View on PyPI](https://pypi.org/project/jdatetime/)