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.

Package:Python supported versions PyPI version Downloads
Docs:Documentation Status
Meta:Code styleLicense


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

$ pip install --upgrade 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

nyse_holidays = holidays.NYSE()  # this is a dict
# the below is the same, but takes a string:
nyse_holidays = holidays.financial_holidays('NYSE')  # 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 python-holidays documentation for additional examples and detailed information.

Available Countries

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

Country Code Subdivisions Available
Albania AL None
Algeria DZ None
American Samoa AS None; Can also be loaded as country US, subdivision AS
Andorra AD Parishes: 02, 03, 04, 05, 06, 07, 08
Angola AO None
Argentina AR None
Armenia AM 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
Bahrain BH None
Bangladesh BD None
Belarus BY None
Belgium BE None
Bolivia BO Departments: B, C, H, L, N, O, P, S, T
Bosnia and Herzegovina BA Departments: BD, FBiH, RS
Botswana BW None
Brazil BR States: AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, PR, 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, YT
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
Costa Rica CR None
Croatia HR None
Cuba CU None
Curacao CW None
Cyprus CY None
Czechia CZ None
Denmark DK None
Djibouti DJ None
Dominican Republic DO None
Ecuador EC None
Egypt EG None
Estonia EE None
Eswatini SZ None
Ethiopia ET None
Finland FI None
France FR Départements: BL, GES, GP, GY, MF, MQ, NC, PF, RE, WF, YT
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
Guam GU None; Can also be loaded as country US, subdivision GU
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
Indonesia ID None
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: Andria, Barletta, Cesena, Forli, Pesaro, Trani, Urbino
Jamaica JM None
Japan JP None
Kazakhstan KZ None
Kenya KE None
Kyrgyzstan KG None
Latvia LV None
Lesotho LS None
Liechtenstein LI None
Lithuania LT None
Luxembourg LU None
Madagascar MG None
Malawi MW None
Malta MT None
Marshall Islands (the) MH None
Mexico MX None
Moldova MD None
Monaco MC None
Montenegro ME None
Morocco MA None
Mozambique MZ None
Namibia NA None
Netherlands NL None
New Zealand NZ Regions: AUK, CAN, CIT, HKB, MBH, NSN, NTL, OTA, STL, TKI, WGN, WTC. Sub-regions: South Canterbury
Nicaragua NI Departments: AN, AS, BO, CA, CI, CO, ES, GR, JI, LE, MD, MN (default), MS, MT, NS, RI, SJ
Nigeria NG None
Northern Mariana Islands (the) MP None; Can also be loaded as country US, subdivision MP
North Macedonia MK None
Norway NO None
Pakistan PK None
Panama PA None
Paraguay PY None
Peru PE None
Philippines PH None
Poland PL None
Portugal PT Districts: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 20, 30, Ext; Use subdiv=’Ext’ to include holidays most people have off
Puerto Rico PR None; Can also be loaded as country US, subdivision PR
Romania RO None
Russia RU None
San Marino SM None
Saudi Arabia SA None
Serbia RS None
Singapore SG None
Slovakia SK None
Slovenia SI None
South Africa ZA None
South Korea KR None
Spain ES Autonomous communities: AN, AR, AS, CB, CE, CL, CM, CN, CT, EX, GA, IB, MC, MD, ML, NC, PV, RI, VC
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
Thailand TH None
Tunisia TN None
Turkey TR None
Ukraine UA None
United Arab Emirates AE None
United Kingdom GB Subdivisions: England, Northern Ireland, Scotland, UK (default), Wales; For Isle of Man use country code IM
United States Minor Outlying Islands UM None; Can also be loaded as country US, subdivision UM
United States of America (the) US States and territories: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY
United States Virgin Islands (the)   See Virgin Islands (U.S.)
Uruguay UY None
Uzbekistan UZ None
Vatican City VA None
Venezuela VE None
Vietnam VN None
Virgin Islands (U.S.) VI None; Can also be loaded as country US, subdivision VI
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.)


Some of the supported entities (country/market) provide more than one language for holiday names output. The default language is defined by default_language (optional) attribute for each entity and is used as a fallback when neither user specified language nor user locale language available. The default language code is a ISO 639-1 code.

Country Default Language Supported languages
Argentina es en_US, es, uk
Armenia hy en_US, hy
Austria de de, en_US, uk
Belarus be be, en_US
Bulgaria bg bg, en_US
Canada en en, fr, th
Chile es en_US, es, uk
Colombia es en_US, es, uk
Costa Rica es en_US, es, uk
Cuba es en_US, es, uk
Cyprus el el, en
Denmark da da, en_US, uk
Dominican Republic es en_US, es, uk
Ecuador es en_US, es, uk
Ethiopia am am, en_US
Finland fi en_US, fi, sv, uk
France fr en_US, fr, uk
Georgia ka en_US, ka
Germany de de, en_US, uk
Greece el el, en_US
Honduras es en_US, es, uk
Iceland is en_US, is, uk
Japan ja en_US, ja
Liechtenstein de de, en_US, uk
Mexico es en_US, es, uk
Moldova ro en_US, ro, uk
Monaco fr en_US, fr, uk
Netherlands nl en_US, nl, uk
Nicaragua es en_US, es, uk
Norway no en_US, no, uk
Paraguay es en_US, es, uk
Peru es en_US, es, uk
Poland pl en_US, pl, uk
Portugal pt_PT en_US, pt_PT
Romania ro en_US, ro, uk
Russia ru en_US, ru
Serbia sr en_US, sr
Slovakia sk en_US, sk, uk
Sweden sv en_US, sv, uk
Thailand th en_US, th
Ukraine uk en_US, uk
Uruguay es en_US, es, uk
Venezuela es en_US, es, uk

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).