Skip to main content

Accurate Hijri-Gregorian date converter based on the Umm al-Qura calendar

Project description

A Python package to convert accurately between Hijri and Gregorian dates using the Umm al-Qura calendar of Saudi Arabia.

Build Status Coverage Status Docs Status Python version support PyPI Package version License


  • Accurate and tested conversion.
  • Optimized code performance compared to similar packages.
  • Intuitive, clean, and easy-to-use interface.
  • Most of methods and formats are similar to those of standard library.
  • Multilingual representation of weekday names, months, and calendar notations.
  • Easily extendable to support other natural languages.
  • Rich comparison between dates.
  • Validation of input dates.
  • Works on Python 3.6+ with zero dependencies.
  • Thoroughly tested on all supported python versions.


$ pip install -U hijri-converter

Basic Usage

from hijri_converter import convert

g = convert.Hijri(1403, 2, 17).to_gregorian()
# 1982-12-02

h = convert.Gregorian(1982, 12, 2).to_hijri()
# 1403-02-17

Online Tool

The following is a simple online conversion tool that was developed to convert between Hijri and Gregorian dates using the latest version of Hijri Converter package:


Please see for full documentation of this package, including overview, benchmarking, usage examples and API reference.


Contributions are welcome! See CONTRIBUTING.rst for more info.


The main author is Mohammed Alshehri — @dralshehri.


Thanks to R.H. van Gent for inspiration and help.


This package is distributed under an MIT license. See LICENSE.

Change Log


This version has more accurate conversion and better internal code. Details are as follows:

  • Dropped support for the years before 1343 AH because the Umm al-Qura calendar was not established then.
  • Added validate parameter to Hijri object for optional disabling of Hijri date validation and improving performance.
  • Verified conversion against original references and updated the month_starts tuple for more accurate conversion.
  • Improved Hijri object rich comparison methods.
  • Improved date validation methods for better performance and readability.
  • Made the Hijri object hashable by adding a custom __hash__ method.
  • Refactored many internal methods (not affecting the API).
  • Other minor fixes, enhancements and performance boost.


In short, this version supports only lunar Hijri calendar on Python 3.6+, and the conversion is in complete agreement with the official Umm al-Qura calendar. Details are as follows:

  • Renamed the package to hijri-converter.
  • Dropped support for the solar Hijri calendar.
  • Dropped support for Python 3.5.
  • Refactored localization and module.
  • Updated month_starts tuple in alignment with the Umm al-Qura calendar.
  • Added fromdate() classmethod to Gregorian object.
  • Added notation() method to Hijri and Gregorian objects.
  • Added more methods to Gregorian object including slashformat(), month_name(), day_name() and to_julian().
  • Renamed month_days() method of Hijri object to month_length().
  • Changed formatted string to use f-strings.
  • Improved documentation and examples.
  • Updated unit tests.
  • Fixed other minor issues and typos.


  • Added fromisoformat() classmethod to Hijri object.
  • Added support for rich comparison between Hijri dates.
  • Updated documentation and testing code.
  • Other minor fixes and enhancements.


  • Refactored conversion methods to improve performance.
  • Changed date validation back to be the default and removed optional parameter.
  • Added to_julian() method to Hijri object.
  • Updated documentation and testing code.
  • Other minor fixes and enhancements.


  • Fixed a bug in range validation for the Gregorian date.
  • Changed generic typing to built-in types.
  • Added more tests to cover the solar calendar.
  • Improved code structure and documentation.


  • Improved documentation and changelog.


  • Fixed README file.


  • Added documentation directory with an online version.
  • Changed date input validation to be optional and disabled by default.
  • Improved code readability and performance.
  • Other minor fixes and enhancements.


  • Added slashformat() method to Hijri object.
  • Improved date validation code.
  • Fixed some typos in documentation and docstrings.


  • Improved examples and documentation.


  • First release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for hijri-converter, version 2.1.0
Filename, size File type Python version Upload date Hashes
Filename, size hijri_converter-2.1.0-py3-none-any.whl (13.8 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size hijri-converter-2.1.0.tar.gz (15.2 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page