You're Invited: Meet the Socket team at BSidesSF and RSAC - April 27 - May 1.RSVP
Socket
Sign inDemoInstall
Socket

holidays

Package Overview
Dependencies
Maintainers
3
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

holidays

Open World Holidays Framework

0.70
PyPI
Maintainers
3

Holidays

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.

PyPI PyPI downloads PyPI version PyPI release date
CI/CD CI/CD status Documentation status
Code License Python supported versions Code style Code coverage
GitHub GitHub stars GitHub forks GitHub contributors GitHub last commit
Citation Open World Holidays Framework DOI

Install

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

pip install --upgrade holidays

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

pip install --upgrade https://github.com/vacanza/holidays/tarball/dev

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

Documentation

The documentation is hosted on Read the Docs.

Quick Start

from datetime import date
import holidays

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

nyse_holidays = holidays.NYSE()  # this is a dict-like object
# the below is the same, but takes a string:
nyse_holidays = holidays.financial_holidays('NYSE')  # this is a dict-like object

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 holidays documentation for additional examples and detailed information.

Available Countries

We currently support 165 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. Some countries have common or foreign names or abbreviations as aliases for their subdivisions. These are defined in the (optional) subdivisions_aliases attribute. Some of the countries support more than one language for holiday names output. A 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. A list of all languages supported by country is defined by supported_languages (optional) attribute. If there is no designated ISO 639-1 code then ISO 639-2 code can be used.

Many countries have other categories of holidays in addition to common (national-wide) holidays: bank holidays, school holidays, additional (paid or non-paid) holidays, holidays of state or public employees, religious holidays (valid only for these religions followers). A list of all categories supported by country is defined by supported_categories (optional) attribute.

The following is a list of supported countries, their subdivisions followed by their aliases (if any) in brackets, available languages and additional holiday categories. All countries support PUBLIC holidays category by default. All other default values are highlighted with bold:

