Caching

FastF1’s caching system dramatically improves performance by storing downloaded and processed data locally. This prevents re-downloading the same data and speeds up subsequent runs.

Why Use Caching?

Without caching:

Every script run downloads data from F1 APIs
Processing and parsing must be repeated
You may hit API rate limits
Scripts take much longer to run

With caching enabled:

Data is downloaded once and reused
Processing is done once and stored
Scripts run 10-100x faster after first run
Reduced load on F1 APIs

It is highly recommended to always enable caching. The performance improvement is substantial, and it helps prevent exceeding API rate limits.

Quick Start

Enable caching at the start of your script:

import fastf1

# Enable cache - create this directory first!
fastf1.Cache.enable_cache('path/to/cache')

# Now use FastF1 as normal
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()  # First run: downloads and caches

On subsequent runs with the same data:

import fastf1

fastf1.Cache.enable_cache('path/to/cache')

session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()  # Much faster - uses cached data!

Enabling the Cache

enable_cache()

Cache.enable_cache(
    cache_dir: str,
    ignore_version: bool = False,
    force_renew: bool = False,
    use_requests_cache: bool = True
)

cache_dir

str

required

Path to the directory for storing cached data. The directory must already exist.Supports:

Absolute paths: '/home/user/fastf1_cache'
Home directory: '~/fastf1_cache'
Environment variables: '%LOCALAPPDATA%/fastf1_cache' (Windows)

ignore_version

bool

default:"False"

If True, uses cached data even if it was created with a different FastF1 version.

Not recommended - incompatible cached data may cause crashes or errors.

force_renew

bool

default:"False"

If True, ignores all existing cached data and downloads fresh data.

use_requests_cache

bool

default:"True"

Enable caching of raw HTTP requests (stage 1 cache).

Example Usage

import fastf1

# Enable cache with default settings
fastf1.Cache.enable_cache('cache')

Cache Location

You can specify the cache location in three ways (in order of precedence):

1. Explicit Configuration

Call enable_cache() with a path:

import fastf1

fastf1.Cache.enable_cache('/path/to/cache')

2. Environment Variable

Set the FASTF1_CACHE environment variable:

# Linux/macOS
export FASTF1_CACHE="/home/user/fastf1_cache"

# Windows
set FASTF1_CACHE=C:\Users\User\fastf1_cache

Then in your script:

import fastf1

# Automatically uses FASTF1_CACHE environment variable
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()

3. Default Location

If neither is specified, FastF1 uses an OS-dependent default:

Windows

%LOCALAPPDATA%\Temp\fastf1Typically: C:\Users\YourName\AppData\Local\Temp\fastf1

macOS

~/Library/Caches/fastf1Full path: /Users/YourName/Library/Caches/fastf1

Linux

~/.cache/fastf1 (if ~/.cache exists)Otherwise: ~/.fastf1

When using the default cache location, FastF1 will create the directory automatically and display a warning message.

How Caching Works

FastF1 uses a two-stage caching system:

Stage 1: HTTP Request Cache

Raw GET and POST requests are cached in a SQLite database:

File: fastf1_http_cache.sqlite in the cache directory
Caches raw API responses
Applies cache control and expiration (12 hours by default)
Reduces network requests

Stage 2: Parsed Data Cache

Processed and parsed data is cached as pickle files:

Files: *.ff1pkl in session-specific subdirectories
Caches Python objects after parsing
Saves computation time
Organized by year/event/session

cache/
├── fastf1_http_cache.sqlite          # Stage 1: HTTP cache
└── 2023/                               # Year
    └── 1/                              # Round number
        └── Bahrain Grand Prix/         # Event name
            └── Qualifying/             # Session name
                ├── timing_data.ff1pkl
                ├── timing_app_data.ff1pkl
                └── ...

Cache Information

Get information about the current cache:

import fastf1

fastf1.Cache.enable_cache('cache')

# Get cache info
path, size = fastf1.Cache.get_cache_info()

if path:
    print(f"Cache location: {path}")
    print(f"Cache size: {size / (1024**3):.2f} GB")
