Skip to main content
tif1 can be configured using environment variables or a .tif1rc configuration file. Environment variables take precedence over file-based configuration. Config._load_env in config.py reads every variable on this page. The two exceptions are TIF1_CONFIG_FILE and TIF1_TRUST_CWD_CONFIG, which Config._load_config reads to locate the file. Value parsing. Booleans accept 1, true, yes, on and 0, false, no, off (case-insensitive). Lists are comma-separated. An unparseable value logs a warning and leaves the previous value in place.

Core Configuration

TIF1_CACHE_DIR

Location for the SQLite cache database.
Type: str. Default: Windows %LOCALAPPDATA%/Temp/tif1; macOS ~/Library/Caches/tif1; Linux/other POSIX ~/.cache/tif1 when ~/.cache exists, otherwise ~/.tif1.

TIF1_ENABLE_CACHE

Enable or disable caching globally.
Type: bool. Default: true

TIF1_OFFLINE_MODE

Serve payloads from the cache only. A cache miss raises NetworkError instead of contacting a CDN. Offline mode also skips the live schedule download and the CDN preconnect.
Type: bool. Default: false

TIF1_CI_MODE

Bypass the persistent cache for reads and writes, so every fetch hits the CDN. CI mode turns off enable_cache for every session, so the laps and telemetry frame tiers are not used either.
Type: bool. Default: false

TIF1_LIB

Default DataFrame lib to use.
Type: str. Default: pandasOptions: pandas, polars

TIF1_POLARS_LAP_CATEGORICAL

Cast the Driver, Team, Compound, and TrackStatus columns of polars lap frames to Categorical. On pandas, these columns are always category.
Type: bool. Default: false

TIF1_PRELOAD_IMPORTS

Start a background thread at import tif1 that imports numpy, pandas, and pyarrow. The thread never imports a tif1 submodule, so configuration set after import tif1 still applies. By default the thread starts only in an interactive interpreter: IPython, Jupyter, python -i, or a REPL. There, the import overlaps the time before the next cell runs. Set 1 to always start it, or 0 to never start it. tif1 reads this variable from the environment directly, not through .tif1rc.
Type: bool. Default: unset (start only in an interactive interpreter)

Network Configuration

TIF1_CDNS

Configure the CDN sources for data fetching with automatic fallback. The value is a comma-separated list, not JSON. Only https:// URLs are accepted; raw.githubusercontent.com is skipped.
Type: list[str]. Default: jsDelivr (primary), Hugging Face buckets (fallback), StaticDelivr (last resort)The system tries CDNs in order and automatically falls back on failures.
The cdn_use_minification config key has no environment variable. Set it in .tif1rc or with config.set("cdn_use_minification", True). It applies only to custom mirrors: tif1 never requests .min.json files from the three default CDNs.

TIF1_TIMEOUT

Timeout for HTTP requests in seconds.
Type: int. Default: 30 seconds

TIF1_MAX_RETRIES

Maximum number of tries for each payload fetch, including the first try. 0 and 1 both mean one try without a retry.
Type: int. Default: 3

TIF1_RETRY_BACKOFF_FACTOR

Backoff multiplier for exponential retry delays. Values below 1.0 are rejected on read.
Type: float. Default: 2.0

TIF1_RETRY_JITTER

Add random jitter to retry delays.
Type: bool. Default: true

TIF1_RETRY_JITTER_MAX

Maximum random jitter in seconds that the async fetch path (laps and telemetry) adds to a retry delay. 0.0 adds no jitter on that path.
Type: float. Default: 0.0

TIF1_MAX_RETRY_DELAY

Upper bound in seconds for a single retry delay on the async fetch path (laps and telemetry).
Type: float. Default: 60.0

TIF1_MAX_WORKERS

Lower bound for the size of the shared worker thread pool. The pool size is the largest of max_workers, max_concurrent_requests, and telemetry_prefetch_max_concurrent_requests.
Type: int. Default: 20

TIF1_MAX_CONCURRENT_REQUESTS

Maximum number of in-flight HTTP requests in the async fetch pipeline.
Type: int. Default: 22

TIF1_TELEMETRY_PREFETCH_MAX_CONCURRENT_REQUESTS

Maximum in-flight requests while prefetching telemetry.
Type: int. Default: 32

TIF1_LOAD_TELEMETRY_LAZY

