# roboflow/sports: a Python source install for soccer and basketball vision pipelines

> roboflow/sports is a Roboflow repository of reusable computer vision tools for sports analytics, distributed as a source install rather than a published package. It ships example notebooks and points at hosted datasets, but the README leaves most of the pipeline for you to assemble.

**roboflow/sports** — computer vision and sports

- Repository: https://github.com/roboflow/sports
- Stars: 5,396 · Forks: 664
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/roboflow-sports

## What roboflow/sports is for, and who should care

Roboflow describes this repository as a testing ground. The README says the company uses sports to push its object detection, image segmentation, keypoint detection, and foundational models, and that the repository contains reusable tools that can be applied in sports and beyond. That framing matters: the primary audience is people building sports analytics pipelines with Roboflow's model stack, not teams looking for a finished analytics product.

The README lists five problems the project is meant to tackle. Ball tracking is hard because the ball is small and moves fast, especially in high-resolution video. Reading jersey numbers fails on blurry footage, players facing away, or occluded numbers. Player tracking breaks under frequent occlusions. Re-identification is difficult when players leave and re-enter the frame, or when a camera moves. Camera calibration is needed for statistics such as player speed and distance traveled, and is complicated by changing camera angles.

If your work sits in one of those five areas and you are comfortable wiring models together, the repository is aimed at you. If you want a library that answers those questions out of the box, the README does not claim to be one.

## How the repository is put together

The top level contains four entries that matter: README.md, LICENSE, setup.py, and two directories, examples/ and sports/. The examples directory has a soccer subdirectory. That is the whole visible layout.

setup.py declares the package name as sports, version 0.1.0, with python_requires set to >=3.8. The author is listed as Piotr Skalski, the licence as MIT, and the classifier Development Status as 4 - Beta. The install_requires list names supervision, numpy, opencv-python, transformers, umap-learn, scikit-learn, tqdm, sentencepiece, and protobuf. A tests extra adds pytest.

That dependency set tells you what kind of code to expect. supervision supplies the annotation and tracking primitives, opencv-python handles video and image I/O, transformers and sentencepiece point at model inference, and umap-learn with scikit-learn suggests embedding work such as the image-embeddings topic. The repository does not publish a module map, so the shape of the sports package has to be read from the source itself.

The README does not document an inference API, a command line entry point, or a configuration format. There is no CLI to learn, and no config file to write. Whatever orchestration exists lives in the example notebooks and in the package code.

## Installing roboflow/sports from source

There is no Python package on PyPI. The README states this directly: "We don't have a Python package yet. Install from source in a Python>=3.8 environment." The install command is a pip install against the git URL.

```bash
pip install git+https://github.com/roboflow/sports.git
```

That pulls the repository and its dependencies into your environment. Because the install is from a git URL rather than a released wheel, pip resolves the default branch at install time; there is no version pin unless you add one to the URL yourself, and no release notes to consult for breaking changes.

A first real use is to open the example notebooks under examples/soccer/. The README does not describe their contents, so treat them as the reference for how the maintainers expect the pieces to be combined. Alongside the notebooks, the README points at hosted datasets on Roboflow Universe for the tasks the repository targets.

```bash
pip install git+https://github.com/roboflow/sports.git
python -c "import sports; print(sports.__file__)"
```

The second command confirms which copy of the package your interpreter picks up, which is worth checking before you debug anything else, because a stale clone or a virtual environment mismatch will otherwise look like a bug in the library.

## The datasets the README points at, and what they cover

The repository does not ship training data. It links out to Roboflow Universe, where the README lists five datasets by task: soccer player detection, soccer ball detection, soccer pitch keypoint detection, basketball court keypoint detection, and basketball jersey numbers OCR. Each link goes to a Roboflow Universe project page.

This is a deliberate split. The repository holds code and examples; the data lives on a hosted service with its own download flow and its own licence terms. That means your effective dependency surface is larger than the Python package. If you work in an environment where downloading datasets from a hosted platform is not acceptable, the code may still be useful, but you will need to substitute your own annotated data for each of the five tasks.

The five tasks map onto the five challenges in the README, with one gap worth naming: camera calibration is listed as a challenge, but the dataset table has no calibration dataset. Pitch and court keypoint detection are the closest thing, since keypoints are what you would use to estimate a homography. The README does not state that connection explicitly.

## Where roboflow/sports runs into trouble

The most concrete limitation is packaging. Installing from a git URL means every environment you build is a fresh resolution against the default branch. There is no tagged release on PyPI, and setup.py pins no dependency versions at all. supervision, transformers, and opencv-python all move quickly, and an unpinned install can break without anything in this repository changing.

