{"id":4166,"library":"pandas-market-calendars","title":"pandas-market-calendars","description":"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.","status":"active","version":"5.3.2","language":"en","source_language":"en","source_url":"https://github.com/rsheftel/pandas_market_calendars","tags":["pandas","finance","calendars","trading","exchanges","holidays","time series"],"install":[{"cmd":"pip install pandas-market-calendars","lang":"bash","label":"pip"},{"cmd":"conda install -c conda-forge pandas-market-calendars","lang":"bash","label":"conda"}],"dependencies":[{"reason":"Provides the underlying exchange calendar data and logic, serving as a core dependency for market definitions.","package":"exchange-calendars","optional":false},{"reason":"Core data manipulation library; pandas-market-calendars is built to integrate with pandas' Series and DataFrame objects.","package":"pandas","optional":false}],"imports":[{"note":"The convention is to import the package and alias it as 'mcal' for brevity and consistency.","wrong":"import pandas_market_calendars.mcal","symbol":"mcal","correct":"import pandas_market_calendars as mcal"}],"quickstart":{"code":"import pandas_market_calendars as mcal\nimport pandas as pd\n\n# List all available calendars\nprint(\"Available calendars:\", mcal.get_calendar_names()[:5], \"...\")\n\n# Create a NYSE calendar instance\nnyse = mcal.get_calendar('NYSE')\n\n# Get the market schedule for a date range\nstart_date = '2023-12-20'\nend_date = '2024-01-10'\nschedule = nyse.schedule(start_date=start_date, end_date=end_date)\n\nprint(f\"\\nNYSE Schedule from {start_date} to {end_date}:\")\nprint(schedule.head())\n\n# Get a DatetimeIndex of valid trading times (e.g., daily frequency)\ntrading_days = mcal.date_range(schedule, frequency='1D')\nprint(f\"\\nFirst 5 trading days in the schedule (1D frequency):\")\nprint(trading_days.head())\n\n# Get specific market times for a date\nexample_date = pd.Timestamp('2023-12-22', tz='America/New_York')\nmarket_open_time = nyse.market_open_time(example_date)\nmarket_close_time = nyse.market_close_time(example_date)\nprint(f\"\\nMarket open on {example_date.date()}: {market_open_time.time()}\")\nprint(f\"Market close on {example_date.date()}: {market_close_time.time()}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python installation to version 3.10 or newer. For example, using `pyenv` or your system's package manager.","message":"As 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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always cross-reference calendar data for critical dates with official exchange sources. Report any discrepancies as issues on the project's GitHub page.","message":"Calendar 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"There'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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"An 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.","severity":"gotcha","affected_versions":"Unknown, reported in recent versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}