> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixeltable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete guide to configuring Pixeltable

## 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`:

```toml theme={null}
[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

[label_studio]
url = 'http://localhost:8080/'
api_key = 'my-label-studio-api-key'
```

## 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]<br />file\_cache\_size\_g | (float) Maximum size of the Pixeltable file cache, in GiB; required                                                                         |
| PIXELTABLE\_TIME\_ZONE           | \[pixeltable]<br />time\_zone           | (string) Default time zone in [IANA format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones); defaults to the system time zone |
| PIXELTABLE\_HIDE\_WARNINGS       | \[pixeltable]<br />hide\_warnings       | (bool) Suppress warnings generated by various libraries used by Pixeltable; default is false                                                |
| PIXELTABLE\_VERBOSITY            | \[pixeltable]<br />verbosity            | (int) Verbosity for Pixeltable console logging (0: minimum, 1: normal, 2: maximum); default is 1                                            |
| PIXELTABLE\_START\_DASHBOARD     | \[pixeltable]<br />start\_dashboard     | (bool) Whether to automatically start the Pixeltable Dashboard server; default is true                                                      |
| PIXELTABLE\_DASHBOARD\_PORT      | \[pixeltable]<br />dashboard\_port      | (int) Port number for the Pixeltable Dashboard server; default is 22089                                                                     |
| PIXELTABLE\_API\_KEY             | \[pixeltable]<br />api\_key             | (string) API key for Pixeltable Cloud                                                                                                       |
| PIXELTABLE\_INPUT\_MEDIA\_DEST   | \[pixeltable]<br />input\_media\_dest   | (string) Default destination URI for media files that are inserted into tables                                                              |
| PIXELTABLE\_OUTPUT\_MEDIA\_DEST  | \[pixeltable]<br />output\_media\_dest  | (string) Default destination URI for media files that are generated by Pixeltable operations                                                |
| PIXELTABLE\_R2\_PROFILE          | \[pixeltable]<br />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]<br />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]<br />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]<br />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]<br />api\_key           | (string) API key to use for Anthropic services                                    |
| AZURE\_STORAGE\_ACCOUNT\_NAME | \[azure]<br />storage\_account\_name | (string) Azure Storage account name for use with Azure Blob Storage               |
| AZURE\_STORAGE\_ACCOUNT\_KEY  | \[azure]<br />storage\_account\_key  | (string) Azure Storage account key for use with Azure Blob Storage                |
| BEDROCK\_API\_KEY             | \[bedrock]<br />api\_key             | (string) API key to use for AWS Bedrock services                                  |
| DEEPSEEK\_API\_KEY            | \[deepseek]<br />api\_key            | (string) API key to use for Deepseek services                                     |
| FAL\_API\_KEY                 | \[fal]<br />api\_key                 | (string) API key to use for fal.ai services                                       |
| FIREWORKS\_API\_KEY           | \[fireworks]<br />api\_key           | (string) API key to use for Fireworks AI services                                 |
| GEMINI\_API\_KEY              | \[gemini]<br />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]<br />api\_key                | (string) API key to use for Groq AI services                                      |
| HF\_AUTH\_TOKEN               | \[hf]<br />auth\_token               | (string) Hugging Face auth token for use with Hugging Face services               |
| LABEL\_STUDIO\_API\_KEY       | \[label\_studio]<br />api\_key       | (string) API key to use for Label Studio                                          |
| LABEL\_STUDIO\_URL            | \[label\_studio]<br />url            | (string) URL of the Label Studio server to use                                    |
| MISTRAL\_API\_KEY             | \[mistral]<br />api\_key             | (string) API key to use for Mistral AI services                                   |
| OPENAI\_API\_KEY              | \[openai]<br />api\_key              | (string) API key to use for OpenAI services                                       |
| OPENAI\_BASE\_URL             | \[openai]<br />base\_url             | (string, optional) Base URL to use for OpenAI services                            |
| OPENAI\_API\_VERSION          | \[openai]<br />api\_version          | (string) API version for use with Azure OpenAI; must be `'latest'` or `'preview'` |
| OPENROUTER\_API\_KEY          | \[openrouter]<br />api\_key          | (string) API key to use for OpenRouter services                                   |
| OPENROUTER\_SITE\_URL         | \[openrouter]<br />site\_url         | (string) Application URL (optional, for OpenRouter analytics)                     |
| OPENROUTER\_APP\_NAME         | \[openrouter]<br />app\_name         | (string) Application name (optional, for OpenRouter analytics)                    |
| REPLICATE\_API\_TOKEN         | \[replicate]<br />api\_token         | (string) API token to use for Replicate services                                  |
| REVE\_API\_KEY                | \[reve]<br />api\_key                | (string) API key to use for Reve Image services                                   |
| TOGETHER\_API\_KEY            | \[together]<br />api\_key            | (string) API key to use for Together AI services                                  |
| TWELVELABS\_API\_KEY          | \[twelvelabs]<br />api\_key          | (string) API key to use for TwelveLabs services                                   |
| VOYAGE\_API\_KEY              | \[voyage]<br />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](/sdk/latest) 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:

```toml theme={null}
[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:

```toml theme={null}
[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-pro = 600
gemini-pro-vision = 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.

<Card title="Installation Guide" icon="computer" href="/overview/quick-start">
  Return to the installation guide for setup instructions
</Card>