Skip to main content

Configuration options

Pixeltable can be configured through:
  • Environment variables
  • System configuration file (~/.pixeltable/config.toml on Linux/macOS or C:\Users\<username>\.pixeltable\config.toml on Windows)
  • pxt.init(), for the calling process only: pxt.init({'openai.api_key': '...'})
The settings governing the file cache that the whole instance shares are read from the config file only: file_cache_size_g and file_cache_lease_s.
Prefer environment variable names (PIXELTABLE_API_KEY, PIXELTABLE_OUTPUT_MEDIA_DEST). Pixeltable resolves environment variables from the process environment and never loads a .env file itself, so source one yourself first (set -a; source .env; set +a) or load it with a dotenv library. Provider keys go under Secrets or pxt secret. On a hosted Cloud database the home bucket is already the default media store; dest env vars are for local Pixeltable and bring-your-own buckets. See Cloud storage.
Example config.toml:

System settings

Per-database settings

Media destinations and the OTLP endpoint and protocol can also be set for a single database. Each database has a [[pixeltable.database]] entry in pixeltable.toml. Add a db_<key> field to that entry to set <key> for that database only. A [[pixeltable.database]] entry with no name corresponds to the local database. A [[pixeltable.database]] entry named pxt://org:db is a hosted database, and must be in pixeltable.toml, not config.toml. Its pods read the entry and the sections of pixeltable.toml after pxt db update, and pxt service update restarts running services with them. For a hosted database, pxt db update refuses a secret in pixeltable.toml (a key named api_key, api_secret, api_token, token, storage_account_key, or exporter_otlp_headers); set it with pxt secret set pxt://org:db OPENAI_API_KEY=... instead.
Settings are resolved in this order:
  1. Database entry: db_<key> in [[pixeltable.database]]
  2. Environment variable: the variable from the table above, or a pxt.init() override
  3. Global config: <key> under [pixeltable] / [otel] in config.toml, shared by every database on the installation
  4. Fallback: a hosted database uses its home bucket for media
Pixeltable on the pods of a hosted database skips the entry’s db_exporter_otlp_endpoint and db_exporter_otlp_protocol. It sends its telemetry to the collector in the pod, at the address in the pod’s environment. The OTLP auth headers are a secret and do not go in the entry: set OTEL_EXPORTER_OTLP_HEADERS in the environment, and on a hosted database with pxt secret set pxt://org:db OTEL_EXPORTER_OTLP_HEADERS=... (see pxt secret).

Telemetry from a hosted database

Each pod of a hosted database runs an OpenTelemetry Collector. Pixeltable in the pod sends its traces, metrics, and logs to that collector, and the collector sends them to your OTLP backends. The first backend takes its endpoint and protocol from the database’s entry (db_exporter_otlp_endpoint, db_exporter_otlp_protocol), or else from the secrets OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_PROTOCOL. Its headers come from the secret OTEL_EXPORTER_OTLP_HEADERS. Secrets whose names start with OTEL_EXPORTER_OTLP_ or OTEL_TRACES_SAMPLER_ARG go only to the collector, so that Pixeltable in the pod keeps sending its telemetry to the collector. Each further backend is a set of secrets whose names end in __<NAME>:
The collector sends every trace that contains an error or takes longer than one second, and 10% of the other traces. Set OTEL_TRACES_SAMPLER_ARG to a ratio between 0 and 1 to change that share, or OTEL_TRACES_SAMPLER_ARG__<NAME> for one backend. Logs and metrics are sent in full. The collector also sends traces to CloudWatch, sampled the same way. OTEL_TRACES_SAMPLER_ARG__CLOUDWATCH sets the share of the other traces that CloudWatch keeps. Without it, OTEL_TRACES_SAMPLER_ARG sets that share, and the default is 10%. You cannot name a backend CLOUDWATCH. Read the spans with pxt db spans and pxt service spans. The pods read these settings at startup. The endpoint and protocol in the entry reach the pods with the project files, so after you change them, run pxt db update and then pxt service update. After you change a secret, run pxt db restart and pxt service restart.

API configuration

Rate limit configuration

Pixeltable supports two patterns for configuring API rate limits in config.toml. Refer to the docstring of the relevant udf in the SDK Reference for details on the rate limiting pattern used by that udf.

Single rate limit per provider

For providers with a single rate limit across all models, add a rate_limit key to the provider’s config section:

Per-model rate limits

For providers that support different rate limits for different models, add a <provider>.rate_limits section and list the rate limits for each model:
Quote a model id that contains . or :. Otherwise TOML reads . as a nested key, and : is a syntax error. If no rate limit is configured, Pixeltable uses a default of 600 requests per minute.

Configuration best practices

Security considerations

When configuring API keys and sensitive information:
  • Avoid hardcoding API keys in your code
  • Use environment variables for temporary access
  • Use the config file for persistent configuration
  • Ensure your config.toml file has appropriate permissions (readable only by you)

Performance tuning

  • Adjust file_cache_size_g based on your available system memory
  • For large datasets, increase the cache size to improve performance
  • Set appropriate verbosity level based on your debugging needs

Applying configuration changes

Configuration changes take effect when you restart your Python session.

Installation Guide

Return to the installation guide for setup instructions
Last modified on November 7, 2026