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)

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_FILE_CACHE_SIZE_G	[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
PIXELTABLE_START_DASHBOARD	[pixeltable] start_dashboard	(bool) Whether to automatically start the Pixeltable Dashboard server; default is true
PIXELTABLE_DASHBOARD_PORT	[pixeltable] dashboard_port	(int) Port number for the Pixeltable Dashboard server; default is 22089
PIXELTABLE_API_KEY	[pixeltable] api_key	(string) API key for Pixeltable Cloud
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
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.

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
REVE_API_KEY	[reve] api_key	(string) API key to use for Reve Image 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

Welcome to Pixeltable

Tools

Core Concepts

How-To

Configuration options

System 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

​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

API configuration

Rate limit configuration

Single rate limit per provider

Per-model rate limits

Configuration best practices

Security considerations

Performance tuning

Applying configuration changes