Configuration

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:

[pixeltable]
file_cache_size_g = 250
time_zone = "America/Los_Angeles"
hide_warnings = true
verbosity = 2

[openai]
api_key = 'my-openai-api-key'

[openai.rate_limits]
tts-1 = 500  # OpenAI uses a per-model rate limit configuration (see below for details)

[mistral]
api_key = 'my-mistral-api-key'
rate_limit = 600  # Mistral uses a single rate limit for all models

System settings

Environment Variable	Config File	Meaning
PIXELTABLE_HOME		(string) Pixeltable user directory; default is ~/.pixeltable
PIXELTABLE_CONFIG		(string) Pixeltable config file; default is $PIXELTABLE_HOME/config.toml
PIXELTABLE_PGDATA		(string) Directory where Pixeltable DB is stored; default is $PIXELTABLE_HOME/pgdata
PIXELTABLE_DB		(string) Pixeltable database name; default is pixeltable
PIXELTABLE_DB_POOL_SIZE	[pixeltable] db_pool_size	(int) Number of database connections this process keeps open; default is 5
PIXELTABLE_DB_POOL_MAX_OVERFLOW	[pixeltable] db_pool_max_overflow	(int) Number of temporary database connections this process may open beyond `db_pool_size`; default is 10
	[pixeltable] file_cache_size_g	(float) Maximum size of the Pixeltable file cache, in GiB; required
PIXELTABLE_TIME_ZONE	[pixeltable] time_zone	(string) Default time zone in IANA format; defaults to the system time zone
PIXELTABLE_HIDE_WARNINGS	[pixeltable] hide_warnings	(bool) Suppress warnings generated by various libraries used by Pixeltable; default is false
PIXELTABLE_VERBOSITY	[pixeltable] verbosity	(int) Verbosity for Pixeltable console logging (0: minimum, 1: normal, 2: maximum); default is 1
PXT_PORT		(int) Port the background process listens on; default is 22089. See Dashboard
PIXELTABLE_API_KEY	[pixeltable] api_key	(string) API key for Pixeltable Cloud, created under API Keys. The environment variable wins over the config file, and either one outranks a `pxt login` session. To use Cloud without a key, run `pxt login` (Signing in).
PIXELTABLE_INPUT_MEDIA_DEST	[pixeltable] input_media_dest	(string) Default destination URI for media files that are inserted into tables
PIXELTABLE_OUTPUT_MEDIA_DEST	[pixeltable] output_media_dest	(string) Default destination URI for media files that are generated by Pixeltable operations
OTEL_EXPORTER_OTLP_ENDPOINT	[otel] exporter_otlp_endpoint	(string) OTLP endpoint for traces. Requires `pip install 'pixeltable[otel]'`. See Observability
OTEL_EXPORTER_OTLP_PROTOCOL	[otel] exporter_otlp_protocol	(string) OTLP transport: `http/protobuf` (default) or `grpc`
OTEL_EXPORTER_OTLP_HEADERS	[otel] exporter_otlp_headers	(string) OTLP auth headers, e.g. `Authorization=Basic <token>`. On a hosted database, set it with `pxt secret set`
PIXELTABLE_R2_PROFILE	[pixeltable] r2_profile	(string) Name of AWS config profile to use when accessing Cloudflare R2 resources. If not specified, default AWS credentials will be used.
PIXELTABLE_S3_PROFILE	[pixeltable] s3_profile	(string) Name of AWS config profile to use when accessing Amazon S3 resources. If not specified, default AWS credentials will be used.
PIXELTABLE_B2_PROFILE	[pixeltable] b2_profile	(string) Name of an S3-compatible profile for accessing Backblaze B2. Defaults to the standard AWS credential chain if not set.
PIXELTABLE_TIGRIS_PROFILE	[pixeltable] tigris_profile	(string) Name of an S3-compatible profile for accessing Tigris. Defaults to the standard AWS credential chain if not set.

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; its pods pick up the config when doing a pxt db update, and a running service moves onto it with pxt service update.

# pixeltable.toml
[[pixeltable.database]]
db_input_media_dest = 's3://bucket/input/'
db_output_media_dest = 's3://bucket/output/'
db_exporter_otlp_endpoint = 'https://otlp.example.com'
db_exporter_otlp_protocol = 'grpc'

