Cache - FastF1

Overview

FastF1’s caching system significantly speeds up data loading and prevents exceeding API rate limits. The cache has two stages:

Stage 1: Raw HTTP GET/POST request caching (using SQLite)
Stage 2: Parsed data caching (using pickle files)

Caching is highly recommended for all FastF1 usage.

Cache Class

The Cache class provides class-level methods for configuring and managing the cache.

from fastf1 import Cache

enable_cache()

Enables the API cache. This should be called at the beginning of your script, right after imports.

Cache.enable_cache(
    cache_dir='path/to/cache',
    ignore_version=False,
    force_renew=False,
    use_requests_cache=True
)

Parameters

cache_dir

str

required

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

Environment variables: %LOCALAPPDATA%, $HOME, etc.
User home expansion: ~ or ~user

ignore_version

bool

default:"False"

Ignore if cached data was created with a different version of the API parser.

Not recommended - may cause crashes or errors due to incompatible data.

force_renew

bool

default:"False"

Ignore existing cached data and re-download everything, updating the cache.

use_requests_cache

bool

default:"True"

Enable stage 1 caching (raw HTTP requests). Disable if you only want stage 2 caching.

Example

import fastf1
from fastf1 import Cache

# Enable cache at the start of your script
Cache.enable_cache('~/fastf1_cache')

# Now load data - it will be cached
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()

clear_cache()

Clears all cached data by deleting cache files.

Cache.clear_cache(
    cache_dir=None,
    deep=False
)

Parameters

cache_dir

str | None

default:"None"

Path to the cache directory to clear. If None, uses the default cache directory.

deep

bool

default:"False"

Also clear the stage 1 requests cache (SQLite database). If False, only clears stage 2 pickle files.

Example

# Clear only parsed data (stage 2)
Cache.clear_cache()

# Clear everything including HTTP cache
Cache.clear_cache(deep=True)

# Clear a specific cache directory
Cache.clear_cache(cache_dir='/path/to/cache', deep=True)

Can be called without enabling the cache first.

get_cache_info()

Returns information about the cache directory and its size.

path, size = Cache.get_cache_info()

Returns

path

str | None

Path to the cache directory, or None if cache is not configured

size

int | None

Total size of the cache in bytes, or None if cache is not configured

Example

path, size_bytes = Cache.get_cache_info()

if path:
    size_mb = size_bytes / (1024 * 1024)
    print(f"Cache: {path}")
    print(f"Size: {size_mb:.2f} MB")
else:
    print("Cache not configured")

disabled()

Returns a context manager that temporarily disables the cache.

with Cache.disabled():
    # No caching happens here
    session = fastf1.get_session(2023, 'Monaco', 'R')
    session.load()

Returns

Context manager object

The context manager is not multithreading-safe.

set_disabled()

Disables the cache while keeping the configuration intact.

Cache.set_disabled()

Disables both stage 1 and stage 2 caching. Use set_enabled() to re-enable.

Prefer using disabled() context manager for temporary disabling.

Not multithreading-safe.

set_enabled()

Re-enables the cache after it was disabled with set_disabled().

Cache.set_enabled()

Cache must be properly configured first using enable_cache(). This method only re-enables a previously disabled cache.

offline_mode()

Enables or disables offline mode.

Cache.offline_mode(enabled=True)

Parameters

enabled

bool

required

True to enable offline mode, False to disable

In offline mode:

No actual requests are sent to APIs
Only cached data is returned
Useful for working with unstable internet or freezing cache state

Must be called after enable_cache() when using a custom cache directory.

Example

import fastf1
from fastf1 import Cache

Cache.enable_cache('~/fastf1_cache')
Cache.offline_mode(True)

# Only cached data will be used
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()  # Fails if data not in cache

ci_mode()

Enables or disables CI (Continuous Integration) mode.

Cache.ci_mode(enabled=True)

Parameters

enabled

bool

required

True to enable CI mode, False to disable

In CI mode:

Cached requests are reused even if expired
Every request is only made once and cached indefinitely
Stage 2 (pickle) cache is disabled
Useful for test environments to reduce API calls and increase predictability

Must be called after enable_cache() when using a custom cache directory.

Cache Configuration

The cache directory is determined in order of precedence:

Explicit call to enable_cache()
FASTF1_CACHE environment variable
OS-dependent default location

Default Cache Locations

%LOCALAPPDATA%\Temp\fastf1

Environment Variable

Set the FASTF1_CACHE environment variable to configure the default cache location:

export FASTF1_CACHE="/path/to/cache"

This value is ignored if enable_cache() is called explicitly.

Cache Structure

The cache directory contains:

