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


  • Added dmyformat() to return dates in DD/MM/YYYY format.
  • Deprecated slashformat() method to be replaced by dmyformat() method.
  • Fixed PyPI package not including a required file. Issue #3 by @PureTryOut.
  • Fixed some typos.
  • Updated tests.


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.1
Filename, size File type Python version Upload date Hashes
Filename, size hijri_converter-2.1.1-py3-none-any.whl (14.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size hijri-converter-2.1.1.tar.gz (32.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page