Skip to main content

Install and the command line

sportsdataverse-py supports Python 3.10 through 3.14 and runs on polars 2 (polars>=2.0,<3). polars 1.x is no longer supported. Every loader and wrapper returns a polars DataFrame by default, and most accept return_as_pandas=True if you want pandas instead.

Install with pip or uv​

pip install --pre sportsdataverse # 0.2.0b1, the 0.2.0 beta

Without --pre, pip installs 0.1.4, the latest final release, until 0.2.0 ships.

With uv, which the project uses day to day:

uv add sportsdataverse

# the latest commit on main, ahead of the next release
uv add "sportsdataverse @ git+https://github.com/sportsdataverse/sportsdataverse-py"

For a development checkout, clone the repository and sync every extra into the checkout's own .venv:

git clone https://github.com/sportsdataverse/sportsdataverse-py.git
cd sportsdataverse-py
uv sync --all-extras
uv run pytest

CONTRIBUTING.md in the repository covers the rest of the contributor workflow (lint, type checks, live-test gates, changelog fragments).

Optional extras​

The extras are defined in [project.optional-dependencies] in pyproject.toml. None of them is needed for the core loaders and ESPN wrappers.

ExtraInstallWhat it adds
testspip install "sportsdataverse[tests]"pytest, mypy, ruff, curl_cffi, kloppy and pyyaml: the test toolchain
soccerpip install "sportsdataverse[soccer]"kloppy for soccer event and tracking data (soccer_open_events)
nflpropip install "sportsdataverse[nflpro]"Playwright, for the NFL Pro (pro.nfl.com) Next Gen Stats client
modelspip install "sportsdataverse[models]"Nothing. It is kept so that existing [models] installs keep working; the models ship in the wheel
pffpip install "sportsdataverse[pff]"Playwright, for the optional headless sign-in of the legacy PFF Premium client
sdvplotpip install "sportsdataverse[sdvplot]"sdvplot 0.1.1 or later with matplotlib (sdvplot[mpl]): team logos, colors and chart themes
sportypypip install "sportsdataverse[sportypy]"sportypy: rulebook fields, rinks and courts to draw coordinates on
mcppip install "sportsdataverse[mcp]>=0.2.0b1"The mcp SDK, for the sdv-docs MCP server
allpip install "sportsdataverse[all]"Every extra above except mcp, plus patchright (the stats.ncaa.org browser transport)

Three notes on the extras:

  • [all] leaves out mcp. Install sportsdataverse[all,mcp] to get both.
  • sportypy is GPL-3.0. sportsdataverse-py is MIT and never bundles it; the extra installs it beside the package, so check that the GPL fits your project before you depend on it. sdvplot is MIT.
  • curl_cffi is in tests and all only. The stats.nba.com / stats.wnba.com wrappers need it for live calls, as do a few international basketball sites. If it is missing, those calls raise an ImportError that names it (pip install curl_cffi). See Troubleshooting.

The sdvplot extra installs sdvplot[mpl], so matplotlib comes with it. For another backend, add sdvplot's own extra: pip install "sdvplot[plotly]" or "sdvplot[altair]".

The sdv command line​

Installing the package puts an sdv console script on your path. It resolves names to ESPN ids, searches the function index and controls the package-wide HTTP response cache, without writing any Python. On a terminal it prints styled cards and tables (team cards in the team's own colours, tables sized to the window); piped or with NO_COLOR set, the output is plain. The --json flag prints JSON for piping to jq; put it before the subcommand (sdv --json find-team ...), which both CLIs below accept. The new CLI also takes it after the subcommand. sdv --help and sdv <command> --help list every command and option.

The CLI is built on cyclopts and Rich and needs Python 3.11 or newer. On Python 3.10, or in an environment without cyclopts or Rich, sdv runs the classic CLI instead: the same commands, flags, --json output and exit codes, in plain text. The conda package needs Python 3.11 or newer and always installs the new CLI.

CommandWhat it does
sdv find-team NAME --league LG [--multi]Resolve a team name to its ESPN team record
sdv find-athlete NAME --league LG [--team TEAM] [--multi]Resolve an athlete name; --team narrows the search and speeds it up
sdv find-event DATE --league LG [--home TEAM] [--away TEAM] [--multi]Resolve a game on a date (YYYY-MM-DD or YYYYMMDD) to its ESPN event
sdv list-functions [--league LG] [--search TEXT] [--parsers-only | --wrappers-only]Search the callable index
sdv function-count [--league LG]Count the callables per league
sdv cache mode [--set off|memory|filesystem]Print or set the HTTP response cache mode
sdv cache statsShow the cache's entries, bytes on disk and mode
sdv cache clear [--pattern GLOB]Drop cached entries, all of them or those matching a filename glob

The --league choices for the find-* commands are nba, wnba, mbb, wbb, cfb, nfl, mlb and nhl. list-functions and function-count take any league or provider group the package has, such as euroleague or pwhl.

sdv find-team lakers --league nba # a card: id 13, LAL, colours, clubhouse link
sdv find-team "Lakres" -l nba # no match: exit 1, with "did you mean Los Angeles Lakers?"
sdv --json find-event 2025-02-09 -l nfl # {"id": "401671889", ... "Kansas City Chiefs at Philadelphia Eagles"}
sdv list-functions -l nba -s roster # espn_nba_game_rosters, espn_nba_team_roster, ...
sdv cache stats # mode off · entries 0 · disk bytes 0 B

Exit codes: 0 when the command succeeded (for find-*, a match was found), 1 when a find-* command found no match, and 2 on an error, printed as sdv: <message> on stderr, or a usage error such as a missing --league. An error covers invalid input, a host that answered "nothing there" (NoDataError) and a fetch that failed (AssetFetchError).

The cache commands control the response cache that the package's HTTP layer checks before going to the network (sportsdataverse.cache; it is off by default). That cache is separate from the NFL loaders' cache, which the NFL cache recipe covers.

The sdv-docs MCP server​

sdv-docs is a Model Context Protocol server that lets an AI assistant search this documentation: the function reference, the Returns tables, the endpoint metadata and the R packages' indexes. It needs the mcp extra:

pip install "sportsdataverse[mcp]>=0.2.0b1" # 0.1.4 has no sdv-docs; the pin upgrades it
sdv-docs --version

With no arguments sdv-docs serves its tools over stdio, so you register it with your MCP client as a command (sdv-docs). It exposes six tools: search, get_function, find_columns, find_endpoints, list_datasets and index_info.

The server never imports sportsdataverse itself, so it starts in about a second. It reads a prebuilt SQLite index, downloaded on first use from the docs-index release of the repository, cached locally and re-checked at most once a day. Set SDV_DOCS_DB to the path of an index file to use that file and never download.