Registry /
data / pandas-market-calendars
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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.604s · 168.3MB
glibcpy 3.10–3.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.fixUpgrade 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.fixAlways 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.fixUnderstand 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.fixBe 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.
fixpip 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.
fixDowngrade 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.
fixEnsure 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.
fixUpgrade 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.
fixInstall 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.