glicko2

A pure Python implementation of the Glicko-2 rating system (Glickman, 2012).

Zero dependencies. Fully typed. Usable as a standalone library or as the rating backend for glicko_eval.

Installation

pip install glicko2-py
# with PostgreSQL support:
pip install "glicko2-py[postgres]"

Quick start

from glicko2 import RatingEngine, MatchResult, RatingPeriod

engine = RatingEngine(tau=0.5)

# Players are auto-created on first use, or register explicitly:
engine.pool.get_or_create("alice")
engine.pool.get_or_create("bob")

period = RatingPeriod(id="round-1")
period.add_match(MatchResult("alice", "bob", 1.0))  # one entry per game

engine.process_period(period)  # engine derives bob's perspective automatically

from glicko2.math.conversions import mu_to_rating, phi_to_rd

alice = engine.pool.get("alice")
print(mu_to_rating(alice.mu))   # display rating  (~1537)
print(phi_to_rd(alice.phi))     # rating deviation (~192)

Core concepts

Math

All rating math lives in glicko2.math and is composed of pure functions with no side effects.

from glicko2.math import g, E, update_rating
from glicko2.math import rating_to_mu, rd_to_phi, mu_to_rating, phi_to_rd
from glicko2.math import rating_interval, win_probability

The update_rating() function implements the full Glickman algorithm including the Illinois (regula falsi) root-finding method for the iterative volatility update (Step 5).

Reference values (Glickman 2012, Table 1)

Tournament formats

from glicko2.tournament import round_robin, swiss, adaptive
from glicko2.tournament import all_below_rd_threshold, top_k_separated

Storage backends

from glicko2.storage import SQLiteStorage

storage = SQLiteStorage("ratings.db")
storage.save_player(engine.pool.get("alice"))
alice = storage.load_player("alice")

Note: PostgresStorage connects and migrates the schema but all CRUD methods raise NotImplementedError. Do not use it in production yet.

Rating inflation utilities

from glicko2.engine import detect_inflation, normalize_ratings, soft_reset

# Detect mean drift
drift = detect_inflation(engine.pool)

# Shift all ratings so the mean returns to 0
normalize_ratings(engine.pool)

# Move ratings halfway back toward defaults (e.g. between seasons)
soft_reset(engine.pool, compression=0.5)

Parameter guidance

Running tests

From the monorepo root:

uv run pytest packages/glicko2/tests/