When true, session.load(telemetry=True) does not fetch telemetry. The first access of a lap of a driver fetches all the laps of that driver.
Type: bool. Default: false

TIF1_LAZY_TELEMETRY_LOOKAHEAD

The number of drivers that a cold lazy load fetches in the background. This starts when the code reads the drivers in the order of the laps table. -1 fetches all the drivers that are not loaded. 0 turns the background fetch off.
Type: int. Default: 1

TIF1_LAZY_TELEMETRY_BACKGROUND_REQUESTS

Maximum in-flight background requests of a cold lazy load.
Type: int. Default: 22

Circuit Breaker

TIF1_CIRCUIT_BREAKER_THRESHOLD

Number of consecutive failures before opening the circuit.
Type: int. Default: 5

TIF1_CIRCUIT_BREAKER_TIMEOUT

Time in seconds before tif1 tries to close an open circuit.
Type: int. Default: 60 seconds

HTTP Session

TIF1_HTTP_MULTIPLEXED

Enable HTTP/2 multiplexing for multiple requests over one connection.
Type: bool. Default: trueDisable this option only when a proxy or CDN causes connection problems.

TIF1_HTTP_DISABLE_HTTP3

Disable HTTP/3 (QUIC) support. HTTP/2 over TCP is the default. Set it to false to negotiate HTTP/3 again.
Type: bool. Default: true

TIF1_HTTP_REVOCATION_CHECK

Check whether the CDN’s TLS certificate has been revoked (OCSP) on the first connection of each process. The certificate chain and host name are verified either way. The first check of a certificate makes a request to the certificate authority before the first data request. tif1 keeps the GOOD answers in the cache (TIF1_HTTP_REVOCATION_CACHE), so later processes do not make that request again until the answer expires. Set to false to skip the check.
Type: bool. Default: true

TIF1_HTTP_REVOCATION_CACHE

Keep the GOOD answers of the revocation check in the SQLite cache and use them again in later processes. tif1 uses a kept answer again only for the same certificate. It uses it only until the expiry time in the answer (nextUpdate, usually hours to days). It never uses it for more than 7 days. tif1 does not keep a REVOKED or UNKNOWN answer, or an answer with a signature that it cannot verify. A process that uses a kept answer does not ask the certificate authority again. Thus it finds a revocation only after the kept answer expires. Set to false to check again in each process.
Type: bool. Default: true. Has no effect when TIF1_HTTP_REVOCATION_CHECK or the cache is off.
A user who can write to the cache directory can change the cached data, and the kept answers too. Make sure that only the user account that runs tif1 can write to the cache directory.

TIF1_CDN_PRECONNECT

Start the network work of a cold load in background threads during get_session(), when the session is not cached yet. get_session() starts the connections and the first requests (TIF1_CDN_FIRST_WAVE) before it imports pandas or polars, so the handshakes run while those libraries load. A cached session never imports the HTTP client or starts a thread. Set to false to keep get_session() free of network activity.
Type: bool. Default: true. Skipped automatically in offline and CI mode.

TIF1_CDN_FIRST_WAVE

Fetch the first files of a cold load with the Python standard library. When TIF1_CDN_PRECONNECT is on and the session is not cached yet, get_session() gets drivers.json and the session lap times over http.client while pandas or polars loads. The HTTP client (niquests) loads only when a telemetry request needs it. Until niquests has an open connection, single requests and the first telemetry requests also use the standard-library connections. niquests then loads and connects in a background thread. A response other than 200 with a JSON object goes through niquests, so the CDN fallback is the same. Set to false to send every request through niquests.
Type: bool. Default: true. Has no effect when TIF1_CDN_PRECONNECT is off.
The standard-library requests verify the certificate chain and the host name with the same root certificates as niquests. They do not do the revocation check (TIF1_HTTP_REVOCATION_CHECK). To do that check on each request, set TIF1_CDN_FIRST_WAVE=false.

TIF1_CDN_HEDGE

Re-issue a slow request on the next CDN source. Each source keeps a moving average of its request latency. A request on the first source waits two times that average, clamped to TIF1_CDN_HEDGE_MAX_DELAY. If it has not answered by then, the same request is sent to the next source too, and the first answer wins. A source that measures more than twice as slow as a lower-priority source moves behind it for the rest of the process. Set to false to try the sources one after the other.
Type: bool. Default: true. Only requests that stall send a second request; a healthy source sends one request per file.

TIF1_CDN_HEDGE_MAX_DELAY

Upper bound, in seconds, for the wait before a stalled request is re-issued on the next CDN source. The lower bound is 1 second. A source without latency samples uses this value.
Type: float. Default: 4.0.

TIF1_POOL_CONNECTIONS

Number of connection pools. The library clamps explicit values to a minimum of 10.
Type: int. Default: unset; the library computes max(256, max_workers, max_concurrent_requests, telemetry_prefetch_max_concurrent_requests).

TIF1_POOL_MAXSIZE

Maximum connections per pool. The library raises explicit values to at least max(512, pool_connections).
Type: int. Default: unset; the library computes max(512, pool_connections * 4).

TIF1_KEEPALIVE_TIMEOUT

Keep-alive timeout in seconds, sent in the Keep-Alive request header.
Type: int. Default: 120

TIF1_KEEPALIVE_MAX_REQUESTS

Maximum requests per keep-alive connection, sent in the Keep-Alive request header.
Type: int. Default: 10000

TIF1_HTTP_RESOLVERS

DNS resolver chain, tried in order. Comma-separated.
Type: list[str]. Default: standard,doh+cloudflare://,doh+google://

TIF1_CONNECTION_STATS_LOG_INTERVAL

Interval in seconds between connection pool statistics log lines.
Type: float. Default: 60.0

TIF1_POOL_EXHAUSTION_BACKOFF_BASE

Base delay in seconds when the connection pool is exhausted.
Type: float. Default: 0.01

TIF1_POOL_EXHAUSTION_BACKOFF_MAX

Maximum pool-exhaustion backoff delay in seconds.
Type: float. Default: 0.5

TIF1_POOL_EXHAUSTION_BACKOFF_JITTER

Jitter added to the pool-exhaustion backoff, in seconds.
Type: float. Default: 0.01

Cache Tuning

TIF1_MEMORY_CACHE_MAX_ITEMS

Size of the in-memory JSON blob LRU (number of items).
Type: int. Default: 1024

TIF1_MEMORY_TELEMETRY_CACHE_MAX_ITEMS

Size of the in-memory telemetry blob LRU (number of items).
Type: int. Default: 2048

TIF1_CACHE_COMMIT_INTERVAL

Number of cache writes between SQLite commits.
Type: int. Default: 100

TIF1_SQLITE_TIMEOUT

SQLite busy timeout in seconds.
Type: float. Default: 30.0

TIF1_MISSING_PAYLOADS_TTL_DAYS

Lifetime in days of an all-CDN-missing verdict. Within the window, tif1 skips the CDN probe for that payload.
Type: float. Default: 7.0

TIF1_SCHEDULE_TTL_HOURS

Age in hours after which the event schedule of the current (or a future) season is re-fetched from the theOehrly/f1schedule repository. Past seasons come from the vendored files and never refresh.
Type: float. Default: 6.0. 0 re-fetches on every lookup.

Ergast Data

The Ergast tier (tif1.ergast and the classification merged into Session.results) reads the TracingInsights Stats repository first. The Jolpica API answers only what that repository cannot. Refer to Ergast.

TIF1_ERGAST_RESULTS

Merge the official Ergast classification into session.results and order session.drivers by it. Off, sessions keep the lap-derived classification and fetch nothing extra.
Type: bool. Default: true

TIF1_ERGAST_FALLBACK

Ask the Jolpica API for what the Stats repository cannot answer. Off, those queries raise ErgastInvalidRequestError or DataNotFoundError.
Type: bool. Default: true

TIF1_JOLPICA_BASE_URL

Base URL of the Jolpica API; a self-hosted instance works.
Type: str. Default: https://api.jolpi.ca/ergast/f1

TIF1_ERGAST_TTL_HOURS

Lifetime in hours of current-season Stats files and of every Jolpica answer in the cache. Past-season Stats files never expire.
Type: float. Default: 6.0

TIF1_ERGAST_TIMEOUT

Jolpica request timeout in seconds.
Type: float. Default: 5.0

TIF1_ERGAST_RATE_LIMIT_BURST

Jolpica requests per second the client allows itself.
Type: int. Default: 4

TIF1_ERGAST_RATE_LIMIT_HOURLY

Jolpica requests per hour the client allows itself.
Type: int. Default: 200

TIF1_STATS_REPO

GitHub repository (owner/repo) holding the Ergast Stats files, served through the configured CDNs.
Type: str. Default: TracingInsights-Archive/Stats

