nflreadpy

You can install the latest release from PyPI using uv (recommended) or pip. To install the latest development version directly from GitHub, use the git URL.

Using uv (recommended)

# Latest release
uv add nflreadpy

# Development version
uv add nflreadpy@git+https://github.com/nflverse/nflreadpy

Using pip

# Latest release
pip install nflreadpy

# Development version
pip install nflreadpy@git+https://github.com/nflverse/nflreadpy

Import nflreadpy as nfl to access data loading functions. Note that nflreadpy returns Polars DataFrames by default. If your workflow requires pandas, you must explicitly convert them using .to_pandas().

import nflreadpy as nfl

# Load current season play-by-play data
pbp = nfl.load_pbp()

# Load player game-level stats for multiple seasons
player_stats = nfl.load_player_stats([2022, 2023])

# Load all available team level stats
team_stats = nfl.load_team_stats(seasons=True)

# Convert Polars DataFrame to pandas
pbp_pandas = pbp.to_pandas()

You can configure the behavior of nflreadpy using the following environment variables:

export NFLREADPY_CACHE='memory'
export NFLREADPY_CACHE_DIR='~/my_cache_dir'
export NFLREADPY_CACHE_DURATION=86400
export NFLREADPY_VERBOSE='False'
export NFLREADPY_TIMEOUT=30
export NFLREADPY_USER_AGENT='nflreadpy/v0.1.1'

Use nflreadpy.get_current_week() to retrieve the integer representing the current NFL week. This is useful for filtering data or identifying the most recent games in a dataset.

import nflreadpy

current_week = nflreadpy.get_current_week()
print(f"The current week is: {current_week}")

Use update_config from nflreadpy.config to set configuration settings within your Python code.

from nflreadpy.config import update_config

update_config(
    cache_mode="memory",
    cache_dir='~/my_cache_dir',
    cache_duration=86400,
    verbose=False,
    timeout=30,
    user_agent='nflreadpy/v0.1.1'
)

The nflreadpy configuration can be managed using the nflreadpy.config module. You can retrieve the current configuration, update settings, or reset the configuration to its default state using the following functions:

• get_config(): Returns the current configuration object.
• update_config(new_config): Updates the global configuration with the provided settings.
• reset_config(): Resets the configuration to its original default values.
• NflreadpyConfig: The configuration class used to define and hold settings.

Use nflreadpy.get_current_season() to retrieve the integer representing the current NFL season. This is useful for dynamically loading data for the active year without hardcoding season values.

import nflreadpy

current_season = nflreadpy.get_current_season()
print(f"The current season is: {current_season}")

Use nflreadpy.clear_cache() to remove all cached data files from your local system. This is useful if you suspect your local cache is corrupted or if you want to force the library to re-download the latest data from the source instead of using existing local files.

import nflreadpy

nflreadpy.clear_cache()

Use these functions for cache management and retrieving current NFL timing information.