Install & Compatibility
Where this runs
tested against v4.13.2 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.226s · 167.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.2s · import 1.172s · 160MB
169MB installed
● package 169MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
exchange_calendars
✓ import exchange_calendars as xcals
✗ import trading_calendars as tc
The library was forked from `trading_calendars`. The `trading_calendars` package is no longer maintained, and `exchange_calendars` is the actively developed successor.
get_calendar
✓ xcals.get_calendar('XNYS')
Used to retrieve a specific exchange calendar by its ISO-10383 market identifier code (MIC).
This quickstart demonstrates how to import the library, list available calendars, retrieve a specific exchange calendar (NYSE in this case), and query its trading schedule for a given date range.
import exchange_calendars as xcals
import pandas as pd
# Get a list of available calendar names
print("Available calendars (first 5):", xcals.get_calendar_names(include_aliases=False)[:5])
# Get the New York Stock Exchange (XNYS) calendar
xnys = xcals.get_calendar("XNYS")
# Query the schedule for a specific date range
start_date = pd.Timestamp("2023-12-28", tz='UTC')
end_date = pd.Timestamp("2024-01-03", tz='UTC')
schedule = xnys.schedule.loc[start_date:end_date]
print("\nNYSE Schedule (2023-12-28 to 2024-01-03):")
print(schedule)
Debug
Known issues
breakingVersion 4.0 introduced significant breaking changes related to timezone handling and method naming. Schedule times returned by the calendar are now UTC-localized, while sessions are timezone-naive. Numerous methods were renamed for consistency (e.g., `session_label` parameters became `session`). The old method names were deprecated in earlier versions and removed in 4.0.fixReview the official migration guide for 4.0. Ensure all references to session labels and timezone-aware datetimes are updated. Adapt to UTC-localized times for market open/close and timezone-naive sessions.
affects: >=4.0.0
gotchaSome calendars have defined historical `start` and `end` bounds, outside of which the accuracy of the calendar's schedule is not guaranteed. Querying dates outside these specified bounds may yield incorrect or undefined trading sessions/holidays.fixAlways verify the `calendar.default_start` and `calendar.default_end` properties for any calendar instance if querying historical or distant future dates. Be aware that the accuracy beyond these bounds is not guaranteed and may require manual verification or community contributions.
affects: All versions
breakingThe library explicitly requires Python >=3.10 and <4.0. Attempting to install or run `exchange-calendars` on unsupported Python versions (e.g., Python 3.9 or older, or Python 4.x when released) will lead to installation failures or runtime errors.fixEnsure your Python environment meets the `requires_python` specification (`>=3.10, <4`). Upgrade your Python interpreter if necessary.
affects: All versions
gotchaThe definition of 'trading minutes' and the behavior of 24-hour calendars (specifically, their open/close times) changed significantly in version 3.4, and the default `side` parameter for calendars was adjusted in v4. Prior to v3.4, 24-hour calendars might have had open/close times one minute later/earlier than the actual market times.fixIf migrating from `trading_calendars` or `exchange_calendars` versions prior to 3.4, carefully review the 'minutes tutorial' in the documentation to understand the current stable definition of trading minutes. Be aware of the `side` parameter (defaulting to 'left' in v4) and its impact on inclusive/exclusive minute ranges.
affects: <3.4.0 (for behavior), <4.0.0 (for `side` default)
gotchaThe library typically defines an exchange as 'open' only during regular trading periods, excluding pre-trading, post-trading, auction periods, or observed lunch breaks. This definition might differ from other sources or user expectations.fixConsult the 'minutes tutorial' in the official documentation for a detailed explanation of how trading minutes are defined and which periods are considered open or closed by the library to align expectations with its functionality.
affects: All versions
Errors
Common errors & fixes
exchange_calendars.errors.DateOutOfBounds: <exception str() failed>
This error occurs when attempting to query a calendar for dates that fall outside its defined historical or future bounds, meaning the library does not have data or guarantees accuracy for those specific dates.
fixCheck the `bound_min()` and `bound_max()` class methods of the specific calendar (e.g., `xcals.get_calendar('XNYS').bound_min()`) to understand its supported date range, and adjust your `start` or `end` parameters accordingly. If the required date range is not supported, you may need to contribute to the library or extend the calendar yourself. KeyError: 'UNKNOWN_CALENDAR_CODE'
This error arises when you try to retrieve a calendar using `xcals.get_calendar()` with an exchange code (e.g., 'UNKNOWN_CALENDAR_CODE') that is not recognized or registered within the `exchange-calendars` library.
fixVerify the correct exchange code by calling `xcals.get_calendar_names()` to get a list of all available calendar names and their aliases, then use one of the valid codes.
ModuleNotFoundError: No module named 'exchange_calendars'
This error indicates that the `exchange-calendars` package is not installed in your Python environment or is not accessible in the current path.
fixInstall the library using pip: `pip install exchange-calendars`. If you are using a virtual environment, ensure it is activated before installation.
AttributeError: 'ExchangeCalendar' object has no attribute 'non_existent_attribute'
This error occurs when you attempt to access an attribute or call a method on an `ExchangeCalendar` object that does not exist or has been removed/renamed in the version of the library you are using.
fixConsult the official `exchange-calendars` documentation or the source code for the correct attribute and method names for your specific version (4.13.2). Ensure you are using the correct properties and methods as defined by the library (e.g., `calendar.schedule`, `calendar.holidays`).
Upgrade
Version history
4.13.2latest on PyPI · released Mar 10, 2026
Audit
Dependencies
No dependency data recorded yet.