The second limitation is documentation depth. The README explains the challenges and links the datasets, but it does not document the sports package's modules, the expected input format for a video, or the output schema of any pipeline. The notebooks under examples/soccer/ are the only worked examples, and the README does not summarise them. Anyone adopting this should expect to read source code rather than documentation.

The third is scope. The examples directory contains soccer only. Basketball appears in the dataset table and in the repository topics, but the README does not point at a basketball example. If your sport is not soccer or basketball, the repository offers general-purpose tools and nothing tailored.

Finally, this is the wrong tool if you need accuracy guarantees. The README publishes no benchmark numbers for ball tracking, jersey OCR, or re-identification. Those are the hard problems it names, and it does not claim to have solved them to any measured standard. Treat the repository as a starting point for your own evaluation, not as a validated component.

## How this differs from a general tracking library

The nearest alternative in practice is supervision, which is already a dependency here. The difference in approach is one of scope. supervision is a general-purpose library of annotation, detection, and tracking utilities that you apply to any video problem. roboflow/sports is a collection of sports-specific tools and examples built on top of that layer, aimed at the five sports problems in the README.

Choosing between them is not really a choice. If you install roboflow/sports you get supervision as a dependency, and you can use supervision directly for anything the sports package does not cover. What roboflow/sports adds is the sports framing: the example notebooks, the pointer to pitch and court keypoint datasets, and whatever domain logic lives in the sports package.

If you are building a general video analytics pipeline and sport is incidental, start with supervision and skip this repository. If your problem is specifically tracking a ball, reading jersey numbers, or calibrating a pitch view, the sports-specific examples are the reason to look here first.

## Maintenance, licence, and the cost of upgrading

The repository is not archived. The last push was on 2026-08-28, which is recent enough that the codebase is being touched. The most recent release listed is soccer-analytics-pr-demos from 2026-07-06, described as soccer analytics PR demo renders, which suggests the release channel is used for demo artefacts rather than versioned library builds. There is no changelog in the repository layout.

The practical upgrade cost follows from the missing package release. Because installation is from a git URL, upgrading means reinstalling from the branch and re-resolving every dependency. Without version pins in setup.py, a reinstall can pull newer versions of supervision, transformers, or opencv-python than the code was written against. If you deploy this, pin the git commit hash in your own requirements file rather than tracking the branch, and freeze the resolved dependency set after your first successful install.

The licence is MIT, declared both in setup.py and in the LICENSE file at the top level. That is a permissive licence, and it applies to the code in this repository. It does not automatically apply to the Roboflow Universe datasets the README links; those are separate projects on a separate platform with their own terms, which you should read before using them. Nothing here is legal advice, and if the datasets are central to your product you should have the terms reviewed.

## Conclusion

Adopt roboflow/sports if you are a Python developer who already works with supervision and object detection models and wants a starting point for soccer or basketball analytics, and you accept assembling the pipeline yourself. Do not adopt it if you need a supported library with a stable API, a published package, or documented accuracy figures; the README publishes none of those. Before writing code against it, verify three things: that the pip install from the git URL resolves on your Python version, that the sports package exposes the modules your pipeline needs, and that the Roboflow Universe datasets you plan to use are the ones named in the README.

## FAQ

### Is roboflow/sports available as a Python package on PyPI?

No. The README states that there is no Python package yet and that you should install from source in a Python>=3.8 environment using pip against the git URL.

### What dependencies does roboflow/sports install?

setup.py lists supervision, numpy, opencv-python, transformers, umap-learn, scikit-learn, tqdm, sentencepiece, and protobuf, with pytest available through a tests extra. No dependency versions are pinned.

### Which sports does roboflow/sports cover?

The README lists datasets for soccer player detection, soccer ball detection, soccer pitch keypoint detection, basketball court keypoint detection, and basketball jersey numbers OCR. The examples directory contains a soccer subdirectory.

### What licence does roboflow/sports use?

The MIT licence, declared in setup.py and included as a LICENSE file at the top level of the repository. The linked Roboflow Universe datasets are separate projects with their own terms.

## Sources

- [Issues](https://github.com/roboflow/sports/issues)
- [License: MIT](https://github.com/roboflow/sports/blob/main/LICENSE)
- [README](https://github.com/roboflow/sports/blob/main/README.md)
- [Releases](https://github.com/roboflow/sports/releases)
- [roboflow/sports on GitHub](https://github.com/roboflow/sports)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/roboflow-sports