Skip to content

Installation

Before you can use kloppy, you'll need to get it installed. This guide will guide you to a minimal installation that'll work while you walk through the user guide.

Install Python

Being a Python library, kloppy requires Python. Currently, kloppy supports Python version 3.9 — 3.12. Get the latest version of Python at python.org or with your operating system's package manager.

You can verify that Python is installed by typing python from your shell; you should see something like:

1
2
3
4
Python 3.x.y
[GCC 4.x] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

Install kloppy

You've got two options to install kloppy.

Installing an official release with pip

This is the recommended way to install kloppy. Simply run this simple command in your terminal of choice:

1
$ python -m pip install kloppy

You might have to install pip first. The easiest method is to use the standalone pip installer.

Optional dependencies

The default installation includes the core functionality for loading and working with supported event, tracking, and code data. Some workflows need optional packages:

  • pandas: export datasets to pandas DataFrames with to_df().
  • polars: export datasets to Polars DataFrames with to_df().
  • networkx: use the event_pattern_matching module for sequence and pattern queries.

Kloppy defines extras for these dependencies, so you can install only what you need:

1
2
3
$ python -m pip install "kloppy[pandas]"
$ python -m pip install "kloppy[polars]"
$ python -m pip install "kloppy[query]"

The query extra installs networkx. To install all three optional workflows at once, combine the extras:

1
$ python -m pip install "kloppy[pandas,polars,query]"

When working from a local clone, use the same extras with the editable install:

1
$ python -m pip install -e ".[pandas,polars,query]"

Installing the development version

Kloppy is actively developed on GitHub, where the code is always available. You can easily install the development version with:

1
$ pip install git+https://github.com/PySport/kloppy.git

However, to be able to make modifications in the code, you should either clone the public repository:

1
$ git clone git://github.com/PySport/kloppy.git

Or, download the zipball:

1
$ curl -OL https://github.com/PySport/kloppy/archive/master.zip

Once you have a copy of the source, you can embed it in your own Python package, or install it into your site-packages easily:

1
2
$ cd kloppy
$ python -m pip install -e .

Verifying

To verify that kloppy can be seen by Python, type python from your shell. Then at the Python prompt, try to import kloppy:

1
2
>>> import kloppy
>>> print(kloppy.__version__)