pybaseball

If you use Retrosheet data in a product or transfer it, you must prominently include the following statement:

The information used here was obtained free of charge from and is copyrighted by Retrosheet. Interested parties may contact Retrosheet at "www.retrosheet.org".

The cache operates at the function parameter level. A cache hit occurs only when a function is called with the exact same parameters as a previous call.

Note on subsetting: The cache does not support subsetting. For example, if you call pybaseball.batting_leaders(2000, 2020), a subsequent call to pybaseball.batting_leaders(2010, 2015) will result in a new download/cache entry rather than reusing the existing data, even though the required data is already present in the cache.

Caching is disabled by default. You can enable or disable it using the cache module. When enabled, pybaseball will store downloaded data to a local directory to speed up subsequent requests.

from pybaseball import cache

# Enable the cache
cache.enable()

# Disable the cache
cache.disable()

When pulling Retrosheet data, pybaseball checks requests against the Chadwick Bureau GitHub repository. Unauthenticated requests are limited to 60 queries per hour by the GitHub API. To increase this limit to 5000 queries per hour, you must use a GitHub Personal Access Token.

1. Create a Personal Access Token on GitHub.
2. Set the environment variable GH_TOKEN with your token value:
   • Mac/Linux: Add GH_TOKEN=<your_token> to your .bashrc file.
   • Windows: Add GH_TOKEN to your environment variables via the Start menu.

Providing this token is optional but recommended as it provides more instructive errors by checking against existing files before attempting a download.

You can install pybaseball via pip or directly from the GitHub repository to get the most up-to-date version.

Via pip:

pip install pybaseball

From source:

git clone https://github.com/jldbc/pybaseball
cd pybaseball
pip install -e .

To use the Lahman data acquisition functions, you must first download the entire database to your current working directory using download_lahman().

from pybaseball.lahman import *
download_lahman()

The cache supports two storage mechanisms: 'CSV' and 'Parquet'. The default storage type is Parquet. To change the storage mechanism, update cache.config.cache_type and call cache.config.save() to persist the setting.

from pybaseball import cache

cache.enable()
cache.config.cache_type='csv'
cache.config.save()

To speed up repeated data requests, you can enable a local data cache. Caching is disabled by default.

Enable Cache:

from pybaseball import cache
cache.enable()

Clear Cache: If you are receiving unexpected results (e.g., empty datasets for future dates), clear the cache:

from pybaseball import cache
cache.purge()

If you encounter a concurrent.futures.process.BrokenProcessPool error, it is likely due to the system using spawn-based processes (common on Windows and macOS). To fix this, wrap your library calls within a if __name__ == '__main__': block.

from pybaseball import statcast

if __name__ == '__main__':
    stats = statcast()

When using pitching_stats(), you can use the qual argument to filter for players who meet a specific threshold of plate appearances. This is useful for removing noise from players with very small sample sizes.

Example: Retrieving data for only players who have pitched 50+ innings (or met a specific plate appearance threshold) in a given year.

from pybaseball import pitching_stats

# retrieve data on only players who have pitched 50+ innings this year
data = pitching_stats(2017, qual=50)

To use statcast_pitcher_spin, you must first find the pitcher's MLBAM ID. You can use the playerid_lookup function to search for players by name.

from pybaseball import playerid_lookup

# find Chris Sale's player id (mlbam_key)
playerid_lookup('darvish','yu')