Skip to content

nflreadpy

A Python package for downloading NFL data from nflverse repositories. This is a Python port of the popular R package nflreadr, designed to provide easy access to NFL data with caching, progress tracking, and modern Python conventions.

Features

  • Compatible API with nflreadr R package
  • Fast data loading with Polars DataFrames
  • Intelligent caching (memory or filesystem)
  • Progress tracking for large downloads
  • Modern Python (3.10+) with type hints

Install

# Using uv (recommended)
uv add nflreadpy

# Using pip
pip install nflreadpy

Usage

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)

# nflreadpy uses Polars instead of pandas. Convert to pandas if needed:
pbp_pandas = pbp.to_pandas()

Available Functions

Reference page for all load functions

Configuration

Reference page for config options

Getting help

The best places to get help on this package are:

Data Sources

nflreadpy downloads data from the following nflverse repositories:

See the automation status page here for last update date/times for each release.

License

MIT License - see LICENSE file for details.

The majority of all nflverse data available (ie all but the FTN data as of July 2025) is broadly licensed as CC-BY 4.0, and the FTN data is CC-BY-SA 4.0 (see nflreadr docs for each main data file).

Development

This project uses the following tooling:

  • uv for dependency management
  • ruff for linting and formatting
  • mypy for type checking
  • pytest for testing
# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Format code
uv run ruff format

# Type check
uv run mypy src

Disclaimer

Most of the first version was written by Claude based on nflreadr, use at your own risk.

Contributing

Many hands make light work! Here are some ways you can contribute to this project: