{"id":2496,"library":"exchange-calendars","title":"Exchange Calendars","description":"exchange-calendars is a Python library designed for defining and querying calendars for various securities exchanges, providing out-of-the-box support for over 50 global exchanges. It is an actively maintained fork of the original `trading_calendars` package. The library is currently at version 4.13.2 and receives frequent updates, primarily to add and correct holiday schedules and trading hours for exchanges worldwide.","status":"active","version":"4.13.2","language":"en","source_language":"en","source_url":"https://github.com/prerak-proof/exchange_calendars","tags":["finance","trading","calendar","exchanges","market-data"],"install":[{"cmd":"pip install exchange-calendars","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The library was forked from `trading_calendars`. The `trading_calendars` package is no longer maintained, and `exchange_calendars` is the actively developed successor.","wrong":"import trading_calendars as tc","symbol":"exchange_calendars","correct":"import exchange_calendars as xcals"},{"note":"Used to retrieve a specific exchange calendar by its ISO-10383 market identifier code (MIC).","symbol":"get_calendar","correct":"xcals.get_calendar('XNYS')"}],"quickstart":{"code":"import exchange_calendars as xcals\nimport pandas as pd\n\n# Get a list of available calendar names\nprint(\"Available calendars (first 5):\", xcals.get_calendar_names(include_aliases=False)[:5])\n\n# Get the New York Stock Exchange (XNYS) calendar\nxnys = xcals.get_calendar(\"XNYS\")\n\n# Query the schedule for a specific date range\nstart_date = pd.Timestamp(\"2023-12-28\", tz='UTC')\nend_date = pd.Timestamp(\"2024-01-03\", tz='UTC')\nschedule = xnys.schedule.loc[start_date:end_date]\n\nprint(\"\\nNYSE Schedule (2023-12-28 to 2024-01-03):\")\nprint(schedule)","lang":"python","description":"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."},"warnings":[{"fix":"Review 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.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always 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.","message":"Some 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment meets the `requires_python` specification (`>=3.10, <4`). Upgrade your Python interpreter if necessary.","message":"The 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.","severity":"breaking","affected_versions":"All versions"},{"fix":"If 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.","message":"The 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.","severity":"gotcha","affected_versions":"<3.4.0 (for behavior), <4.0.0 (for `side` default)"},{"fix":"Consult 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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}