pybaseball

library2.2.7pypypi✓ verified 86d ago

pybaseball is a Python library for retrieving and analyzing baseball data from sources like Baseball Savant, FanGraphs, and Baseball-Reference. Version 2.2.7 (current) fixes FanGraphs leaderboard URLs and adds new features like PitchingBot/Stuff+ stat enums and strike zone plotting. Release cadence is irregular, with minor patches every few months.

data

pip install pybaseball

github ↗package ↗

INSTALL

IMPORT

SIG · PYBASEBALL

pybaseball

datapythonv2.2.7

Install

20.1s avg

Import

4967ms

Disk

602MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.2.7 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 5.104s · 612.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 20.1s · import 4.830s · 572MB

602MB installed

● package 602MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

statcast

✓ from pybaseball import statcast

✗ from pybaseball.statcast import statcast

statcast is a top-level function, not a submodule

batting_stats

✓ from pybaseball import batting_stats

✗ from pybaseball.fangraphs import batting_stats

batting_stats is a top-level function; direct submodule imports may break

playerid_lookup

✓ from pybaseball import playerid_lookup

✗ from pybaseball.lookup import playerid_lookup

player lookup is at top level

Retrieve Statcast data for two days in May 2024. Cache is disabled by default, but if enabled, use cache.disable() to ensure fresh data.

from pybaseball import statcast import pandas as pd # Disable cache to avoid stale data from pybaseball import cache df = statcast(start_dt='2024-05-01', end_dt='2024-05-02') print(df.head())

Debug

Known issues

breakingStatcast data schema changes frequently: column names, data types, and null handling can change without notice. Always check the actual columns after fetching.

fix

Inspect df.columns after fetching and handle missing/renamed columns gracefully.

affects: all

breakingFanGraphs leaderboard URL changed in v2.2.6; older versions cannot retrieve FanGraphs data.

fix

Upgrade to pybaseball>=2.2.6.

affects: < 2.2.6

deprecatedPython 3.6 support dropped in v2.2.5; 3.7 also dropped later.

fix

Use Python 3.8+.

affects: >= 2.2.5

gotchaCaching is disabled by default, but enabling it can cause stale data if not cleared. Manual cache clearing is required.

fix

Use cache.enable() then cache.disable() or delete cache files manually.

affects: >= 2.1.0

gotchaWeb scraping can be unreliable: frequent HTTP errors (429, 503) and HTML structure changes may break scraping functions.

fix

Wrap calls in retry logic; check GitHub issues for known outages.

affects: all

Errors

Common errors & fixes

ValueError: URL does not return valid JSON

Statcast API endpoint temporarily down or changed.

fix

Wait and retry, or check the pybaseball GitHub issue tracker for known API issues.

AttributeError: module 'pybaseball' has no attribute 'statcast'

Importing from submodule instead of top level, or very old version (<2.0.0).

fix

Use from pybaseball import statcast and upgrade to latest version.

HTTPError: 429 Client Error: Too Many Requests

Exceeding rate limits on Baseball Savant or FanGraphs.

fix

Add delays between requests (time.sleep(1)). Or use cached data after first successful fetch.

KeyError: 'events'

Statcast data column missing; schema changed.

fix

Check df.columns for available columns; the 'events' column may be named differently or absent for certain date ranges.

Upgrade

Version history

2.2.7latest on PyPI · released Sep 8, 2023

Audit

Dependencies

pandasrequiredData manipulation and DataFrame returns

requestsrequiredHTTP requests to baseball data sources

numpyrequiredNumerical operations

lxmlrequiredHTML parsing for web scraping

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/jldbc/pybaseball ↗

packagehttps://pypi.org/project/pybaseball/ ↗