Registry / data / govuk-bank-holidays

govuk-bank-holidays

library0.19pypypi✓ verified 84d ago

This library provides a convenient way to load the official list of bank holidays in the United Kingdom directly from GOV.UK. Currently at version 0.19, it is actively maintained with frequent updates to include new holiday data as published by GOV.UK, alongside regular maintenance for Python version compatibility.

data

pip install govuk-bank-holidays

github ↗package ↗

INSTALL

IMPORT

SIG · GOVUK-BANK-HOLIDAY

govuk-bank-holidays

datapythonv0.19

Install

2.1s avg

Import

556ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.19 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.589s · 21.3MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.1s · import 0.522s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BankHolidays

✓ from govuk_bank_holidays.bank_holidays import BankHolidays

Initializes the `BankHolidays` class, demonstrating how to fetch all holidays for a specific division and retrieve the next upcoming holiday. It also shows how to use the cached holiday data offline.

from govuk_bank_holidays.bank_holidays import BankHolidays # Initialize the BankHolidays object (fetches data from GOV.UK by default) bank_holidays = BankHolidays() # Get all bank holidays for England and Wales print("Bank holidays for England and Wales:") for holiday in bank_holidays.get_holidays(division=BankHolidays.ENGLAND_AND_WALES): print(f" {holiday['title']} on {holiday['date']}") # Get the next upcoming bank holiday for Scotland next_scottish_holiday = bank_holidays.get_next_holiday(division=BankHolidays.SCOTLAND) if next_scottish_holiday: print(f"\nNext Scottish bank holiday: {next_scottish_holiday['title']} on {next_scottish_holiday['date']}") # Use cached holidays only (no internet connection required) cached_holidays = BankHolidays(use_cached_holidays=True) print(f"\nTotal cached holidays: {len(cached_holidays.get_holidays())}")

Debug

Known issues

breakingPython version compatibility has changed across releases. For example, version 0.12 dropped support for Python versions older than 3.7, version 0.16 dropped support for versions older than 3.9, and version 0.18 removed Python 3.9 support. Ensure your environment uses a currently supported Python version (e.g., 3.10-3.14 for v0.18+).

fix

Upgrade your Python environment to version 3.10 or newer. Check the library's release notes for the exact supported Python versions for your `govuk-bank-holidays` library version.

affects: 0.12, 0.16, 0.18

gotchaWhen fetching holidays, if no `division` parameter is specified, only holidays common to all UK divisions (England/Wales, Scotland, Northern Ireland) are returned. This will omit division-specific bank holidays.

fix

Always specify a `division` (e.g., `BankHolidays.ENGLAND_AND_WALES`, `BankHolidays.SCOTLAND`, `BankHolidays.NORTHERN_IRELAND`) when calling methods like `get_holidays()` or `get_next_holiday()` to ensure all relevant holidays for that region are included.

affects: All versions

gotchaGOV.UK only provides bank holiday data for a year or two into the future. While the library includes a cached backup, it may not be as frequently updated or as comprehensive for distant future dates as the live GOV.UK source.

fix

Be aware that very far-future holiday data might be missing or incomplete. For critical planning, always cross-reference with official GOV.UK sources.

affects: All versions

gotchaVersion 0.17 introduced a timeout for downloading bank holiday data from GOV.UK. Older versions might hang indefinitely if the GOV.UK source is unavailable or slow.

fix

Upgrade to version 0.17 or newer to benefit from the built-in download timeout and fallback to cached data.

affects: <0.17

gotchaThe Welsh localization (`locale='cy'`) may contain errors.

fix

Exercise caution when using the Welsh locale (`BankHolidays(locale='cy')`) and verify the accuracy of the holiday titles and notes if relied upon for official purposes.

affects: All versions

Errors

Common errors & fixes

KeyError: 'some-division-name'

Attempting to access a bank holiday division using an incorrect or non-existent key, or trying to access specific event properties directly from the raw GOV.UK JSON structure instead of using the library's methods.

fix

Use the constants provided by the `BankHolidays` class for divisions (e.g., `BankHolidays.ENGLAND_AND_WALES`). If parsing raw JSON, ensure you understand its nested structure.

AttributeError: module 'govuk_bank_holidays' has no attribute 'BankHolidays'

Incorrect import path for the `BankHolidays` class.

fix

The correct import statement is `from govuk_bank_holidays.bank_holidays import BankHolidays`.

No bank holidays returned for a specific region, even though holidays are expected.

The `division` parameter was not specified when calling methods like `get_holidays()`, leading to only common UK holidays being returned.

fix

Always pass the appropriate division constant to the method, e.g., `bank_holidays.get_holidays(division=BankHolidays.SCOTLAND)` to get holidays specific to Scotland.

requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer')) or similar connection issues.

Network problems preventing the library from downloading the latest bank holiday data from GOV.UK. This can be exacerbated in older versions (pre-0.17) that lack download timeouts.

fix

Ensure stable internet connectivity. Upgrade the library to version 0.17 or newer for robust timeout handling. Alternatively, initialize with `BankHolidays(use_cached_holidays=True)` to use the locally cached data, bypassing live download.

Upgrade

Version history

0.19latest on PyPI · released Feb 25, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/ministryofjustice/govuk-bank-holidays ↗

packagehttps://pypi.org/project/govuk-bank-holidays/ ↗