Requirements
- Python: 3.11 or higher (3.11 through 3.15 are tested in CI)
- OS: Windows, macOS, or Linux
- Browser: Pyodide 314 or later (JupyterLite, PyScript, marimo). Refer to Pyodide and the Browser
Quick Install
1
Choose a package manager
tif1 is available on PyPI. Install it with a package manager.2
Check what comes with it
tif1 installs pandas and polars together with its plotting dependencies. There is no separate extra for the Polars backend. Select it at runtime with lib="polars" or TIF1_LIB=polars.The only extra is dev. It adds the test and lint toolchain for contributors.3
The native telemetry decoder
tif1-native is a small Rust extension in the native/ directory of the repository. pip install tif1 installs it as a dependency on CPython for Linux, macOS and Windows (x86_64 and arm64). On other platforms, build it with the commands below. When it is importable, tif1 decodes telemetry payloads with it. The JSON scan runs without the GIL and produces typed numpy arrays. The DriverAhead channel comes back as codes into a short list of driver numbers, not one Python string per sample. A session that rebuilds its telemetry frames from the cached payloads loads about twice as fast on multi-core machines. That happens on the first load after a cold load, or after an upgrade that changes the frame format. The frames are identical with and without it, and tif1 works without it. The build needs a Rust toolchain and maturin.TIF1_DISABLE_NATIVE=1 before starting Python.4
Optional: install in the browser
Pyodide installs Load sessions with
tif1 with micropip. The Pyodide distribution provides the native packages; the polars backend is not available there.Pyodide
await session.load_async(). Refer to Pyodide and the Browser for the details.5
Verify the installation
Run this check to confirm that the installation works:
Configuration
Environment Variables
Configuretif1 with environment variables. They are useful in CI/CD environments.
The default cache directory follows the FastF1 platform layout. It uses
tif1 as the application directory:
- Windows:
%LOCALAPPDATA%/Temp/tif1 - macOS:
~/Library/Caches/tif1 - Linux and other POSIX systems:
~/.cache/tif1when~/.cacheexists, otherwise~/.tif1
TIF1_CACHE_DIR, or set cache_dir in .tif1rc, to override the default.
Config File (.tif1rc)
For permanent settings, create a.tif1rc (JSON) file in the home directory:
Advanced Troubleshooting
HTTP/2 SSL Errors
HTTP/2 SSL Errors
tif1 uses niquests for HTTP/2 support. If SSL errors occur, update the system openssl version. Also check that the certificate store has a correct configuration.SQLite Database Locking
SQLite Database Locking
“Database is locked” errors show that multiple processes write to the cache at the same time.
tif1 uses WAL mode to reduce this problem. Very high concurrency on slow disks can still trigger the error.Polars Version Mismatch
Polars Version Mismatch
tif1 requires polars>=2.0.0,<3 and installs it automatically. Polars 1.x is not supported. Upgrade an older installation with pip install -U "polars>=2.0.0,<3".Related Pages
Quickstart
Start using tif1
Configuration
Configure tif1
Troubleshooting
Solve common issues
Environment Variables
Configure with environment variables