TIF1_STATS_BRANCH

Branch of the Stats repository.
Type: str. Default: main

Data Loading and Validation

TIF1_ULTRA_COLD_START

Enable the low-latency path for first-time loads. For a session that is not in the cache, tif1 skips cache reads and payload validation. A cached session always loads from the cache.
Type: bool. Default: true

TIF1_ULTRA_COLD_BACKGROUND_CACHE_FILL

Fill the cache in a background thread during an ultra cold start.
Type: bool. Default: false

TIF1_ULTRA_COLD_SKIP_RETRIES

Skip retries during an ultra cold start.
Type: bool. Default: true

TIF1_PREFETCH_DRIVER_LAPS_ON_GET_DRIVER

Prefetch a driver’s lap data when the driver is first accessed.
Type: bool. Default: true

TIF1_PREFETCH_ALL_TELEMETRY_ON_FIRST_LAP_REQUEST

Prefetch every telemetry payload on the first lap telemetry request.
Type: bool. Default: false

TIF1_PREFETCH_ALL_TELEMETRY_AFTER_LAPS_LOAD

Prefetch every telemetry payload in a background thread as soon as laps are loaded. This setting takes effect only when TIF1_PREFETCH_ALL_TELEMETRY_ON_FIRST_LAP_REQUEST is also true.
Type: bool. Default: false

TIF1_VALIDATE_DATA

Enable Pydantic validation of the weather.json and rcm.json payloads.
Type: bool. Default: false

TIF1_VALIDATE_LAP_TIMES

Enable validation of the laptimes.json and session_laptimes.json payloads.
Type: bool. Default: false

TIF1_VALIDATE_TELEMETRY

Enable validation of the {lap}_tel.json telemetry payloads.
Type: bool. Default: false
The three validation settings apply only to payloads that tif1 downloads with TIF1_ULTRA_COLD_START=false. The ultra cold start path (the default) skips validation, and a cache hit is not validated again.

TIF1_JSON_PARSE_WORKERS

Number of worker processes for JSON parsing. 0 parses in-process.
Type: int. Default: 0Process-pool parsing adds IPC overhead on telemetry-heavy cold starts. Keep it at 0 unless a benchmark shows a gain.

Configuration File Control

TIF1_CONFIG_FILE

Explicit path to a .tif1rc JSON file. It is checked first in the lookup order.
Type: str. Default: unset

TIF1_TRUST_CWD_CONFIG

Allow tif1 to read .tif1rc from the current working directory.
Type: bool. Default: false
Set TIF1_TRUST_CWD_CONFIG=true only in trusted directories. A .tif1rc in an untrusted checkout could redirect the CDN list or the cache directory.

Configuration File

Instead of environment variables, create a .tif1rc file. The file is a JSON object keyed by configuration key. A configuration key is the environment variable name without the TIF1_ prefix, in lowercase. tif1 loads the first file found in this order:
  1. The path in TIF1_CONFIG_FILE, when set
  2. ./.tif1rc in the current working directory, only when TIF1_TRUST_CWD_CONFIG=true
  3. ~/.tif1rc in the home directory
A file whose root is not a JSON object is skipped with a warning.

Example .tif1rc

Programmatic Configuration

Configure tif1 directly in code as an alternative. The Config object exposes get(key, default=None), set(key, value), and save(path=None); there is no attribute API, and tif1 does not export the Config class.

Priority Order

Configuration is resolved in this order (highest to lowest priority):
  1. Programmatic config.set() calls
  2. Environment variables
  3. The first .tif1rc found: TIF1_CONFIG_FILE, then ./.tif1rc (only with TIF1_TRUST_CWD_CONFIG=true), then ~/.tif1rc
  4. Default values

Validation

tif1 raises no configuration exception at startup. A value that fails type conversion logs a warning and keeps the previous value. Range checks run on read: config.get() logs a warning and returns the supplied default for an invalid value.

Best Practices

Use .tif1rc for Projects

Commit a project .tif1rc and point TIF1_CONFIG_FILE at it. tif1 reads ./.tif1rc only with TIF1_TRUST_CWD_CONFIG=true.

Use ENV for Deployment

Use environment variables in production for flexibility.

Keep Defaults

Override only the values that must change.

Document Changes

Record each changed default value outside the file. .tif1rc is strict JSON and accepts no comments.
Last modified on November 3, 2026