else:
    print("Cache not configured")

# Print cache representation
print(fastf1.Cache)
# Output: FastF1 cache (1.23 GB) /path/to/cache

Managing the Cache

Clearing the Cache

Delete all cached data:

import fastf1

# Clear only parsed data (stage 2)
fastf1.Cache.clear_cache('path/to/cache')

# Clear everything including HTTP cache (stage 1)
fastf1.Cache.clear_cache('path/to/cache', deep=True)

You can call clear_cache() without enabling the cache first.

Manual Cache Management

You can manually delete cache files:

# Delete cache for a specific session
rm -rf cache/2023/5/Miami\ Grand\ Prix/Qualifying/

# Delete entire year
rm -rf cache/2023/

# Delete HTTP cache only
rm cache/fastf1_http_cache.sqlite

Cache Size Management

The cache can grow large over time. Typical sizes:

Single qualifying session: 5-15 MB
Single race: 20-50 MB
Full season (all sessions): 3-8 GB

To manage size:

Clear old/unused data regularly
Use selective loading (disable telemetry if not needed)
Store cache on a drive with sufficient space

Temporarily Disabling Cache

Disable caching for specific code sections:

Using Context Manager

import fastf1

fastf1.Cache.enable_cache('cache')

# Normal caching
session1 = fastf1.get_session(2023, 'Monaco', 'Q')
session1.load()  # Uses cache

# Temporarily disable
with fastf1.Cache.disabled():
    session2 = fastf1.get_session(2023, 'Silverstone', 'Q')
    session2.load()  # No caching

# Caching re-enabled
session3 = fastf1.get_session(2023, 'Spa', 'Q')
session3.load()  # Uses cache again

Manual Control

import fastf1

fastf1.Cache.enable_cache('cache')

# Disable cache
fastf1.Cache.set_disabled()
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()  # No caching

# Re-enable cache
fastf1.Cache.set_enabled()
session = fastf1.get_session(2023, 'Spa', 'Q')
session.load()  # Uses cache

Offline Mode

Work with cached data without internet:

import fastf1

fastf1.Cache.enable_cache('cache')
fastf1.Cache.offline_mode(enabled=True)

# Only cached data will be used
# No network requests will be made
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()  # Only works if data is cached

Useful for:

Working without internet connection
Ensuring reproducible results
Preventing accidental data updates

Performance Benefits

Real-world performance comparison:

Without Cache

import fastf1
import time

# No cache
start = time.time()
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()
end = time.time()

print(f"Loading time: {end - start:.2f} seconds")
# Output: Loading time: 45.23 seconds

With Cache (First Run)

import fastf1
import time

fastf1.Cache.enable_cache('cache')

start = time.time()
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()
end = time.time()

print(f"Loading time: {end - start:.2f} seconds")
# Output: Loading time: 42.18 seconds (similar to no cache)

With Cache (Subsequent Runs)

import fastf1
import time

fastf1.Cache.enable_cache('cache')

start = time.time()
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()
end = time.time()

print(f"Loading time: {end - start:.2f} seconds")
# Output: Loading time: 1.34 seconds (30x faster!)

Advanced Features

CI Mode

For continuous integration environments:

import fastf1

fastf1.Cache.enable_cache('cache')
fastf1.Cache.ci_mode(enabled=True)

# In CI mode:
# - Cached requests are reused even if expired
# - Each request is made only once and cached forever
# - Pickle cache (stage 2) is disabled
# - Good for test reproducibility

Version Handling

When FastF1 is updated, cached data from older versions may be incompatible:

import fastf1

# Default: requires matching version
fastf1.Cache.enable_cache('cache')
# Cached data from different version will be refreshed

# Ignore version mismatch (not recommended)
fastf1.Cache.enable_cache('cache', ignore_version=True)
# Uses cached data regardless of version

Best Practices

Always Enable Caching in Scripts

Start every script with cache enablement:

import fastf1

fastf1.Cache.enable_cache('cache')

# Rest of script...

Use a Dedicated Cache Directory

Don’t mix cache files with your project files:

# Good
fastf1.Cache.enable_cache('/var/cache/fastf1')

