Skip to main content

Generate and work with holidays in Python

Project description

A fast, efficient Python library for generating country- and subdivision- (e.g. state or province) specific sets of government-designated holidays on the fly. It aims to make determining whether a specific date is a holiday as fast and flexible as possible. Documentation Status


The latest stable version can always be installed or updated via pip:

$ pip install --update holidays


The documentation is hosted on Read the Docs.

Quick Start

from datetime import date
import holidays

us_holidays = holidays.US()  # this is a dict
# the below is the same, but takes a string:
us_holidays = holidays.country_holidays('US')  # this is a dict

date(2015, 1, 1) in us_holidays  # True
date(2015, 1, 2) in us_holidays  # False
us_holidays.get('2014-01-01')  # "New Year's Day"

The HolidayBase dict-like class will also recognize date strings and Unix timestamps:

'2014-01-01' in us_holidays  # True
'1/1/2014' in us_holidays    # True
1388597445 in us_holidays    # True

Some holidays may be only present in parts of a country:

us_pr_holidays = holidays.country_holidays('US', subdiv='PR')
'2018-01-06' in us_holidays     # False
'2018-01-06' in us_pr_holidays  # True

Please see the documentation for additional examples and detailed information.

Available Countries

We currently support 86 countries. The standard way to refer to a country is by using its ISO 3166-1 alpha-2 code, the same used for domain names. The following countries and their subdivisions are available:

Country Code Subdivisions Available
Angola AO None
Argentina AR None
Aruba AW None
Australia AU States and territories: ACT (default), NSW, NT, QLD, SA, TAS, VIC, WA
Austria AT States: 1, 2, 3, 4, 5, 6, 7, 8, 9 (default)
Azerbaijan AZ None
Bangladesh BD None
Belarus BY None
Belgium BE None
Botswana BW None
Brazil BR States: AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, RJ, RN, RO, RR, RS, SC, SE, SP, TO
Bulgaria BG None
Burundi BI None
Canada CA Provinces and territories: AB, BC, MB, NB, NL, NS NT, NU, ON (default), PE, QC, SK, YU
Chile CL Regions: AI, AN, AP, AR, AT, BI, CO, LI, LL, LR, MA, ML, NB, RM, TA, VS
China CN None
Colombia CO None
Croatia HR None
Curaçao CW None
Cyprus CY None
Czechia CZ None
Denmark DK None
Djibouti DJ None
Dominican Republic DO None
Egypt EG None
Estonia EE None
Ethiopia ET None
Finland FI None
France FR Départements: Métropole (default), Alsace-Moselle, Guadeloupe, Guyane, Martinique, Mayotte, Nouvelle-Calédonie, La Réunion, Polynésie Française, Saint-Barthélémy, Saint-Martin, Wallis-et-Futuna
Georgia GE None
Germany DE States: BB, BE, BW, BY, BYP, HB, HE, HH, MV, NI, NW, RP, SH, SL, SN, ST, TH
Greece GR None
Honduras HN None
Hong Kong HK None
Hungary HU None
Iceland IS None
India IN States: AN, AP, AR, AS, BR, CG, CH, DD, DH, DL, GA, GJ, HP, HR, JH, JK, KA, KL, LA, LD, MH, ML, MN, MP, MZ, NL, OR, PB, PY, RJ, SK, TN, TR, TS, UK, UP, WB
Ireland IE None
Isle of Man IM None
Israel IL None
Italy IT Provinces: AG, AL, AN, AO, AP, AQ, AR, AT, AV, BA, BG, BI, BL, BN, BO, BR, BS, BT, BZ, CA, CB, CE, CH, CL, CN, CO, CR, CS, CT, CZ, EN, FC, FE, FG, FI, FM, FR, GE, GO, GR, IM, IS, KR, LC, LE, LI, LO, LT, LU, MB, MC, ME, MI, MN, MO, MS, MT, NA, NO, NU, OR, PA, PC, PD, PE, PG, PI, PN, PO, PR, PT, PU, PV, PZ, RA, RC, RE, RG, RI, RM, RN, RO, SA, SI, SO, SP, SR, SS, SU, SV, TA, TE, TN, TO, TP, TR, TS, TV, UD, VA, VB, VC, VE, VI, VR, VT, VV; Cities: Barletta, Andria, Trani, Cesena, Forlì, Pesaro, Urbino
Jamaica JM None
Japan JP None
Kazakhstan KZ None
Kenya KE None
Korea KR None
Latvia LV None
Lesotho LS None
Lithuania LT None
Luxembourg LU None
Madagascar MG None
Malawi MW None
Malta MT None
Mexico MX None
Morocco MA None
Mozambique MZ None
Netherlands NL None
Namibia NA None
New Zealand NZ Regions: AUK, CAN, HKB, MBH, NSN, NTL, OTA, STL, TKI, WGN, WTC, CIT; Sub-regions: South Canterbury
Nicaragua NI Departments: MN (default)
Nigeria NG None
North Macedonia MK None
Norway NO None
Paraguay PY None
Peru PE None
Poland PL None
Portugal PT Use subd=’Ext’ to include holidays most people have off
Romania RO None
Russia RU None
Saudi Arabia SA None
Serbia RS None
Singapore SG None
Slovakia SK None
Slovenia SI None
South Africa ZA None
Spain ES Autonomous communities: AN (Andalucía), AR (Aragón), AS (Asturias), CB (Cantabria), CE (Ceuta), CL (Castilla y León), CM (Castilla La Mancha), CN (Canarias), CT (Cataluña), EX (Extremadura), GA (Galicia), IB (Islas Baleares), MC (Murcia), MD (Madrid), NC (Navarra), PV (País Vasco), RI (La Rioja), VC (Comunidad Valenciana)
Swaziland SZ None
Sweden SE None
Switzerland CH Cantons: AG, AR, AI, BL, BS, BE, FR, GE, GL, GR, JU, LU, NE, NW, OW, SG, SH, SZ, SO, TG, TI, UR, VD, VS, ZG, ZH
Taiwan TW None
Turkey TR None
Tunisia TN None
Ukraine UA None
United Arab Emirates AE None
United Kingdom GB Subdivisions: UK (default), England, Northern Ireland, Scotland, Wales. For Isle of Man use country code IM.
United States US States and territories: AL, AK, AS, AZ, AR, CA, CO, CT, DE, DC, FL, GA, GU, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MH, MA, MI, FM, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, MP, OH, OK, OR, PW, PA, PR, RI, SC, SD, TN, TX, UT, VT, VA, VI, WA, WV, WI, WY
Uruguay UY None
Uzbekistan UZ None
Venezuela VE None
Vietnam VN None
Zambia ZM None
Zimbabwe ZW None

Available Financial Markets

The standard way to refer to a financial market is to use its ISO 10383 MIC (Market Identifier Code) as a “country” code when available. The following financial markets are available:

Entity Code Info
European Central Bank ECB Trans-European Automated Real-time Gross Settlement (TARGET2)
New York Stock Exchange XNYS NYSE market holidays (used by all other US-exchanges, including NASDAQ, etc.)

Beta Version

The latest development (beta) version can be installed directly from GitHub:

$ pip install --upgrade

All new features are always first pushed to beta branch, then released on master branch upon official version upgrades.


Issues and pull requests are always welcome. Please see here for more information.


Code and documentation are available according to the MIT License (see LICENSE).

Download files

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

Source Distribution

holidays-0.14.2.tar.gz (119.1 kB view hashes)

Uploaded source

Built Distribution

holidays-0.14.2-py3-none-any.whl (179.1 kB view hashes)

Uploaded py3

Supported by

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