[[pixeltable.database]]
name = 'pxt://myorg:mydb'
db_input_media_dest = 's3://bucket/prod/input/'
db_output_media_dest = 's3://bucket/prod/output/'
db_exporter_otlp_endpoint = 'https://otlp.example.com'

Settings are resolved in this order:

Database entry: db_<key> in [[pixeltable.database]]
Environment variable: the variable from the table above, or a pxt.init() override
Global config: <key> under [pixeltable] / [otel] in config.toml, shared by every database on the installation
Fallback: a hosted database uses its home bucket for media

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).

API configuration

Environment Variable	Config File	Meaning
ANTHROPIC_API_KEY	[anthropic] api_key	(string) API key to use for Anthropic services
AZURE_STORAGE_ACCOUNT_NAME	[azure] storage_account_name	(string) Azure Storage account name for use with Azure Blob Storage
AZURE_STORAGE_ACCOUNT_KEY	[azure] storage_account_key	(string) Azure Storage account key for use with Azure Blob Storage
BEDROCK_API_KEY	[bedrock] api_key	(string) API key to use for AWS Bedrock services
DEEPSEEK_API_KEY	[deepseek] api_key	(string) API key to use for Deepseek services
FAL_API_KEY	[fal] api_key	(string) API key to use for fal.ai services
FIREWORKS_API_KEY	[fireworks] api_key	(string) API key to use for Fireworks AI services
GEMINI_API_KEY	[gemini] api_key	(string) API key for Google AI Studio (not used for Vertex AI)
GOOGLE_API_KEY		(string) Alternative API key for Google AI Studio (not used for Vertex AI)
GOOGLE_CLOUD_LOCATION		(string) Google Cloud region for Vertex AI
GOOGLE_CLOUD_PROJECT		(string) Google Cloud project ID for Vertex AI
GOOGLE_GENAI_USE_VERTEXAI		(bool) Set to `true` to use Vertex AI instead of Google AI Studio
GROQ_API_KEY	[groq] api_key	(string) API key to use for Groq AI services
HF_TOKEN	[hf] token	(string) Hugging Face token for use with Hugging Face services
MISTRAL_API_KEY	[mistral] api_key	(string) API key to use for Mistral AI services
OPENAI_API_KEY	[openai] api_key	(string) API key to use for OpenAI services
OPENAI_BASE_URL	[openai] base_url	(string, optional) Base URL to use for OpenAI services
OPENAI_API_VERSION	[openai] api_version	(string) API version for use with Azure OpenAI; must be `'latest'` or `'preview'`
OPENROUTER_API_KEY	[openrouter] api_key	(string) API key to use for OpenRouter services
OPENROUTER_SITE_URL	[openrouter] site_url	(string) Application URL (optional, for OpenRouter analytics)
OPENROUTER_APP_NAME	[openrouter] app_name	(string) Application name (optional, for OpenRouter analytics)
REPLICATE_API_TOKEN	[replicate] api_token	(string) API token to use for Replicate services
TOGETHER_API_KEY	[together] api_key	(string) API key to use for Together AI services
TWELVELABS_API_KEY	[twelvelabs] api_key	(string) API key to use for TwelveLabs services
VOYAGE_API_KEY	[voyage] api_key	(string) API key to use for Voyage AI services

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:

[mistral]
api_key = 'my-mistral-api-key'
rate_limit = 600  # requests per minute

[fireworks]
api_key = 'my-fireworks-api-key'
rate_limit = 300

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:

[openai]
api_key = 'my-openai-api-key'

[openai.rate_limits]
gpt-4o = 500
gpt-4o-mini = 1000
tts-1 = 50
dall-e-3 = 10

[gemini.rate_limits]
gemini-2.5-flash = 600
gemini-2.5-pro = 300

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

Getting started

Tools

How to

Resources

Configuration options

System settings

Per-database settings

API configuration

Rate limit configuration

Single rate limit per provider

Per-model rate limits

Configuration best practices

Security considerations

Performance tuning

Applying configuration changes

Installation Guide

​Configuration options

​System settings

​Per-database settings

​API configuration

​Rate limit configuration

​Single rate limit per provider

​Per-model rate limits

​Configuration best practices

​Security considerations

​Performance tuning

​Applying configuration changes

Installation Guide

Configuration options

System settings

Per-database settings

API configuration

Rate limit configuration

Single rate limit per provider

Per-model rate limits

Configuration best practices

Security considerations

Performance tuning

Applying configuration changes