Registry / data / pandas-market-calendars

pandas-market-calendars

JSON →
library5.4.0pypypi✓ verified 22d ago

pandas-market-calendars provides a comprehensive set of market and exchange trading calendars for use with pandas. It fills a critical gap by offering specific holiday, late open, and early close calendars for over 50 global equity and futures markets, which are not included in pandas by default. The library also includes functions to manipulate these calendars and generate pandas DatetimeIndex objects containing only market-open times. It is actively maintained with frequent updates, typically releasing new versions every few months.

pip install pandas-market-calendars
INSTALL
IMPORT
SIG · PANDAS-MARKET-CALE
P
pandas-market-calendars
datapythonv5.4.0
Install
8.3s avg
Import
1945ms
Disk
170MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v5.4.0 · 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.103.95 runs
installs and imports cleanly · install 0.0s · import 1.604s · 168.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 8.3s · import 1.508s · 161MB
170MB installed
● package 170MB
Code
Verified usage

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

mcal
import pandas_market_calendars as mcal
import pandas_market_calendars.mcal
The convention is to import the package and alias it as 'mcal' for brevity and consistency.

This quickstart demonstrates how to list available calendars, get a specific market calendar (NYSE), retrieve its trading schedule for a date range, and then use that schedule to generate a DatetimeIndex of trading days. It also shows how to query specific market open/close times for a given date. Dates and times are timezone-aware.

import pandas_market_calendars as mcal import pandas as pd # List all available calendars print("Available calendars:", mcal.get_calendar_names()[:5], "...") # Create a NYSE calendar instance nyse = mcal.get_calendar('NYSE') # Get the market schedule for a date range start_date = '2023-12-20' end_date = '2024-01-10' schedule = nyse.schedule(start_date=start_date, end_date=end_date) print(f"\nNYSE Schedule from {start_date} to {end_date}:") print(schedule.head()) # Get a DatetimeIndex of valid trading times (e.g., daily frequency) trading_days = mcal.date_range(schedule, frequency='1D') print(f"\nFirst 5 trading days in the schedule (1D frequency):") print(trading_days.head()) # Get specific market times for a date example_date = pd.Timestamp('2023-12-22', tz='America/New_York') market_open_time = nyse.market_open_time(example_date) market_close_time = nyse.market_close_time(example_date) print(f"\nMarket open on {example_date.date()}: {market_open_time.time()}") print(f"Market close on {example_date.date()}: {market_close_time.time()}")
Debug
Known issues
breakingAs of version 5.0.0, the minimum required Python version has been raised to 3.10. Users on Python 3.9 or older must upgrade their Python environment.
fix
Upgrade your Python installation to version 3.10 or newer. For example, using `pyenv` or your system's package manager.
affects: >=5.0.0
gotchaCalendar accuracy for specific dates and markets can sometimes be an issue. GitHub issues indicate instances where holidays, early closes, or regular market times for certain exchanges (e.g., NYSE, EUREX, CME) might be incorrect or require updates. Users should verify critical dates for their specific use case.
fix
Always cross-reference calendar data for critical dates with official exchange sources. Report any discrepancies as issues on the project's GitHub page.
affects: All versions
gotchaThere's a distinction between `schedule()` and `date_range()`. `schedule()` returns a DataFrame with `market_open` and `market_close` timestamps for valid trading days. `date_range()` takes this schedule and generates a `pd.DatetimeIndex` of all trading minutes/hours/days within that schedule, based on a specified frequency. Confusing their outputs can lead to incorrect time series generation.
fix
Understand that `schedule()` defines the boundaries of trading periods, while `date_range()` populates those periods with specific timestamps at a given frequency. Use `schedule()` to get market open/close per day, and `date_range()` to create a detailed time series of trading moments.
affects: All versions
gotchaAn open GitHub issue (#301) suggests that importing `pandas_market_calendars` might subtly alter the behavior of the `pandas` library. While the exact impact isn't fully detailed in public search results, it indicates a potential side effect.
fix
Be aware of this potential interaction, especially when using complex pandas operations alongside `pandas-market-calendars`. If unexpected behavior is observed in pandas, try isolating the `pandas-market-calendars` import to confirm if it's the cause.
affects: Unknown, reported in recent versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pandas_market_calendars'
The `pandas-market-calendars` library is not installed in the active Python environment.
fix
pip install pandas-market-calendars
ImportError: cannot import name 'apply_wraps' from 'pandas._libs.tslibs.offsets'
This error often indicates a compatibility issue between `pandas-market-calendars` and the installed version of `pandas`, specifically due to changes in pandas' internal modules.
fix
Downgrade pandas to a compatible version, such as `pandas==1.2.5`, or check the `pandas-market-calendars` documentation for the officially supported pandas versions.
ValueError: The dtype of 'values' is incorrect. Must be 'datetime64[ns]'. Got object instead.
This error occurs when a pandas DataFrame column used with `pandas-market-calendars` functions is not of the expected `datetime64[ns]` dtype, often appearing as an 'object' dtype, possibly due to an outdated pandas version.
fix
Ensure the DataFrame column containing dates is explicitly converted to `datetime64[ns]` using `pd.to_datetime()` and upgrade pandas to the latest compatible version using `pip install pandas --upgrade`.
TypeError: int() argument must be a string, a bytes-like object or a number, not 'NaTType'
This `NP_NAT error` is a compatibility issue with the underlying `exchange_calendars` package (which `pandas-market-calendars` uses), typically caused by an incompatible pandas version.
fix
Upgrade the `exchange-calendars` package to its latest version (e.g., `pip install exchange-calendars --upgrade`) to resolve the incompatibility with `pandas`.
pandas-market-calendars X.Y.Z requires pandas<A.B,>=C.D, but you have pandas P.Q.R which is incompatible.
The installed version of `pandas` does not meet the specific version requirements declared by `pandas-market-calendars`, leading to a direct dependency conflict reported by the package manager.
fix
Install a version of `pandas` that satisfies the specified requirements (e.g., `pip install pandas==<A.B-1.x>`). Alternatively, check for a newer version of `pandas-market-calendars` that supports your desired `pandas` version.
Upgrade
Version history
5.4.0latest on PyPI · released May 27, 2026
Audit
Dependencies
exchange-calendarsrequiredProvides the underlying exchange calendar data and logic, serving as a core dependency for market definitions.
pandasrequiredCore data manipulation library; pandas-market-calendars is built to integrate with pandas' Series and DataFrame objects.
Agent activity
12 hits · last 30 days
node
10
Amazon
1
Resources
pandas-market-calendars — pip install pandas-market-calendars · libregistry