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: trueTIF1_OFFLINE_MODE
Serve payloads from the cache only. A cache miss raisesNetworkError instead of contacting a CDN. Offline mode also skips the live schedule download and the CDN preconnect.
Type:
bool. Default: falseTIF1_CI_MODE
Bypass the persistent cache for reads and writes, so every fetch hits the CDN. CI mode turns offenable_cache for every session, so the laps and telemetry frame tiers are not used either.
Type:
bool. Default: falseTIF1_LIB
Default DataFrame lib to use.Type:
str. Default: pandasOptions: pandas, polarsTIF1_POLARS_LAP_CATEGORICAL
Cast theDriver, Team, Compound, and TrackStatus columns of polars lap frames to Categorical. On pandas, these columns are always category.
Type:
bool. Default: falseTIF1_PRELOAD_IMPORTS
Start a background thread atimport 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. Onlyhttps:// 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 secondsTIF1_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: 3TIF1_RETRY_BACKOFF_FACTOR
Backoff multiplier for exponential retry delays. Values below1.0 are rejected on read.
Type:
float. Default: 2.0TIF1_RETRY_JITTER
Add random jitter to retry delays.Type:
bool. Default: trueTIF1_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.0TIF1_MAX_RETRY_DELAY
Upper bound in seconds for a single retry delay on the async fetch path (laps and telemetry).Type:
float. Default: 60.0TIF1_MAX_WORKERS
Lower bound for the size of the shared worker thread pool. The pool size is the largest ofmax_workers, max_concurrent_requests, and telemetry_prefetch_max_concurrent_requests.
Type:
int. Default: 20TIF1_MAX_CONCURRENT_REQUESTS
Maximum number of in-flight HTTP requests in the async fetch pipeline.Type:
int. Default: 22TIF1_TELEMETRY_PREFETCH_MAX_CONCURRENT_REQUESTS
Maximum in-flight requests while prefetching telemetry.Type:
int. Default: 32TIF1_LOAD_TELEMETRY_LAZY
Whentrue, 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: falseTIF1_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: 1TIF1_LAZY_TELEMETRY_BACKGROUND_REQUESTS
Maximum in-flight background requests of a cold lazy load.Type:
int. Default: 22Circuit Breaker
TIF1_CIRCUIT_BREAKER_THRESHOLD
Number of consecutive failures before opening the circuit.Type:
int. Default: 5TIF1_CIRCUIT_BREAKER_TIMEOUT
Time in seconds before tif1 tries to close an open circuit.Type:
int. Default: 60 secondsHTTP 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 tofalse to negotiate HTTP/3 again.
Type:
bool. Default: trueTIF1_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: trueTIF1_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.TIF1_CDN_PRECONNECT
Start the network work of a cold load in background threads duringget_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. WhenTIF1_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.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 toTIF1_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 of10.
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 leastmax(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 theKeep-Alive request header.
Type:
int. Default: 120TIF1_KEEPALIVE_MAX_REQUESTS
Maximum requests per keep-alive connection, sent in theKeep-Alive request header.
Type:
int. Default: 10000TIF1_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.0TIF1_POOL_EXHAUSTION_BACKOFF_BASE
Base delay in seconds when the connection pool is exhausted.Type:
float. Default: 0.01TIF1_POOL_EXHAUSTION_BACKOFF_MAX
Maximum pool-exhaustion backoff delay in seconds.Type:
float. Default: 0.5TIF1_POOL_EXHAUSTION_BACKOFF_JITTER
Jitter added to the pool-exhaustion backoff, in seconds.Type:
float. Default: 0.01Cache Tuning
TIF1_MEMORY_CACHE_MAX_ITEMS
Size of the in-memory JSON blob LRU (number of items).Type:
int. Default: 1024TIF1_MEMORY_TELEMETRY_CACHE_MAX_ITEMS
Size of the in-memory telemetry blob LRU (number of items).Type:
int. Default: 2048TIF1_CACHE_COMMIT_INTERVAL
Number of cache writes between SQLite commits.Type:
int. Default: 100TIF1_SQLITE_TIMEOUT
SQLite busy timeout in seconds.Type:
float. Default: 30.0TIF1_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.0TIF1_SCHEDULE_TTL_HOURS
Age in hours after which the event schedule of the current (or a future) season is re-fetched from thetheOehrly/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 intosession.results and order session.drivers by it. Off, sessions keep the lap-derived classification and fetch nothing extra.
Type:
bool. Default: trueTIF1_ERGAST_FALLBACK
Ask the Jolpica API for what the Stats repository cannot answer. Off, those queries raiseErgastInvalidRequestError or DataNotFoundError.
Type:
bool. Default: trueTIF1_JOLPICA_BASE_URL
Base URL of the Jolpica API; a self-hosted instance works.Type:
str. Default: https://api.jolpi.ca/ergast/f1TIF1_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.0TIF1_ERGAST_TIMEOUT
Jolpica request timeout in seconds.Type:
float. Default: 5.0TIF1_ERGAST_RATE_LIMIT_BURST
Jolpica requests per second the client allows itself.Type:
int. Default: 4TIF1_ERGAST_RATE_LIMIT_HOURLY
Jolpica requests per hour the client allows itself.Type:
int. Default: 200TIF1_STATS_REPO
GitHub repository (owner/repo) holding the Ergast Stats files, served through the configured CDNs.
Type:
str. Default: TracingInsights-Archive/StatsTIF1_STATS_BRANCH
Branch of the Stats repository.Type:
str. Default: mainData 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: trueTIF1_ULTRA_COLD_BACKGROUND_CACHE_FILL
Fill the cache in a background thread during an ultra cold start.Type:
bool. Default: falseTIF1_ULTRA_COLD_SKIP_RETRIES
Skip retries during an ultra cold start.Type:
bool. Default: trueTIF1_PREFETCH_DRIVER_LAPS_ON_GET_DRIVER
Prefetch a driver’s lap data when the driver is first accessed.Type:
bool. Default: trueTIF1_PREFETCH_ALL_TELEMETRY_ON_FIRST_LAP_REQUEST
Prefetch every telemetry payload on the first lap telemetry request.Type:
bool. Default: falseTIF1_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 whenTIF1_PREFETCH_ALL_TELEMETRY_ON_FIRST_LAP_REQUEST is also true.
Type:
bool. Default: falseTIF1_VALIDATE_DATA
Enable Pydantic validation of theweather.json and rcm.json payloads.
Type:
bool. Default: falseTIF1_VALIDATE_LAP_TIMES
Enable validation of thelaptimes.json and session_laptimes.json payloads.
Type:
bool. Default: falseTIF1_VALIDATE_TELEMETRY
Enable validation of the{lap}_tel.json telemetry payloads.
Type:
bool. Default: falseThe 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: unsetTIF1_TRUST_CWD_CONFIG
Allow tif1 to read.tif1rc from the current working directory.
Type:
bool. Default: falseConfiguration 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:
- The path in
TIF1_CONFIG_FILE, when set ./.tif1rcin the current working directory, only whenTIF1_TRUST_CWD_CONFIG=true~/.tif1rcin the home directory
Example .tif1rc
Programmatic Configuration
Configure tif1 directly in code as an alternative. TheConfig 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):- Programmatic
config.set()calls - Environment variables
- The first
.tif1rcfound:TIF1_CONFIG_FILE, then./.tif1rc(only withTIF1_TRUST_CWD_CONFIG=true), then~/.tif1rc - 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.