General Questions
What is tif1?
tif1 is a Python library for Formula 1 data analysis. It provides fast access to timing, telemetry, and weather data from 2018-current, and to Ergast results, lap times, pit stops and standings from 1950-current. Parallel async loading is more than 3x faster than sequential fetching in the benchmark suite.How is tif1 different from fastf1?
tif1 is designed as a faster alternative to fastf1 with API compatibility. Key differences:- Speed: Parallel data loading with async/HTTP/2 (3x+ vs sequential, benchmark-validated)
- Backends: Supports both pandas and polars
- Caching: SQLite + memory LRU vs file-based pickle
- Data Source: TracingInsights CDN (timing, telemetry) and the TracingInsights Stats repository (Ergast tables, jolpica-f1 only as fallback) vs live timing + jolpica-f1
- Focus: Historical data only (no live timing)
Is tif1 free to use?
Yes, tif1 is open source under the MIT License. Use it freely for personal, academic, or commercial projects.What data is available?
- Lap times and sectors (2018-current)
- Official classifications, pit stops and championship standings (1950-current, Ergast data)
- Telemetry (speed, throttle, brake, RPM, gear, DRS)
- Position data (X, Y, Z coordinates)
- Acceleration data (X, Y, Z axes)
- Weather data
- Tire compounds and strategy
- Race control messages
- Driver metadata
Installation & Setup
How do I install tif1?
What Python version do I need?
Python 3.11 or higher is required. Versions 3.11 through 3.15 are tested in CI. On Python 3.14 and later, the cache uses the standard-librarycompression.zstd module instead of the zstandard package. On Python 3.15, the lz4 package is not installed because it has no 3.15 wheels yet. The frame cache uses zstd instead. Cached payloads read on every version. On Python 3.15, a cached frame written with lz4 is a cache miss. tif1 rebuilds it from the cached payload.
Do I need an API key?
No, tif1 does not require any API keys or authentication. All data is publicly available via the TracingInsights CDN.Where is data cached?
By default, data uses FastF1-style OS-specific cache locations: Windows%LOCALAPPDATA%/Temp/tif1, macOS ~/Library/Caches/tif1, and Linux/other POSIX ~/.cache/tif1 when ~/.cache exists (otherwise ~/.tif1). Change this location in the .tif1rc file or with TIF1_CACHE_DIR.
Data Access
Why is my first load slow?
The first access to a session downloads data from the CDN. Later loads read the local cache.session.laps already fetches the lap payloads in parallel. Inside a running event loop, use await session.laps_async() instead.
How do I load data faster?
- Keep caching enabled (default)
- Enable the polars lib:
lib="polars" - Use batch telemetry fetching:
session.get_fastest_laps_tels()
Can I access live timing data?
No, tif1 focuses on historical data (timing and telemetry 2018-current, Ergast results 1950-current). For live timing, use fastf1.How recent is the data?
The TracingInsights data repositories publish a session shortly after it ends. The timing and telemetry files are generated with fastf1 and are available in under a minute after fastf1 has the data. A session that is not published yet raisesDataNotFoundError. The Ergast classification of a round appears in the Stats repository a few hours after jolpica-f1 has it; until then session.results is merged from jolpica-f1.
Why am I getting DataNotFoundError?
Common causes:- The data has not been published yet (check whether the session ended recently)
- The session did not take place (cancelled or postponed)
- A driver code or lap number does not exist in the session (
DriverNotFoundError,LapNotFoundError)
get_session raises EventNotFoundError, a ValueError subclass, with the message No event matching '<name>' in <year>. An event that is not on the calendar of that season, for example "Suzuka" in 2021, raises EventNotInSeasonError, a subclass of EventNotFoundError.
tif1 resolves circuit, city, and country names such as "Spa" or "Silverstone" to the correct event. A misspelled event name such as "Monacco" does not raise: tif1 corrects it to the closest event name and logs a warning. Check the result with session.event["EventName"]. A name that resembles no event, such as "Paris", raises EventNotFoundError. A session name that does not exist raises ValueError and lists the available session names.
Performance
How can I reduce memory usage?
- Use the polars lib
- Process drivers one at a time instead of loading all at once
- Delete DataFrames when done:
del laps - Use categorical dtypes (automatic for
Driver,Team,Compound, andTrackStatuson pandas)
Why is polars faster?
Polars is written in Rust and uses:- Better parallelization across CPU cores
- More efficient memory layout
- Lazy evaluation for query optimization
- Native Arrow format
Can I use multiple backends in one script?
Yes, each session can use a different backend:Errors & Troubleshooting
I Get a NetworkError
Possible causes:- Internet connection issues
- CDN is temporarily down (rare)
- Firewall blocking the CDN hosts (jsDelivr, Hugging Face, StaticDelivr)
- Check the internet connection
- Reset the circuit breaker:
tif1.reset_circuit_breaker() - Enable debug logging:
tif1.setup_logging(logging.DEBUG)
The Cache Is Corrupted
Clear the cache and re-download:Column Names Do Not Match fastf1
tif1 uses the fastf1 column names, which are mostly PascalCase, for exampleLapTime and Speed. The raw JSON keys, such as time, are not column names. The laps table also keeps the lower-case source columns drv, team, and ms1 to ms3. Use the exact column names shown in the Data Schema Reference.
API & Usage
Do I need to call session.load()?
No, tif1 uses lazy loading. Data is fetched automatically at first access:session.load().
How do I get telemetry for all drivers?
Use the optimized batch method:Can I filter by lap number?
Yes, use standard DataFrame filtering:Why does laps["LapTime"] < 90 fail?
LapTime is a timedelta64[ns] column on pandas and a Duration column on polars. On polars, pl.col("LapTime") < 90 compares nanoseconds, so it selects no lap. Compare LapTimeSeconds, which is a float on both backends:
laps[laps["LapTime"] < pd.Timedelta(seconds=90)] also works. On polars, laps_pl.filter(pl.col("LapTime") < pl.duration(seconds=90)) does. See Column types by backend.
How do I get weather data?
Weather is automatically included in the laps DataFrame:Time is timedelta64[ns] on pandas and Duration("ns") on polars. Rainfall is a nullable boolean on both backends. When the weather payload cannot be converted, tif1 logs a warning and returns an empty DataFrame. See Empty Weather or Race Control Table.
Data Quality
Are lap times accurate?
Lap times come from the official timing data that FastF1 reads. For Race sessions, the data pipeline replaces them with the official Ergast/Jolpica lap times where available.Why are some lap times missing?
Lap times can be missing due to:- Pit stops
- Timing system issues
- Very slow laps (FastF1 can drop laps slower than 2:30)
LapTime. The Deleted column flags it, and the fastest-lap functions skip it.
For Race sessions, the data pipeline adds laps that FastF1 drops, such as lap 1, from Ergast/Jolpica. tif1 itself does not fill gaps.
Is telemetry data validated?
Only on request. Pydantic validation is off by default. SetTIF1_VALIDATE_TELEMETRY=true and TIF1_ULTRA_COLD_START=false to validate downloaded telemetry. A payload that fails validation raises InvalidDataError. See Environment Variables.
Advanced Usage
Can I use tif1 in production?
Yes, tif1 is designed for production use with:- Typed exceptions rooted at
TIF1Error - Circuit breaker pattern
- Automatic retries
- SQLite caching for reliability
How do I export data?
On the pandas backend, use the standard pandas export methods. On polars, usewrite_csv, write_parquet, and write_json.
Can I use tif1 with Jupyter?
Yes, tif1 has built-in Jupyter support with rich HTML displays for Session, Driver, and Lap objects.Does tif1 work with async frameworks?
Yes, tif1 uses asyncio internally and provides async methods:await session.laps_async() directly.
How do I analyze tire degradation?
Tire degradation analysis requires tracking lap times over tire life:How do I compare two drivers’ telemetry?
Load the fastest lap of each driver and plot the telemetry:How do I find overtakes?
Detect position changes between consecutive laps:How do I calculate race pace?
Race pace excludes outliers and pit laps:How do I work with sprint races?
Sprint races are accessed like regular sessions:How do I handle missing data?
Missing lap times areNaT (pandas) or null (polars). Missing telemetry gives an empty DataFrame, not an exception. A driver code that is not in the session raises DriverNotFoundError, a subclass of DataNotFoundError and of ValueError (the fastf1 exception):
How do I analyze sector times?
Sector analysis shows where time is gained or lost:How do I use tif1 with Streamlit?
tif1 works with Streamlit for interactive dashboards. Install Streamlit first withpip install streamlit, then start the script with streamlit run app.py:
How do I batch process multiple sessions?
Process multiple sessions efficiently:How do I create custom visualizations?
tif1 provides plotting utilities, and custom visualizations are also possible:Contributing
How can I contribute?
Contributions are welcome! See the Contributing Guide for details.I found a bug, what should I do?
- Check whether the bug is already reported in GitHub Issues
- If not, create a new issue with:
- Minimal reproducible example
- Error message and traceback
- tif1 version (
tif1.__version__) - Python version
Can I request features?
Yes, feature requests are welcome! Open an issue on GitHub with:- Clear description of the feature
- Use case / motivation
- Example of how it would work
Licensing & Legal
What license is tif1 under?
MIT License. Use it freely in any project.Can I use tif1 commercially?
Yes, the MIT License allows commercial use.Who owns the F1 data?
The underlying F1 data is owned by Formula 1. tif1 provides access to publicly available timing data through the TracingInsights project.Related Pages
Troubleshooting
Solve issues.
Getting Started
Usage guide.
Best Practices
Recommended patterns.