https://github.com/dr-prodigy/python-holidays
Open World Holidays Framework
https://github.com/dr-prodigy/python-holidays
calendar gsoc holiday holiday-api holiday-calculation python
Last synced: 13 days ago
JSON representation
Open World Holidays Framework
- Host: GitHub
- URL: https://github.com/dr-prodigy/python-holidays
- Owner: vacanza
- License: mit
- Created: 2014-08-24T15:17:18.000Z (over 10 years ago)
- Default Branch: dev
- Last Pushed: 2025-04-01T03:15:00.000Z (14 days ago)
- Last Synced: 2025-04-01T04:24:03.569Z (14 days ago)
- Topics: calendar, gsoc, holiday, holiday-api, holiday-calculation, python
- Language: Python
- Homepage: https://pypi.org/project/holidays
- Size: 14.9 MB
- Stars: 1,590
- Watchers: 20
- Forks: 511
- Open Issues: 112
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Authors: AUTHORS.md
Awesome Lists containing this project
- best-of-python - GitHub
README
# 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
![]()
![]()
![]()
CI/CD
![]()
![]()
Code
![]()
![]()
![]()
![]()
GitHub
![]()
![]()
![]()
![]()
Citation
![]()
## Install
The latest stable version can always be installed or updated via pip:
``` shell
pip install --upgrade holidays
```The latest development (dev) version can be installed directly from GitHub:
``` shell
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](https://holidays.readthedocs.io/).
## Quick Start
``` python
from datetime import date
import holidaysus_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 objectnyse_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 objectdate(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:
``` python
'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:
``` python
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](https://holidays.readthedocs.io/) for additional examples
and detailed information.## Available Countries
We currently support 162 country codes. The standard way to refer to a country is by using its [ISO
3166-1 alpha-2 code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes), the same used
for domain names, and for a subdivision its [ISO 3166-2
code](https://en.wikipedia.org/wiki/ISO_3166-2). 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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). A list of all languages supported by
country is defined by `supported_languages` (optional) attribute. If there is no designated [ISO
639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) then [ISO 639-2
code](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) 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:Country
Code
Subdivisions
Supported Languages
Supported CategoriesAfghanistan
AFen_US, fa_AF, ps_AF
Albania
ALen_US, sq, uk
Algeria
DZar, en_US, fr
American Samoa
AS
Can also be loaded as country US, subdivision ASGOVERNMENT, UNOFFICIAL
Andorra
AD
Parishes: 02, 03, 04, 05, 06, 07, 08Angola
AOen_US, pt_AO, uk
Argentina
AR
Provinces: 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, uk
ARMENIAN, BANK, GOVERNMENT, HEBREW, ISLAMICArmenia
AMen_US, hy
Aruba
AWen_US, nl, pap_AW, uk
Australia
AU
States 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, th
BANK, HALF_DAYAustria
AT
States: 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, uk
BANKAzerbaijan
AZaz, en_US, uk
WORKDAYBahamas
BSBahrain
BHar, en_US
Bangladesh
BDBarbados
BBBelarus
BYbe, en_US, ru, th
WORKDAYBelgium
BEde, en_US, fr, nl, uk
BANKBelize
BZBolivia
BO
Departments: B, C, H, L, N, O, P, S, T
en_US, es, ukBosnia and Herzegovina
BA
Entities and district: BIH (Federacija Bosne i Hercegovine, FBiH), BRC (Brčko distrikt, BD), SRP (Republika Srpska, RS)
bs, en_US, sr, ukBotswana
BWBrazil
BR
States: 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, uk
OPTIONALBrunei
BNen_US, ms, th
Bulgaria
BGbg, en_US, uk
SCHOOLBurkina Faso
BFBurundi
BICambodia
KHen_US, km, th
Cameroon
CMCanada
CA
Provinces and territories: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT
ar, en_CA, en_US, fr, th
GOVERNMENT, OPTIONALChad
TDChile
CL
Regions: AI, AN, AP, AR, AT, BI, CO, LI, LL, LR, MA, ML, NB, RM, TA, VS
en_US, es, uk
BANKChina
CNen_US, th, zh_CN, zh_TW
HALF_DAYColombia
COen_US, es, uk
Congo
CGen_US, fr
Costa Rica
CRen_US, es, uk
OPTIONALCroatia
HRen_US, hr, uk
Cuba
CUen_US, es, uk
Curacao
CWen_US, nl, pap_CW, uk
HALF_DAYCyprus
CYel, en_CY, en_US, uk
BANK, OPTIONALCzechia
CZcs, en_US, sk, uk
Denmark
DKda, en_US, uk
OPTIONALDjibouti
DJar, en_US, fr
Dominica
DMDominican Republic
DOen_US, es, uk
Ecuador
ECen_US, es, uk
Egypt
EGar, en_US
El Salvador
SV
Departments: 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, ukEstonia
EEen_US, et, uk
Eswatini
SZEthiopia
ETam, ar, en_US
Fiji
FJWORKDAY
Finland
FIen_US, fi, sv_FI, uk
UNOFFICIALFrance
FR
DOM/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, ukGabon
GAGeorgia
GEen_US, ka, uk
GOVERNMENTGermany
DE
States: 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, uk
CATHOLICGhana
GHGreece
GRel, en_US, uk
HALF_DAYGreenland
GLda, en_US, fi, is, kl, no, sv, uk
OPTIONALGuam
GU
Can also be loaded as country US, subdivision GUGOVERNMENT, UNOFFICIAL
Guatemala
GTen_US, es
Guernsey
GGHaiti
HTen_US, es, fr_HT, ht
OPTIONALHonduras
HNen_US, es, uk
Hong Kong
HKen_HK, en_US, th, zh_CN, zh_HK
OPTIONALHungary
HUen_US, hu, uk
Iceland
ISen_US, is, uk
HALF_DAYIndia
IN
States: 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, hi
OPTIONALIndonesia
IDen_US, id, th, uk
GOVERNMENTIran
IRen_US, fa_IR
Ireland
IEIsle of Man
IMen_GB, en_US, th
Israel
ILen_US, he, th, uk
OPTIONAL, SCHOOLItaly
IT
Provinces: 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, UrbinoIvory Coast
CIen_CI, en_US, fr
Jamaica
JMJapan
JPen_US, ja, th
BANKJersey
JEJordan
JOar, en_US
Kazakhstan
KZen_US, kk, uk
Kenya
KEen_KE, en_US, sw
HINDU, ISLAMICKuwait
KWar, en_US
Kyrgyzstan
KGLaos
LAen_US, lo, th
BANK, SCHOOL, WORKDAYLatvia
LVen_US, lv, uk
Lesotho
LSLiechtenstein
LIde, en_US, uk
BANKLithuania
LTen_US, lt, uk
Luxembourg
LUde, en_US, fr, lb, uk
Macau
MO
Historical municipalities: I (Concelho das Ilhas, 海島市, 海岛市), M (Concelho de Macau, 澳門市, 澳门市)
en_MO, en_US, pt_MO, th, zh_CN, zh_MO
GOVERNMENT, MANDATORYMadagascar
MGen_US, mg, uk
Malawi
MWMalaysia
MY
States 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, thMaldives
MVMalta
MTen_US, mt
Marshall Islands (the)
MHMauritania
MRMexico
MXen_US, es, uk
Moldova
MDen_US, ro, uk
Monaco
MCen_US, fr, uk
Montenegro
MEcnr, en_US, uk
CATHOLIC, HEBREW, ISLAMIC, ORTHODOX, WORKDAYMorocco
MAar, en_US, fr
Mozambique
MZen_US, pt_MZ, uk
Namibia
NANetherlands
NLen_US, fy, nl, uk
OPTIONALNew Zealand
NZ
Regions 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 CanterburyNicaragua
NI
Subdivisions: 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, ukNigeria
NGNorthern Mariana Islands (the)
MP
Can also be loaded as country US, subdivision MPGOVERNMENT, UNOFFICIAL
North Macedonia
MKNorway
NOen_US, no, th, uk
Pakistan
PKen_PK, en_US, ur_PK
Palau
PWARMED_FORCES, HALF_DAY
Panama
PAen_US, es, uk
BANKPapua New Guinea
PGParaguay
PYen_US, es, uk
GOVERNMENTPeru
PEen_US, es, uk
Philippines
PHen_PH, en_US, fil, th
WORKDAYPoland
PLde, en_US, pl, uk
Portugal
PT
Districts: 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, uk
OPTIONALPuerto Rico
PR
Can also be loaded as country US, subdivision PRGOVERNMENT, UNOFFICIAL
Romania
ROen_US, ro, uk
Russia
RUen_US, ru, th
Saint Kitts and Nevis
KNHALF_DAY, WORKDAY
Saint Lucia
LCen_LC, en_US
Samoa
WSSan Marino
SMSaudi Arabia
SAar, en_US
Serbia
RSen_US, sr
Seychelles
SCen_SC, en_US
Singapore
SGen_SG, en_US, th
Slovakia
SKen_US, sk, uk
WORKDAYSlovenia
SIen_US, sl, uk
WORKDAYSouth Africa
ZASouth Korea
KRen_US, ko, th
BANKSpain
ES
Autonomous communities: AN, AR, AS, CB, CE, CL, CM, CN, CT, EX, GA, IB, MC, MD, ML, NC, PV, RI, VC
en_US, es, ukSri Lanka
LKen_US, si_LK, ta_LK
BANK, GOVERNMENT, WORKDAYSweden
SEen_US, sv, th, uk
Switzerland
CH
Cantons: 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, ZH
de, en_US, fr, it, uk
HALF_DAY, OPTIONALTaiwan
TWen_US, th, zh_CN, zh_TW
GOVERNMENT, OPTIONAL, SCHOOL, WORKDAYTanzania
TZen_US, sw
BANKThailand
THen_US, th
ARMED_FORCES, BANK, GOVERNMENT, SCHOOL, WORKDAYTimor Leste
TLen_US, pt_TL, tet
GOVERNMENT, WORKDAYTonga
TOen_US, to
Tunisia
TNar, en_US
Turkey
TRen_US, tr, uk
HALF_DAYTuvalu
TV
Town/Island Councils: FUN (Funafuti), NIT (Niutao), NKF (Nukufetau), NKL (Nukulaelae), NMA (Nanumea), NMG (Nanumaga, Nanumanga), NUI (Nui), VAI (Vaitupu)
en_GB, en_US, tvlUkraine
UAar, en_US, th, uk
WORKDAYUnited Arab Emirates
AEar, en_US, th
GOVERNMENT, OPTIONALUnited Kingdom
GB
Subdivisions: ENG (England), NIR (Northern Ireland), SCT (Scotland), WLS (Wales)
en_GB, en_US, thUnited States Minor Outlying Islands
UM
Can also be loaded as country US, subdivision UMGOVERNMENT, UNOFFICIAL
United States of America (the)
US
States 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
Uruguay
UYen_US, es, uk
BANKUzbekistan
UZen_US, uk, uz
Vanuatu
VUVatican City
VAen_US, it, th
Venezuela
VEen_US, es, uk
Vietnam
VNen_US, th, vi
Virgin Islands (U.S.)
VI
Can also be loaded as country US, subdivision VIGOVERNMENT, UNOFFICIAL
Zambia
ZMZimbabwe
ZW## Available Financial Markets
The standard way to refer to a financial market is to use its [ISO 10383
MIC](https://www.iso20022.org/market-identifier-codes) (Market Identifier Code) as a "market"
code when available. The following financial markets are available:Entity
Code
Info
Supported LanguagesBrasil, Bolsa, Balcão
BVMF
Brazil Stock Exchange and Over-the-Counter Market holidays (same as ANBIMA holidays)
en_US, pt_BR, ukEuropean Central Bank
XECB
Trans-European Automated Real-time Gross Settlement (TARGET2)ICE Futures Europe
IFEU
A London-based Investment Exchange holidaysNew York Stock Exchange
XNYS
NYSE market holidays (used by all other US-exchanges, including NASDAQ, etc.)## Contributions
[Issues](https://github.com/vacanza/holidays/issues) and [pull
requests](https://github.com/vacanza/holidays/pulls) are always welcome. Please see
[here](https://github.com/vacanza/holidays/blob/dev/CONTRIBUTING.md) for more information.## License
Code and documentation are available according to the MIT License (see
[LICENSE](https://github.com/vacanza/holidays/blob/dev/LICENSE)).