{"id":13835695,"url":"https://github.com/holidays/holidays","last_synced_at":"2026-04-02T17:49:56.925Z","repository":{"id":473426,"uuid":"98540","full_name":"holidays/holidays","owner":"holidays","description":"A collection of Ruby methods to deal with statutory and other holidays.  You deserve a holiday!","archived":false,"fork":false,"pushed_at":"2026-03-29T05:49:17.000Z","size":1892,"stargazers_count":844,"open_issues_count":46,"forks_count":288,"subscribers_count":14,"default_branch":"master","last_synced_at":"2026-03-29T07:33:50.850Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/holidays.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2008-12-30T18:33:59.000Z","updated_at":"2026-03-29T05:49:21.000Z","dependencies_parsed_at":"2023-07-07T14:01:27.438Z","dependency_job_id":"15c5daf8-b8de-4445-a140-adf7002bef81","html_url":"https://github.com/holidays/holidays","commit_stats":{"total_commits":666,"total_committers":113,"mean_commits":5.893805309734513,"dds":0.7912912912912913,"last_synced_commit":"ed17774be9b7c31e4da1374aba1d0b7fa2e701c8"},"previous_names":["alexdunae/holidays"],"tags_count":50,"template":false,"template_full_name":null,"purl":"pkg:github/holidays/holidays","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holidays%2Fholidays","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holidays%2Fholidays/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holidays%2Fholidays/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holidays%2Fholidays/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/holidays","download_url":"https://codeload.github.com/holidays/holidays/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holidays%2Fholidays/sbom","scorecard":{"id":467723,"data":{"date":"2025-08-11","repo":{"name":"github.com/holidays/holidays","commit":"49667d7b42da20699d0a6bd4c94c628a2ee423f4"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":5.5,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":7,"reason":"Found 7/10 approved changesets -- score normalized to 7","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Info: topLevel 'contents' permission set to 'read': .github/workflows/ruby.yml:8","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":8,"reason":"dependency not pinned by hash detected -- score normalized to 8","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ruby.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/holidays/holidays/ruby.yml/master?enable=pin","Info:   0 out of   1 GitHub-owned GitHubAction dependencies pinned","Info:   1 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v8.6.0 not signed: https://api.github.com/repos/holidays/holidays/releases/77319166","Warn: release artifact v8.6.0 does not have provenance: https://api.github.com/repos/holidays/holidays/releases/77319166"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-19T12:56:41.438Z","repository_id":473426,"created_at":"2025-08-19T12:56:41.438Z","updated_at":"2025-08-19T12:56:41.438Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T14:01:09.677Z","updated_at":"2026-04-02T17:49:56.908Z","avatar_url":"https://github.com/holidays.png","language":"Ruby","readme":"# Ruby Holidays Gem [![Build Status](https://github.com/holidays/holidays/actions/workflows/ruby.yml/badge.svg)](https://github.com/holidays/holidays/actions/workflows/ruby.yml)\n\nFunctionality to deal with holidays in Ruby.\n\nExtends Ruby's built-in Date and Time classes and supports custom holiday definition lists.\n\n## Installation\n\n```\ngem install holidays\n```\n\n## Tested versions\n\nThis gem is tested with the following ruby versions:\n\n  * 3.2\n  * 3.3\n  * 3.4\n  * 4.0\n  * JRuby 9.2.21.0\n  * JRuby 9.4.2.0\n\n## Semver\n\nThis gem follows [semantic versioning](http://semver.org/). The guarantee specifically covers:\n\n * methods in the top-most `Holidays` namespace e.g. `Holidays.\u003cmethod\u003e`\n * the [core extensions](#extending-rubys-date-and-time-classes)\n\nPlease note that we consider definition changes to be 'minor' bumps, meaning they are backwards compatible with your code but might give different holiday results!\n\n## Time zones\n\nTime zones are ignored.  This library assumes that all dates are within the same time zone.\n\n## Usage\n\nThis gem offers multiple ways to check for holidays for a variety of scenarios.\n\n#### Checking a specific date\n\nGet all holidays on April 25, 2008 in Australia:\n\n```ruby\nHolidays.on(Date.new(2008, 4, 25), :au)\n=\u003e [{:name =\u003e 'ANZAC Day',...}]\n```\n\nYou can check multiple regions in a single call:\n\n```ruby\nHolidays.on(Date.new(2008, 1, 1), :us, :fr)\n=\u003e [{:name=\u003e\"New Year's Day\", :regions=\u003e[:us],...},\n    {:name=\u003e\"Jour de l'an\", :regions=\u003e[:fr],...}]\n```\n\nYou can leave off 'regions' to get holidays for any region in our [definitions](https://github.com/holidays/definitions):\n\n```ruby\n Holidays.on(Date.new(2007, 4, 25))\n=\u003e [{:name=\u003e\"ANZAC Day\", :regions=\u003e[:au],...},\n    {:name=\u003e\"Festa della Liberazione\", :regions=\u003e[:it],...},\n    {:name=\u003e\"Dia da Liberdade\", :regions=\u003e[:pt],...}\n    ...\n   ]\n```\n\n#### Checking a date range\n\nGet all holidays during the month of July 2008 in Canada and the US:\n\n```ruby\nfrom = Date.new(2008,7,1)\nto = Date.new(2008,7,31)\n\nHolidays.between(from, to, :ca, :us)\n=\u003e [{:name =\u003e 'Canada Day',...}\n    {:name =\u003e 'Independence Day',...}]\n```\n\n#### Check for 'informal' holidays\n\nYou can pass the 'informal' flag to include holidays specified as informal in your results. See [here](https://github.com/holidays/definitions/blob/master/doc/SYNTAX.md#formalinformal) for information on what constitutes 'informal' vs 'formal'.\n\nBy default this flag is turned off, meaning no informal holidays will be returned.\n\nGet Valentine's Day in the US:\n\n```ruby\nHolidays.on(Date.new(2018, 2, 14), :us, :informal)\n=\u003e [{:name=\u003e\"Valentine's Day\",...}]\n```\n\nLeaving off 'informal' will mean that Valentine's Day is not returned:\n\n```ruby\nHolidays.on(Date.new(2018, 2, 14), :us)\n=\u003e []\n```\n\nGet informal holidays during the month of February 2008 for any region:\n\n```ruby\nfrom = Date.new(2008,2,1)\nto = Date.new(2008,2,15)\n\nHolidays.between(from, to, :informal)\n=\u003e [{:name =\u003e 'Valentine\\'s Day',...}]\n```\n\n#### Check for 'observed' holidays\n\nYou can pass the 'observed' flag to include holidays that are observed on different days than they actually occur. See [here](https://github.com/holidays/definitions/blob/master/doc/SYNTAX.md#observed) for further explanation of 'observed'.\n\nBy default this flag is turned off, meaning no observed logic will be applied.\n\nGet holidays that are observed on Monday July 2, 2007 in British Columbia, Canada:\n\n```ruby\nHolidays.on(Date.new(2007, 7, 2), :ca_bc, :observed)\n=\u003e [{:name =\u003e 'Canada Day',...}]\n```\n\nLeaving off the 'observed' flag will mean that 'Canada Day' is not returned since it actually falls on Sunday July 1:\n\n```ruby\nHolidays.on(Date.new(2007, 7, 2), :ca_bc)\n=\u003e []\n\nHolidays.on(Date.new(2007, 7, 1), :ca_bc)\n=\u003e [{:name=\u003e\"Canada Day\", :regions=\u003e[:ca],...}]\n```\n\nGet all observed US Federal holidays between 2018 and 2019:\n\n```ruby\nfrom = Date.new(2018,1,1)\nto = Date.new(2019,12,31)\n\nHolidays.between(from, to, :federalreserve, :observed)\n=\u003e [{:name =\u003e \"New Year's Day\"....}\n    {:name =\u003e \"Birthday of Martin Luther King, Jr\"....}]\n```\n\n#### Check whether any holidays occur during work week\n\nCheck if there are any holidays taking place during a specified work week. 'Work week' is defined as the period of Monday through Friday of the week specified by the date.\n\nCheck whether a holiday falls during first week of the year for any region:\n\n```ruby\nHolidays.any_holidays_during_work_week?(Date.new(2016, 1, 1))\n=\u003e true\n```\n\nYou can also pass in `informal` or `observed`:\n\n```ruby\n# Returns true since Valentine's Day falls on a Wednesday\nHolidays.any_holidays_during_work_week?(Date.new(2018, 2, 14), :us, :informal)\n=\u003e true\n\n# Returns false if you don't specify informal\nHolidays.any_holidays_during_work_week?(Date.new(2018, 2, 14), :us)\n=\u003e false\n\n# Returns true since Veteran's Day is observed on Monday November 12, 2018\nHolidays.any_holidays_during_work_week?(Date.new(2018, 11, 12), :us, :observed)\n=\u003e true\n\n# Returns false if you don't specify observed since the actual holiday is on Sunday November 11th 2018\nHolidays.any_holidays_during_work_week?(Date.new(2018, 11, 12), :us)\n=\u003e false\n```\n\n#### Find the next holiday(s) that will occur from a specific date\n\nGet the next holidays occurring from February 23, 2016 for the US:\n\n```ruby\nHolidays.next_holidays(3, [:us, :informal], Date.new(2016, 2, 23))\n=\u003e [{:name =\u003e \"St. Patrick's Day\",...}, {:name =\u003e \"Good Friday\",...}, {:name =\u003e \"Easter Sunday\",...}]\n```\n\nYou can specify the number of holidays to return. This method will default to `Date.today` if no date is provided.\n\n#### Find all holidays occurring starting from a specific date to the end of the year\n\nGet all holidays starting from February 23, 2016 to end of year in the US:\n\n```ruby\nHolidays.year_holidays([:ca_on], Date.new(2016, 2, 23))\n=\u003e [{:name=\u003e\"Good Friday\",...},\n    {:name=\u003e\"Easter Sunday\",...},\n    {:name=\u003e\"Victoria Day\",...},\n    {:name=\u003e\"Canada Day\",...},\n    {:name=\u003e\"Civic Holiday\",...},\n    {:name=\u003e\"Labour Day\",...},\n    {:name=\u003e\"Thanksgiving\",...},\n    {:name=\u003e\"Remembrance Day\",...},\n    {:name=\u003e\"Christmas Day\",...},\n    {:name=\u003e\"Boxing Day\",...}]\n```\n\nThis method will default to `Date.today` if no date is provided.\n\n#### Return all available regions\n\nReturn all available regions:\n\n```ruby\nHolidays.available_regions\n=\u003e [:ar, :at, ..., :sg] # this will be a big array\n```\n\n## Loading Custom Definitions on the fly\n\nIn addition to the [provided definitions](https://github.com/holidays/definitions) you can load custom definitions file on the fly and use them immediately.\n\nTo load custom 'Company Founding' holiday on June 1st:\n\n```ruby\nHolidays.load_custom('/home/user/holiday_definitions/custom_holidays.yaml')\nHolidays.on(Date.new(2013, 6, 1), :my_custom_region)\n=\u003e [{:name =\u003e 'Company Founding',...}]\n```\n\nCustom definition files must match the [syntax of the existing definition files](https://github.com/holidays/definitions/blob/master/doc/SYNTAX.md).\n\nMultiple files can be loaded at the same time:\n\n```ruby\nHolidays.load_custom(\n  '/home/user/holidays/custom_holidays1.yaml',\n  '/home/user/holidays/custom_holidays2.yaml'\n)\n```\n\n## Extending Ruby's Date and Time classes\n\n### Date\n\nTo extend the 'Date' class:\n\n```ruby\nrequire 'holidays/core_extensions/date'\n\nclass Date\n  include Holidays::CoreExtensions::Date\nend\n```\n\nNow you can check which holidays occur in Iceland on January 1, 2008:\n\n```ruby\nd = Date.new(2008,7,1)\n\nd.holidays(:is)\n=\u003e [{:name =\u003e 'Nýársdagur'}...]\n```\n\nOr lookup Canada Day in different regions:\n\n```ruby\nd = Date.new(2008,7,1)\n\nd.holiday?(:ca) # Canada\n=\u003e true\n\nd.holiday?(:ca_bc) # British Columbia, Canada\n=\u003e true\n\nd.holiday?(:fr) # France\n=\u003e false\n```\n\nOr return the new date based on the options:\n\n```ruby\nd = Date.new(2008,7,1)\nd.change(:year =\u003e 2016, :month =\u003e 1, :day =\u003e 1)\n=\u003e #\u003cDate: 2016-01-01 ((2457389j,0s,0n),+0s,2299161j)\u003e\n```\n\nOr you can calculate the day of the month:\n\n```ruby\nDate.calculate_mday(2015, 4, :first, 2)\n=\u003e 7\n```\n\n### Time\n\n```ruby\nrequire 'holidays/core_extensions/time'\n\nclass Time\n  include Holidays::CoreExtensions::Time\nend\n```\n\nFind end of month for given date:\n\n```ruby\nd = Date.new(2016,8,1)\nd.end_of_month\n=\u003e #\u003cDate: 2016-08-31 ((2457632j,0s,0n),+0s,2299161j)\u003e\n```\n\n## Caching Holiday Lookups\n\nIf you are checking holidays regularly you can cache your results for improved performance. Run this before looking up a holiday (e.g. in an initializer):\n\n```ruby\nYEAR = 365 * 24 * 60 * 60\nHolidays.cache_between(Time.now, Time.now + 2 * YEAR, :ca, :us, :observed)\n```\n\nHolidays for the regions specified within the dates specified will be pre-calculated and stored in-memory. Future lookups will be much faster.\n\n## How to contribute\n\nSee our [contribution guidelines](doc/CONTRIBUTING.md) for information on how to help out!\n\n## Credits and code\n\n* Started by [@alexdunae](http://github.com/alexdunae) 2007-2012\n* Maintained by [@hahahana](https://github.com/hahahana), 2013\n* Maintained by [@ppeble](https://github.com/ppeble), 2014-present\n* Maintained by [@ttwo32](https://github.com/ttwo32), 2016-present\n\nPlus all of these [wonderful contributors!](https://github.com/holidays/holidays/contributors)\n","funding_links":[],"categories":["Ruby","Date and Time Processing"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholidays%2Fholidays","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fholidays%2Fholidays","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholidays%2Fholidays/lists"}