cache_dir/
├── fastf1_http_cache.sqlite    # Stage 1: HTTP request cache
└── static/                      # Stage 2: Parsed data cache
    ├── 2023/
    │   ├── 2023-05-28_Monaco_Grand_Prix/
    │   │   ├── Qualifying/
    │   │   │   ├── session_info.ff1pkl
    │   │   │   ├── lap_times.ff1pkl
    │   │   │   └── ...
    │   │   └── Race/
    │   └── ...
    └── ...

Manual Cache Management

You can manually delete specific events or sessions:

Navigate to the cache directory
Find the year/event/session folder
Delete the folder

Deleting the SQLite file removes all HTTP request cache. You cannot selectively delete individual requests from it.

Helper Functions

While not part of the Cache class, these module-level functions work with the cache:

enable_cache()

Shorthand for Cache.enable_cache():

import fastf1

fastf1.enable_cache('path/to/cache')
# Equivalent to:
# fastf1.Cache.enable_cache('path/to/cache')

Available at module level for convenience.

Examples

Basic Setup

import fastf1
from fastf1 import Cache

# Enable cache - call this first!
Cache.enable_cache('~/fastf1_cache')

# Load data - will be cached automatically
session = fastf1.get_session(2023, 5, 'Q')
session.load()

# Second time is much faster (loaded from cache)
session2 = fastf1.get_session(2023, 5, 'Q')
session2.load()  # Fast!

Force Refresh

# Ignore cache and re-download everything
Cache.enable_cache('~/fastf1_cache', force_renew=True)

session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()  # Always downloads fresh data

Temporary Cache Disable

Cache.enable_cache('~/fastf1_cache')

# Normal cached loading
session1 = fastf1.get_session(2023, 1, 'Q')
session1.load()

# Temporarily disable cache
with Cache.disabled():
    session2 = fastf1.get_session(2023, 2, 'Q')
    session2.load()  # Not cached

# Cache is enabled again
session3 = fastf1.get_session(2023, 3, 'Q')
session3.load()  # Cached

Check Cache Size

path, size = Cache.get_cache_info()

if path:
    size_gb = size / (1024**3)
    print(f"Cache location: {path}")
    print(f"Cache size: {size_gb:.2f} GB")
    
    if size_gb > 5:
        print("Cache is large, consider clearing it")
        # Cache.clear_cache(deep=True)

Working Offline

import fastf1
from fastf1 import Cache

# First, load data with internet connection
Cache.enable_cache('~/fastf1_cache')
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()  # Downloads and caches

# Later, work offline
Cache.offline_mode(True)
session = fastf1.get_session(2023, 'Monaco', 'Q')
session.load()  # Works! Uses cached data

session2 = fastf1.get_session(2023, 'Monza', 'Q')
session2.load()  # Fails if not previously cached

Best Practices

Always enable caching

Caching dramatically improves performance and prevents hitting API rate limits. Always call enable_cache() at the start of your script.

import fastf1

# First thing after imports!
fastf1.Cache.enable_cache('~/fastf1_cache')

Use version checking

Keep ignore_version=False (default) to avoid loading incompatible cached data after FastF1 updates.

Manage cache size

The cache can grow large over time. Periodically check and clear it:

path, size = Cache.get_cache_info()
if size and size > 10 * 1024**3:  # 10 GB
    Cache.clear_cache(deep=True)

Don't commit cache to version control

Add your cache directory to .gitignore:

# .gitignore
fastf1_cache/

Notes

Cached requests do not count towards API rate limits.

HTTP cache (stage 1) uses cache control headers and refreshes periodically (every 12 hours by default).

Deleting cache files reclaims disk space but means you’ll need to re-download data, which takes time and counts towards API rate limits.

Core API

Data Access

Visualization

Utilities

​Overview

​Cache Class

​enable_cache()

​Parameters

​Example

​clear_cache()

​Parameters

​Example

​get_cache_info()

​Returns

​Example

​disabled()

​Returns

​set_disabled()

​set_enabled()

​offline_mode()

​Parameters

​Example

​ci_mode()

​Parameters

​Cache Configuration

​Default Cache Locations

​Environment Variable

​Cache Structure

​Manual Cache Management

​Helper Functions

​enable_cache()

​Examples

​Basic Setup

​Force Refresh

​Temporary Cache Disable

​Check Cache Size

​Working Offline

​Best Practices

​Notes

​See Also

Build docs developers (and LLMs) love

Overview

Cache Class

enable_cache()

Parameters

Example

clear_cache()

Parameters

Example

get_cache_info()

Returns

Example

disabled()

Returns

set_disabled()

set_enabled()

offline_mode()

Parameters

Example

ci_mode()

Parameters

Cache Configuration

Default Cache Locations

Environment Variable

Cache Structure

Manual Cache Management

Helper Functions

enable_cache()

Examples

Basic Setup

Force Refresh

Temporary Cache Disable

Check Cache Size

Working Offline

Best Practices

Notes

See Also