# Less ideal
fastf1.Cache.enable_cache('./cache')  # Mixed with project

Create Cache Directory First

Ensure the directory exists before enabling cache:

import os
import fastf1

cache_dir = 'cache'
if not os.path.exists(cache_dir):
    os.makedirs(cache_dir)

fastf1.Cache.enable_cache(cache_dir)

Periodically Clear Old Data

Clean up cache for sessions you no longer need:

# Clear everything
fastf1.Cache.clear_cache('cache', deep=True)

# Or manually delete old years
# rm -rf cache/2018 cache/2019

Monitor Cache Size

Check cache size periodically:

path, size = fastf1.Cache.get_cache_info()
if size > 10 * 1024**3:  # 10 GB
    print("Cache is getting large, consider cleaning")

Troubleshooting

Cache Not Working

If caching doesn’t seem to work:

Verify directory exists

import os
cache_dir = 'path/to/cache'
print(f"Exists: {os.path.exists(cache_dir)}")

Check cache is enabled

import fastf1
fastf1.Cache.enable_cache('cache')
path, _ = fastf1.Cache.get_cache_info()
print(f"Cache enabled: {path is not None}")

Verify files are created
```
ls -lh cache/
```

Version Mismatch Errors

If you see version mismatch warnings:

# Option 1: Clear cache and download fresh data
fastf1.Cache.clear_cache('cache', deep=True)

# Option 2: Ignore version (not recommended)
fastf1.Cache.enable_cache('cache', ignore_version=True)

Permission Errors

If you get permission errors:

# Linux/macOS: Fix permissions
chmod -R u+w cache/

# Or use a different directory

Loading Data - Understanding what data is cached
Sessions and Events - Basic session loading

Get Started

Core Concepts

Guides

Examples

Why Use Caching?

Quick Start

Enabling the Cache

enable_cache()

Example Usage

Cache Location

1. Explicit Configuration

2. Environment Variable

3. Default Location

How Caching Works

Stage 1: HTTP Request Cache

Stage 2: Parsed Data Cache

Cache Information

Managing the Cache

Clearing the Cache

Manual Cache Management

Cache Size Management

Temporarily Disabling Cache

Using Context Manager

Manual Control

Offline Mode

Performance Benefits

Without Cache

With Cache (First Run)

With Cache (Subsequent Runs)

Advanced Features

CI Mode

Version Handling

Best Practices

Troubleshooting

Cache Not Working

Version Mismatch Errors

Permission Errors

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Examples

​Why Use Caching?

​Quick Start

​Enabling the Cache

​enable_cache()

​Example Usage

​Cache Location

​1. Explicit Configuration

​2. Environment Variable

​3. Default Location

​How Caching Works

​Stage 1: HTTP Request Cache

​Stage 2: Parsed Data Cache

​Cache Information

​Managing the Cache

​Clearing the Cache

​Manual Cache Management

​Cache Size Management

​Temporarily Disabling Cache

​Using Context Manager

​Manual Control

​Offline Mode

​Performance Benefits

​Without Cache

​With Cache (First Run)

​With Cache (Subsequent Runs)

​Advanced Features

​CI Mode

​Version Handling

​Best Practices

​Troubleshooting

​Cache Not Working

​Version Mismatch Errors

​Permission Errors

​Related Topics

Build docs developers (and LLMs) love

Why Use Caching?

Quick Start

Enabling the Cache

enable_cache()

Example Usage

Cache Location

1. Explicit Configuration

2. Environment Variable

3. Default Location

How Caching Works

Stage 1: HTTP Request Cache

Stage 2: Parsed Data Cache

Cache Information

Managing the Cache

Clearing the Cache

Manual Cache Management

Cache Size Management

Temporarily Disabling Cache

Using Context Manager

Manual Control

Offline Mode

Performance Benefits

Without Cache

With Cache (First Run)

With Cache (Subsequent Runs)

Advanced Features

CI Mode

Version Handling

Best Practices

Troubleshooting

Cache Not Working

Version Mismatch Errors

Permission Errors

Related Topics