Getting started

Introduction

lapbox is a Python library of Formula 1 analysis on top of FastF1: it tells you what the data means, and says so when it can’t.

FastF1 gives you a session’s timing and telemetry. lapbox tells you what they mean: who was quicker where, how fast each car really was once the fuel is taken out, how hard the tyres went off. And when the data can’t support an answer, it says so instead of returning a confident wrong number.

It is the analysis engine behind LapBox, extracted into a library anyone can use on FastF1 data. It is open source (MIT) and on PyPI.

Shell

pip install lapbox

What it does

Module	What it gives you
`lapbox.telemetry`	One lap — corners, braking and full-throttle zones, g-forces, frozen car data — and two laps matched by track position: the time gap, where it changes hands, minisectors. Guide
`lapbox.data`	Seconds columns, pit stops, tyre stints, the gap to the car ahead, time formatting. Guide
`lapbox.practice`	Practice split into runs; long runs told from qualifying simulations; long-run pace and degradation. Guide
`lapbox.pace`	Lap cleaning with an audit, race pace with the fuel taken out, clean air against traffic, consistency, the ideal lap. Guide
`lapbox.tyres`	Degradation per compound across the field, and stint by stint. Guide
`lapbox.plot`	Plotly figures of the results, as an optional extra. They keep the caveats: a refused pair is drawn without its gap, frozen data is shaded. Guide

How it works

FastF1 in, pandas out. Every function takes FastF1’s objects as they come — session.laps, lap.get_telemetry() — with FastF1’s column names, never modifies them, and returns DataFrames or small result objects.
Laps are matched before they are compared. Two laps of the same circuit disagree on their length, so comparing them at equal distances lines one car’s corner up with the other’s straight. compare puts them on the same points of track first, and reports how well that worked.
It refuses rather than guesses. A pair of laps that can’t be matched comes back with matched set to False; an ideal lap that would be misleading comes back as None. Each refusal says why.
Its numbers are measured. Thresholds such as the 15 km/h alignment cut-off come with the measurement behind them, and what lapbox can’t do yet is listed in Limits.
Charts are optional. The core needs only FastF1, pandas, NumPy and SciPy; Plotly comes with the plot extra.

A first look

Max Verstappen against Lando Norris, fastest laps of qualifying at Silverstone 2025:

Python

import fastf1
from lapbox.telemetry import compare, delta_time

session = fastf1.get_session(2025, "Silverstone", "Q")
session.load()
ver = session.laps.pick_drivers("VER").pick_fastest().get_telemetry()
nor = session.laps.pick_drivers("NOR").pick_fastest().get_telemetry()

result = compare(ver, nor, driver_a="VER", driver_b="NOR")
if result.matched:
    print(f"VER ahead by {delta_time(result.aligned).iloc[-1]:+.3f} s at the line")
    gain = result.segments.loc[result.segments["time_delta"].idxmax()]
    print(f"VER gains most from {gain.start_distance:.0f} to {gain.end_distance:.0f} m: {gain.time_delta:+.3f} s")
else:
    print(f"Can't compare: laps differ by {result.residual:.0f} km/h RMS after alignment")

Output

VER ahead by +0.118 s at the line
VER gains most from 2957 to 4765 m: +0.202 s

Every output on these pages was produced by running the code shown on real sessions. The Quickstart continues from here.

Status

lapbox 0.1.0 is the first release. Until 1.0 the API may still change between minor releases (0.2, 0.3, …), and every change is listed in the changelog. The strategy engine moves over from LapBox in 0.2.

Python 3.11 and 3.12 are tested. Questions and bugs go to GitHub issues.

Where to go next

Installationpip, the charts extra, and getting data from FastF1.QuickstartLaps, race pace and tyres on real sessions in a few minutes.Core conceptsInputs, outputs, refusals and the conventions every module shares.API referenceEvery public name, its parameters and what it returns.

These docs describe lapbox 0.1.0. Something wrong or missing? Open an issue.