CountryCodeSubdivisionsSupported LanguagesSupported Categories
AfghanistanAFen_US, fa_AF, ps_AF
AlbaniaALen_US, sq, uk
AlgeriaDZar, en_US, fr
American SamoaASCan also be loaded as country US, subdivision ASGOVERNMENT, UNOFFICIAL
AndorraADParishes: 02, 03, 04, 05, 06, 07, 08
AngolaAOen_US, pt_AO, uk
Antigua and BarbudaAG
ArgentinaARProvinces: A (Salta), B (Buenos Aires), C (Ciudad Autónoma de Buenos Aires), D (San Luis), E (Entre Ríos), F (La Rioja), G (Santiago del Estero), H (Chaco), J (San Juan), K (Catamarca), L (La Pampa), M (Mendoza), N (Misiones), P (Formosa), Q (Neuquén), R (Río Negro), S (Santa Fe), T (Tucumán), U (Chubut), V (Tierra del Fuego), W (Corrientes), X (Córdoba), Y (Jujuy), Z (Santa Cruz)en_US, es, ukARMENIAN, BANK, GOVERNMENT, HEBREW, ISLAMIC
ArmeniaAMen_US, hy
ArubaAWen_US, nl, pap_AW, uk
AustraliaAUStates and territories: ACT (Australian Capital Territory), NSW (New South Wales), NT (Northern Territory), QLD (Queensland), SA (South Australia), TAS (Tasmania), VIC (Victoria), WA (Western Australia)en_AU, en_US, thBANK, HALF_DAY
AustriaATStates: 1 (Burgenland, Bgld, B), 2 (Kärnten, Ktn, K), 3 (Niederösterreich, NÖ, N), 4 (Oberösterreich, OÖ, O), 5 (Salzburg, Sbg, S), 6 (Steiermark, Stmk, St), 7 (Tirol, T), 8 (Vorarlberg, Vbg, V), 9 (Wien, W)de, en_US, ukBANK
AzerbaijanAZaz, en_US, ukWORKDAY
BahamasBS
BahrainBHar, en_US
BangladeshBD
BarbadosBB
BelarusBYbe, en_US, ru, thWORKDAY
BelgiumBEde, en_US, fr, nl, ukBANK
BelizeBZ
BoliviaBODepartments: B, C, H, L, N, O, P, S, Ten_US, es, uk
Bosnia and HerzegovinaBAEntities and district: BIH (Federacija Bosne i Hercegovine, FBiH), BRC (Brčko distrikt, BD), SRP (Republika Srpska, RS)bs, en_US, sr, uk
BotswanaBW
BrazilBRStates: AC (Acre), AL (Alagoas), AM (Amazonas), AP (Amapá), BA (Bahia), CE (Ceará), DF (Distrito Federal), ES (Espírito Santo), GO (Goiás), MA (Maranhão), MG (Minas Gerais), MS (Mato Grosso do Sul), MT (Mato Grosso), PA (Pará), PB (Paraíba), PE (Pernambuco), PI (Piauí), PR (Paraná), RJ (Rio de Janeiro), RN (Rio Grande do Norte), RO (Rondônia), RR (Roraima), RS (Rio Grande do Sul), SC (Santa Catarina), SE (Sergipe), SP (São Paulo), TO (Tocantins)en_US, pt_BR, ukOPTIONAL
BruneiBNen_US, ms, th
BulgariaBGbg, en_US, ukSCHOOL
Burkina FasoBF
BurundiBI
CambodiaKHen_US, km, th
CameroonCM
CanadaCAProvinces and territories: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YTar, en_CA, en_US, fr, thGOVERNMENT, OPTIONAL
ChadTD
ChileCLRegions: AI, AN, AP, AR, AT, BI, CO, LI, LL, LR, MA, ML, NB, RM, TA, VSen_US, es, ukBANK
ChinaCNen_US, th, zh_CN, zh_TWHALF_DAY
ColombiaCOen_US, es, uk
CongoCGen_US, fr
Costa RicaCRen_US, es, ukOPTIONAL
CroatiaHRen_US, hr, uk
CubaCUen_US, es, uk
CuracaoCWen_US, nl, pap_CW, ukHALF_DAY
CyprusCYel, en_CY, en_US, ukBANK, OPTIONAL
CzechiaCZcs, en_US, sk, uk
DenmarkDKda, en_US, ukOPTIONAL
DjiboutiDJar, en_US, fr
DominicaDM
Dominican RepublicDOen_US, es, uk
EcuadorECen_US, es, uk
EgyptEGar, en_US
El SalvadorSVDepartments: AH (Ahuachapán), CA (Cabañas), CH (Chalatenango), CU (Cuscatlán), LI (La Libertad), MO (Morazán), PA (La Paz), SA (Santa Ana), SM (San Miguel), SO (Sonsonate), SS (San Salvador), SV (San Vicente), UN (La Unión), US (Usulután)en_US, es, uk
EstoniaEEen_US, et, uk
EswatiniSZ
EthiopiaETam, ar, en_US
FijiFJWORKDAY
FinlandFIen_US, fi, sv_FI, ukUNOFFICIAL
FranceFRDOM/TOM: BL (Saint-Barthélemy), GES (Alsace, Champagne-Ardenne, Lorraine), GP (Guadeloupe), GY (Guyane), MF (Saint-Martin), MQ (Martinique), NC (Nouvelle-Calédonie), PF (Polynésie Française), RE (La Réunion), WF (Wallis-et-Futuna), YT (Mayotte)en_US, fr, uk
GabonGA
GeorgiaGEen_US, ka, ukGOVERNMENT
GermanyDEStates: BB (Brandenburg), BE (Berlin), BW (Baden-Württemberg), BY (Bayern), HB (Bremen), HE (Hessen), HH (Hamburg), MV (Mecklenburg-Vorpommern), NI (Niedersachsen), NW (Nordrhein-Westfalen), RP (Rheinland-Pfalz), SH (Schleswig-Holstein), SL (Saarland), SN (Sachsen), ST (Sachsen-Anhalt), TH (Thüringen)de, en_US, th, ukCATHOLIC
GhanaGH
GreeceGRel, en_US, ukHALF_DAY
GreenlandGLda, en_US, fi, is, kl, no, sv, ukOPTIONAL
GuamGUCan also be loaded as country US, subdivision GUGOVERNMENT, UNOFFICIAL
GuatemalaGTen_US, es
GuernseyGG
GuineaGNen_US, fr
HaitiHTen_US, es, fr_HT, htOPTIONAL
HondurasHNen_US, es, uk
Hong KongHKen_HK, en_US, th, zh_CN, zh_HKOPTIONAL
HungaryHUen_US, hu, uk
IcelandISen_US, is, ukHALF_DAY
IndiaINStates: AN (Andaman and Nicobar Islands), AP (Andhra Pradesh), AR (Arunachal Pradesh, Arunāchal Pradesh), AS (Assam), BR (Bihar, Bihār), CG (Chhattisgarh, Chhattīsgarh), CH (Chandigarh, Chandīgarh), DH (Dadra and Nagar Haveli and Daman and Diu, Dādra and Nagar Haveli and Damān and Diu), DL (Delhi), GA (Goa), GJ (Gujarat, Gujarāt), HP (Himachal Pradesh, Himāchal Pradesh), HR (Haryana, Haryāna), JH (Jharkhand, Jhārkhand), JK (Jammu and Kashmir, Jammu and Kashmīr), KA (Karnataka, Karnātaka), KL (Kerala), LA (Ladakh, Ladākh), LD (Lakshadweep), MH (Maharashtra, Mahārāshtra), ML (Meghalaya, Meghālaya), MN (Manipur), MP (Madhya Pradesh), MZ (Mizoram), NL (Nagaland, Nāgāland), OD (Odisha), PB (Punjab), PY (Puducherry), RJ (Rajasthan, Rājasthān), SK (Sikkim), TN (Tamil Nadu, Tamil Nādu), TR (Tripura), TS (Telangana, Telangāna), UK (Uttarakhand, Uttarākhand), UP (Uttar Pradesh), WB (West Bengal)en_IN, en_US, hiOPTIONAL
IndonesiaIDen_US, id, th, ukGOVERNMENT
IranIRen_US, fa_IR
IrelandIE
Isle of ManIMen_GB, en_US, th
IsraelILen_US, he, th, ukOPTIONAL, SCHOOL
ItalyITProvinces: AG (Agrigento), AL (Alessandria), AN (Ancona), AO (Aosta), AP (Ascoli Piceno), AQ (L'Aquila), AR (Arezzo), AT (Asti), AV (Avellino), BA (Bari), BG (Bergamo), BI (Biella), BL (Belluno), BN (Benevento), BO (Bologna), BR (Brindisi), BS (Brescia), BT (Barletta-Andria-Trani), BZ (Bolzano), CA (Cagliari), CB (Campobasso), CE (Caserta), CH (Chieti), CL (Caltanissetta), CN (Cuneo), CO (Como), CR (Cremona), CS (Cosenza), CT (Catania), CZ (Catanzaro), EN (Enna), FC (Forli-Cesena, Forlì-Cesena), FE (Ferrara), FG (Foggia), FI (Firenze), FM (Fermo), FR (Frosinone), GE (Genova), GO (Gorizia), GR (Grosseto), IM (Imperia), IS (Isernia), KR (Crotone), LC (Lecco), LE (Lecce), LI (Livorno), LO (Lodi), LT (Latina), LU (Lucca), MB (Monza e Brianza), MC (Macerata), ME (Messina), MI (Milano), MN (Mantova), MO (Modena), MS (Massa-Carrara), MT (Matera), NA (Napoli), NO (Novara), NU (Nuoro), OR (Oristano), PA (Palermo), PC (Piacenza), PD (Padova), PE (Pescara), PG (Perugia), PI (Pisa), PN (Pordenone), PO (Prato), PR (Parma), PT (Pistoia), PU (Pesaro e Urbino), PV (Pavia), PZ (Potenza), RA (Ravenna), RC (Reggio Calabria), RE (Reggio Emilia), RG (Ragusa), RI (Rieti), RM (Roma), RN (Rimini), RO (Rovigo), SA (Salerno), SI (Siena), SO (Sondrio), SP (La Spezia), SR (Siracusa), SS (Sassari), SU (Sud Sardegna), SV (Savona), TA (Taranto), TE (Teramo), TN (Trento), TO (Torino), TP (Trapani), TR (Terni), TS (Trieste), TV (Treviso), UD (Udine), VA (Varese), VB (Verbano-Cusio-Ossola), VC (Vercelli), VE (Venezia), VI (Vicenza), VR (Verona), VT (Viterbo), VV (Vibo Valentia). Cities: Andria, Barletta, Cesena, Forli (Forlì), Pesaro, Trani, Urbino
Ivory CoastCIen_CI, en_US, fr
JamaicaJM
JapanJPen_US, ja, thBANK
JerseyJE
JordanJOar, en_US
KazakhstanKZen_US, kk, uk
KenyaKEen_KE, en_US, swHINDU, ISLAMIC
KuwaitKWar, en_US
KyrgyzstanKG
LaosLAen_US, lo, thBANK, SCHOOL, WORKDAY
LatviaLVen_US, lv, uk
LesothoLS
LiechtensteinLIde, en_US, ukBANK
LithuaniaLTen_US, lt, uk
LuxembourgLUde, en_US, fr, lb, uk
MacauMOHistorical municipalities: I (Concelho das Ilhas, 海島市, 海岛市), M (Concelho de Macau, 澳門市, 澳门市)en_MO, en_US, pt_MO, th, zh_CN, zh_MOGOVERNMENT, MANDATORY
MadagascarMGen_US, mg, uk
MalawiMW
MalaysiaMYStates and federal territories: 01 (Johor, JHR), 02 (Kedah, KDH), 03 (Kelantan, KTN), 04 (Melaka, MLK), 05 (Negeri Sembilan, NSN), 06 (Pahang, PHG), 07 (Pulau Pinang, PNG), 08 (Perak, PRK), 09 (Perlis, PLS), 10 (Selangor, SGR), 11 (Terengganu, TRG), 12 (Sabah, SBH), 13 (Sarawak, SWK), 14 (WP Kuala Lumpur, KUL), 15 (WP Labuan, LBN), 16 (WP Putrajaya, PJY)en_US, ms_MY, th
MaldivesMV
MaltaMTen_US, mt
Marshall Islands (the)MH
MauritaniaMR
MexicoMXen_US, es, uk
MoldovaMDen_US, ro, uk
MonacoMCen_US, fr, uk
MontenegroMEcnr, en_US, ukCATHOLIC, HEBREW, ISLAMIC, ORTHODOX, WORKDAY
MoroccoMAar, en_US, fr
MozambiqueMZen_US, pt_MZ, uk
NamibiaNA
NetherlandsNLen_US, fy, nl, ukOPTIONAL
New ZealandNZRegions and Special Island Authorities: AUK (Auckland, Tāmaki-Makaurau, AU), BOP (Bay of Plenty, Toi Moana, BP), CAN (Canterbury, Waitaha, CA), CIT (Chatham Islands Territory, Chatham Islands, Wharekauri, CI), GIS (Gisborne, Te Tairāwhiti, GI), HKB (Hawke's Bay, Te Matau-a-Māui, HB), MBH (Marlborough, MA), MWT (Manawatū Whanganui, Manawatū-Whanganui, MW), NSN (Nelson, Whakatū, NE), NTL (Northland, Te Taitokerau, NO), OTA (Otago, Ō Tākou, OT), STL (Southland, Te Taiao Tonga, SO), TAS (Tasman, Te tai o Aorere, TS), TKI (Taranaki, TK), WGN (Greater Wellington, Te Pane Matua Taiao, Wellington, Te Whanganui-a-Tara, WG), WKO (Waikato, WK), WTC (West Coast, Te Tai o Poutini, WC). Subregions: South Canterbury
NicaraguaNISubdivisions: AN (Costa Caribe Norte), AS (Costa Caribe Sur), BO (Boaco), CA (Carazo), CI (Chinandega), CO (Chontales), ES (Estelí), GR (Granada), JI (Jinotega), LE (León), MD (Madriz), MN (Managua), MS (Masaya), MT (Matagalpa), NS (Nueva Segovia), RI (Rivas), SJ (Río San Juan)en_US, es, uk
NigeriaNG
Northern Mariana Islands (the)MPCan also be loaded as country US, subdivision MPGOVERNMENT, UNOFFICIAL
North MacedoniaMK
NorwayNOen_US, no, th, uk
PakistanPKen_PK, en_US, ur_PK
PalauPWARMED_FORCES, HALF_DAY
PanamaPAen_US, es, ukBANK
Papua New GuineaPG
ParaguayPYen_US, es, ukGOVERNMENT
PeruPEen_US, es, uk
PhilippinesPHen_PH, en_US, fil, thWORKDAY
PolandPLde, en_US, pl, uk
PortugalPTDistricts: 01 (Aveiro), 02 (Beja), 03 (Braga), 04 (Bragança), 05 (Castelo Branco), 06 (Coimbra), 07 (Évora), 08 (Faro), 09 (Guarda), 10 (Leiria), 11 (Lisboa), 12 (Portalegre), 13 (Porto), 14 (Santarém), 15 (Setúbal), 16 (Viana do Castelo), 17 (Vila Real), 18 (Viseu), 20 (Região Autónoma dos Açores), 30 (Região Autónoma da Madeira)en_US, pt_PT, ukOPTIONAL
Puerto RicoPRCan also be loaded as country US, subdivision PRGOVERNMENT, UNOFFICIAL
QatarQAar_QA, en_USBANK
RomaniaROen_US, ro, uk
RussiaRUen_US, ru, th
Saint Kitts and NevisKNHALF_DAY, WORKDAY
Saint LuciaLCen_LC, en_US
SamoaWS
San MarinoSM
Saudi ArabiaSAar, en_US
SerbiaRSen_US, sr
SeychellesSCen_SC, en_US
SingaporeSGen_SG, en_US, th
SlovakiaSKen_US, sk, ukWORKDAY
SloveniaSIen_US, sl, ukWORKDAY
South AfricaZA
South KoreaKRen_US, ko, thBANK
SpainESAutonomous communities: AN, AR, AS, CB, CE, CL, CM, CN, CT, EX, GA, IB, MC, MD, ML, NC, PV, RI, VCen_US, es, uk
Sri LankaLKen_US, si_LK, ta_LKBANK, GOVERNMENT, WORKDAY
SwedenSEen_US, sv, th, uk
SwitzerlandCHCantons: AG, AI, AR, BL, BS, BE, FR, GE, GL, GR, JU, LU, NE, NW, OW, SG, SH, SZ, SO, TG, TI, UR, VD, VS, ZG, ZHde, en_US, fr, it, ukHALF_DAY, OPTIONAL
TaiwanTWen_US, th, zh_CN, zh_TWGOVERNMENT, OPTIONAL, SCHOOL, WORKDAY
TanzaniaTZen_US, swBANK
ThailandTHen_US, thARMED_FORCES, BANK, GOVERNMENT, SCHOOL, WORKDAY
Timor LesteTLen_TL, en_US, pt_TL, tet, thGOVERNMENT, WORKDAY
TongaTOen_US, to
TunisiaTNar, en_US
TurkeyTRen_US, tr, ukHALF_DAY
TuvaluTVTown/Island Councils: FUN (Funafuti), NIT (Niutao), NKF (Nukufetau), NKL (Nukulaelae), NMA (Nanumea), NMG (Nanumaga, Nanumanga), NUI (Nui), VAI (Vaitupu)en_GB, en_US, tvl
UkraineUAar, en_US, th, ukWORKDAY
United Arab EmiratesAEar, en_US, thGOVERNMENT, OPTIONAL
United KingdomGBSubdivisions: ENG (England), NIR (Northern Ireland), SCT (Scotland), WLS (Wales)en_GB, en_US, th
United States Minor Outlying IslandsUMCan also be loaded as country US, subdivision UMGOVERNMENT, UNOFFICIAL
United States of America (the)USStates and territories: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WYGOVERNMENT, UNOFFICIAL
United States Virgin Islands (the)See Virgin Islands (U.S.)GOVERNMENT, UNOFFICIAL
UruguayUYen_US, es, ukBANK
UzbekistanUZen_US, uk, uz
VanuatuVU
Vatican CityVAen_US, it, th
VenezuelaVEen_US, es, uk
VietnamVNen_US, th, vi
Virgin Islands (U.S.)VICan also be loaded as country US, subdivision VIGOVERNMENT, UNOFFICIAL
ZambiaZM
ZimbabweZW

Available Financial Markets

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

EntityCodeInfoSupported Languages
Brasil, Bolsa, BalcãoBVMFBrazil Stock Exchange and Over-the-Counter Market holidays (same as ANBIMA holidays)en_US, pt_BR, uk
European Central BankXECBTrans-European Automated Real-time Gross Settlement (TARGET2)
ICE Futures EuropeIFEUA London-based Investment Exchange holidays
New York Stock ExchangeXNYSNYSE market holidays (used by all other US-exchanges, including NASDAQ, etc.)

Contributions

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

License

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

Keywords

holidays

FAQs

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts