Quickstart

This document should walk you through everything you need to get started with hdate.

Getting the Hebrew date

Suppose we want to get today’s Hebrew date.

>>> from datetime import date
>>> from hdate import HebrewDate
>>> from hdate.translator import set_language

>>> today = date(2025, 1, 15)
>>> set_language("en")
>>> heb_date = HebrewDate.from_gdate(today)
>>> print(heb_date)
15 Tevet 5785

Let’s see how much time is left until Pesach 😧

>>> from hdate import Months

>>> pesach = HebrewDate(0, Months.NISAN, 15)
>>> time_to_pesach = pesach - heb_date  # Returns a timedelta object

>>> print(time_to_pesach.days)
88

Better start cleaning 😉

The HebrewDate object is similar to Python’s built-in datetime.date object. It’s responsibility is to represent a Hebrew date and allow date comparisons and calculations. To get more information about a specific date, have a look at the HDateInfo object.

Note

By setting the year value to 0, the HebrewDate is considered to be relative. All calculations and comparisons are done on the assumption that both objects use the same year value.

See more on that later for special cases of leap years and possible non-existing days.

Getting the Gregorian date

We want to know when is Rosh Hashana for the upcoming year (5786).

>>> rosh_hashana = HebrewDate(5786, Months.TISHREI, 1)
>>> gdate = rosh_hashana.to_gdate()
>>> print(gdate)
2025-09-23

We can also know what the day of the week is:

>>> day_of_week = rosh_hashana.dow()
>>> print(day_of_week)
Tuesday

Getting the string value in a different language

All objects in hdate can have their language changed by calling the set_language() method. Currently supported are Hebrew, English and French. Languages are set globally and should be formatted according to RFC 5646. The default language is Hebrew.

>>> from hdate.translator import set_language
>>> set_language("he")
>>> print(str(day_of_week))
יום שלישי
>>> set_language("fr")
>>> print(str(day_of_week))
Mardi

Zmanim - getting the times of a given day

To get the times of a given day, we’ll need first to define a location. The location requires a name, latitude, longitude, timezone and elevation.

>>> from hdate import Location

>>> location = Location("Home", 32.09, 34.89, "Asia/Jerusalem", 54)

Now we can go ahead and ask hdate for the Halachic times for a given date.

>>> from hdate import Zmanim

>>> zmanim = Zmanim(date(2025, 1, 15), location)
>>> zmanim.alot_hashachar.local
datetime.datetime(2025, 1, 15, 5, 25, tzinfo=zoneinfo.ZoneInfo(key='Asia/Jerusalem'))

To get a list of the supported zmanim, you’ll want to inspect the keys returned by the zmanim property.

>>> zmanim.zmanim.keys()
dict_keys(['alot_hashachar', 'talit_and_tefillin', 'netz_hachama', ...

You can also get a nice printout by calling str on the Zmanim object.

Warning

Although we try as much as possible to be correct with our code trying to calculate the Halachic times, we do not take ANY responsibility whatsoever for the reliance on these calculations. When in doubt, please contact your local Halachic authority.

The HDateInfo object

If you want more information on a specific date like Parshat Hashavua, Holidays, the Daf Yomi, or the current Omer count, you’ll want to initialize a HDateInfo object.

The HDateInfo object, accepts a date (either Gregorian or Hebrew), a boolean that specifies whether the information should be calculated according to diaspora or not, and language (defaults to Hebrew).

>>> from hdate import HDateInfo
>>> set_language("en")
>>> today = HDateInfo(today, diaspora=False)
>>> print(today.parasha)
Shemot
>>> today.is_holiday
False
>>> print(today.daf_yomi)
Sanhedrin 29
>>> pesach = today.upcoming_yom_tov
>>> pesach.holidays
[Holiday(type=<HolidayTypes.YOM_TOV: 1>, name='pesach', date=(<Months.NISAN: 9>, 15), date_functions_list=[], israel_diaspora='')]
>>> print(pesach.holidays[0])
Pesach
>>> pesach.next_day.omer
Omer(date=HebrewDate(year=5785, month=<Months.NISAN: 9>, day=16), total_days=1, day=1, week=0, nusach=<Nusach.SFARAD: 2>)