---
id: nflreadpy
version: "0.1.5"
license: MIT
license_treatment: permissive
maintenance: active
---

# nflreadpy — A Python package for downloading NFL data from nflverse repositories

License: permissive · Maintenance: active · Downloads: 85.5K/mo

## What it is and what it does

nflreadpy is a Python package that fetches NFL data from nflverse repositories and returns it as Polars DataFrames. It wraps access to multiple data sources—play-by-play records, player and team statistics, rosters, schedules, draft picks, injury reports, and fantasy football metrics—with built-in caching (memory or filesystem), progress tracking via tqdm, and configurable timeouts. The package uses requests for HTTP downloads, pydantic for configuration validation, and platformdirs for cache directory management.

You use it by calling functions like load_pbp(), load_player_stats(), or load_team_stats() with optional season parameters, and receive Polars DataFrames that can be converted to pandas if needed. Configuration is available via environment variables or programmatic calls to update_config(). The package is designed as a Python port of the R package nflreadr, so it follows similar naming and API conventions.

Use it for:

- Fetch historical play-by-play data for a season to analyze game patterns and drive efficiency.
- Load player stats across multiple seasons to build a dataset for fantasy football projections.
- Retrieve current rosters and depth charts to track roster composition changes over time.
- Download combine results and draft picks for scouting or historical analysis.
- Cache NFL schedules and injury reports locally to power a dashboard or analytics application.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Downloads and caches NFL data from nflverse repositories into Polars DataFrames, providing access to play-by-play, player stats, team stats, rosters, schedules, and other NFL analytics datasets.

Yes, if you work with NFL data. The package is actively maintained, has low install friction, carries a permissive MIT license, and provides a straightforward API to multiple authoritative nflverse data sources. The Beta status and recent release history (first release September 2025, latest November 2025) suggest it is still stabilizing; verify that the specific load functions you need are fully implemented and stable in your target version.

## Install

pip install nflreadpy
uv add nflreadpy
poetry add nflreadpy

## Installing nflreadpy

Before you install: Low install friction with a pure-Python wheel and six well-maintained runtime dependencies. The package is actively maintained with recent commits and is in Beta status, indicating ongoing development and refinement.

License in practice: MIT license permits unrestricted use, modification, and distribution. Note that the underlying NFL data from nflverse repositories carries its own licenses (CC-BY 4.0 for most data, CC-BY-SA 4.0 for FTN data), which may impose attribution or share-alike requirements on derived works.

Quickstart:

pip install nflreadpy

import nflreadpy as nfl

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

# Convert to pandas if needed
pbp_pandas = pbp.to_pandas()

Requires Python 3.10 or later. Underlying nflverse data sources must be accessible (requires internet connectivity).

Verify before relying:

- Whether the caching system (memory or filesystem) is suitable for large datasets without performance degradation.
- Actual data freshness guarantees and update frequency for each data source.
- Whether all 22 documented load functions are fully implemented and stable in version 0.1.5.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 85.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

nfl data download python, nfl play-by-play stats, nflverse data loader, football analytics data, nfl rosters schedules, sports data fetching, nfl statistics api, sports-analytics, data-fetching, nfl

[View on SkillFed](https://skillfed.io/packages/nflreadpy) · [View on PyPI](https://pypi.org/project/nflreadpy/)