---
title: "Environment variables"
source: PostHog Documentation
source_url: https://github.com/PostHog/posthog.com
licence: MIT
domain: data-and-analysis
subdomain: posthog-docs
date_added: 2026-04-25
---

import Sunset from "../\_snippets/sunset-disclaimer.mdx"

<Sunset />

As of [PostHog 1.33.0](/blog/the-posthog-array-1-33-0) some settings can now be managed directly in the app, without having to connect to your cluster and/or redeploy. If you are on version 1.33.0 or newer, please review [Instance settings](/docs/self-host/configure/instance-settings) first.

For settings that can be managed with Instance Settings, you can either set the values via environment variables or through the Instance Settings page in your instance. However, it is strongly **recommended to use Instance settings.** Environment variables are only loaded when there are no values in Instance settings, which means that environment variables could reflect outdated values.

For other settings, there are various environment variables you can set to configure your instance. Below is a comprehensive list of all of them. However, for general use, you most likely do not have to worry about the vast majority of these.

Rows with a missing 'Default Value' usually default to an empty string. This is different from `None`.

Some variables here are default Django variables. This [Django Docs page](https://docs.djangoproject.com/en/3.2/ref/settings/) has more information about them.

| Variable                                                                                                 | Description                                                                                                                                                                                                                                         | Default Value                                                                                                 |
| :------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| `SECRET_KEY`                                                                                             | **❗️ Always required.** [Used by Django for cryptography](https://docs.djangoproject.com/en/2.2/ref/settings/#secret-key). Helps secure cookies, sessions, hashes, etc. Custom value required in production.                                        | `<randomly generated secret key>`                                                                             |
| `SITE_URL` - should be an absolute URL and include the protocol (e.g. `https://posthog.your-domain.com`) | **❗️ Always required.** Principal/canonical URL of your PostHog instance. Needed for emails, webhooks and SSO to work properly. We currently do not support subpaths in this URL.                                                                   | `http://localhost:8000`                                                                                       |
| `SECURE_COOKIES`                                                                                         | Determines if Django should use [secure cookies](https://docs.djangoproject.com/en/2.2/ref/settings/#session-cookie-secure). Insecure cookies do not work without HTTPS.                                                                            | `False` if PostHog is running in DEBUG or TEST mode, else `True`                                              |
| `IS_BEHIND_PROXY`                                                                                        | Specifies if PostHog is running behind a proxy like Apache, NGINX or ELB. Be sure to properly set [trusted proxies](/docs/self-host/configure/running-behind-proxy#trusted-proxies).                                                                | `False`                                                                                                       |
| `ALLOWED_IP_BLOCKS`                                                                                      | Specifies IP blocks allowed to connect to the PostHog instance for management (events will still be allowed from anywhere). Make sure to properly [configure your proxy](/docs/self-host/configure/running-behind-proxy) if running behind a proxy. | _Empty_                                                                                                       |
| `TRUSTED_PROXIES`                                                                                        | Specifies the IPs of proxies that can be trusted.                                                                                                                                                                                                   | `None`                                                                                                        |
| `TRUST_ALL_PROXIES`                                                                                      | Determines if all proxies can be trusted.                                                                                                                                                                                                           | `False`                                                                                                       |
| `ALLOWED_HOSTS`                                                                                          | A list of strings representing the host/domain names that Django can serve. [More info](https://docs.djangoproject.com/en/3.1/ref/settings/#allowed-hosts).                                                                                         | `*` (all)                                                                                                     |
| `SKIP_SERVICE_VERSION_REQUIREMENTS`                                                                      | Set this to True if you want to disable checking for dependent service version requirements.                                                                                                                                                        | `False`                                                                                                       |
| `ACTION_EVENT_MAPPING_INTERVAL_SECONDS`                                                                  | Specify how often (in seconds) PostHog should run a job to match events to actions.                                                                                                                                                                 | `300`                                                                                                         |
| `ASYNC_EVENT_ACTION_MAPPING`                                                                             | If set to `False`, actions will be matched to events as they come. Otherwise, the matching will happen in batches through a periodic Celery task. Should only be toggled on by high load instances.                                                 | `False`                                                                                                       |
| `CAPTURE_INTERNAL_METRICS`                                                                               | Send some internal instrumentation to your own posthog instance, exposed via `/instance/status` page. For EE only.                                                                                                                                  | `False`                                                                                                       |
| `DATABASE_URL`                                                                                           | [Database URL](https://github.com/jacobian/dj-database-url#url-schema) pointing to your PostgreSQL instance.                                                                                                                                        | `postgres://localhost:5432/posthog` if PostHog is running in DEBUG or TEST mode, must be specified otherwise. |
| `DEBUG_QUERIES`                                                                                          | Whether debugging queries (ClickHouse) is enabled in the Command Palette.                                                                                                                                                                           | `False`                                                                                                       |
| `DEBUG`                                                                                                  | Determines if PostHog should run in [DEBUG mode](https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-DEBUG). You can set this to a truthy value when developing, but disable this in production!                                        | `False`                                                                                                       |
| `CLICKHOUSE_DISABLE_EXTERNAL_SCHEMAS`                                                                    | If set, disables using ProtoBuf schemas for kafka communication. Needs to be set when using an external ClickHouse service provider during initial deploy.                                                                                          | `False`                                                                                                       |
| `DISABLE_PAID_FEATURE_SHOWCASING`                                                                        | Whether any showcasing of a paid feature should be disabled. Useful if running a free open source version of PostHog and are not interested in premium functionality.                                                                               | `False`                                                                                                       |
| `DISABLE_SECURE_SSL_REDIRECT`                                                                            | Disables automatic redirect from port 80 (HTTP) to port 443 (HTTPS).                                                                                                                                                                                | `False`                                                                                                       |
| `GITHUB_TOKEN`                                                                                           | GitHub personal access token, used to prevent rate limiting when using apps and to allow installation of apps from private repos                                                                                                                    | `None`                                                                                                        |
| `GITLAB_TOKEN`                                                                                           | GitLab personal access token, used to prevent rate limiting when using apps and to allow installation of apps from private repos                                                                                                                    | `None`                                                                                                        |
| `JS_URL`                                                                                                 | URL used by Webpack for loading external resources like images and files.                                                                                                                                                                           | `http://localhost:8234` if PostHog is running in DEBUG mode, must be specified otherwise.                     |
| `KAFKA_URL`                                                                                              | Address used by the application to contact kafka                                                                                                                                                                                                    | `kafka://kafka`                                                                                               |
| `KAFKA_URL_FOR_CLICKHOUSE`                                                                               | Address used by ClickHouse to read from kafka. Falls back to `KAFKA_URL`                                                                                                                                                                            | `None`                                                                                                        |
| `MATERIALIZE_COLUMNS_ANALYSIS_PERIOD_HOURS`                                                              | Diagnostic for what columns to materialize                                                                                                                                                                                                          | `168`                                                                                                         |
| `MATERIALIZE_COLUMNS_BACKFILL_PERIOD_DAYS`                                                               | How far back backfill materialized columns                                                                                                                                                                                                          | `90`                                                                                                          |
| `MATERIALIZE_COLUMNS_MAX_AT_ONCE`                                                                        | How many columns to materialize at once                                                                                                                                                                                                             | `10`                                                                                                          |
| `MATERIALIZE_COLUMNS_MINIMUM_QUERY_TIME`                                                                 | Diagnostic for what columns to materialize                                                                                                                                                                                                          | `3000`                                                                                                        |
| `MATERIALIZE_COLUMNS_SCHEDULE_CRON`                                                                      | How frequently to run clickhouse column materialization.                                                                                                                                                                                            | `0 5 * * SAT`                                                                                                 |
| `MULTI_ORG_ENABLED`                                                                                      | Allows creating multiple organizations in your instance (multi-tenancy). **Requires a premium license.**                                                                                                                                            | `False`                                                                                                       |
| `NPM_TOKEN`                                                                                              | [Access token for npm](https://docs.npmjs.com/about-access-tokens), used to allow installation of apps released as a private npm package                                                                                                            | `None`                                                                                                        |
| `OPT_OUT_CAPTURE`                                                                                        | Disable sending product usage data to PostHog.                                                                                                                                                                                                      | `False`                                                                                                       |
| `POSTHOG_DB_NAME`                                                                                        | Database name.                                                                                                                                                                                                                                      | Must be specified when `DATABASE_URL` is not set.                                                             |
| `POSTHOG_DB_PASSWORD`                                                                                    | Database password.                                                                                                                                                                                                                                  | `""` if PostHog is running in DEBUG or TEST mode. Must be specified when `DATABASE_URL` is not set.           |
| `POSTHOG_DB_USER`                                                                                        | Database username.                                                                                                                                                                                                                                  | `postgres` if PostHog is running in DEBUG or TEST mode. Must be specified when `DATABASE_URL` is not set.     |
| `POSTHOG_POSTGRES_CLI_SSL_CA`                                                                            | Location of the SSL root certificate file for PostgreSQL. [More info.](https://www.postgresql.org/docs/current/ssl-tcp.html)                                                                                                                        | `None`                                                                                                        |
| `POSTHOG_POSTGRES_CLI_SSL_CRT`                                                                           | Location of the SSL certificate file for PostgreSQL. [More info.](https://www.postgresql.org/docs/current/ssl-tcp.html)                                                                                                                             | `None`                                                                                                        |
| `POSTHOG_POSTGRES_CLI_SSL_KEY`                                                                           | Location of the SSL key file for PostgreSQL. [More info.](https://www.postgresql.org/docs/current/ssl-tcp.html)                                                                                                                                     | `None`                                                                                                        |
| `POSTHOG_POSTGRES_HOST`                                                                                  | Host pointing to your PostgreSQL instance.                                                                                                                                                                                                          | `localhost` if PostHog is running in DEBUG or TEST mode. Must be specified when `DATABASE_URL` is not set.    |
| `POSTHOG_POSTGRES_PORT`                                                                                  | Port pointing to your PostgreSQL instance.                                                                                                                                                                                                          | `5432` if PostHog is running in DEBUG or TEST mode. Must be specified when `DATABASE_URL` is not set.         |
| `POSTHOG_POSTGRES_SSL_MODE`                                                                              | PostgreSQL SSL mode. [More info.](https://www.postgresql.org/docs/9.1/libpq-ssl.html#LIBQ-SSL-CERTIFICATES)                                                                                                                                         | `None`                                                                                                        |
| `REDIS_URL`                                                                                              | [Redis URL](https://redis-py.readthedocs.io/en/stable/#redis.ConnectionPool.from_url) pointing to your Redis instance.                                                                                                                              | `redis://localhost/` if PostHog is running in DEBUG or TEST mode, must be specified otherwise.                |
| `SOCIAL_AUTH_GITHUB_KEY`                                                                                 | GitHub key for allowing [sign up with GitHub](/docs/user-guides/sso#github).                                                                                                                                                                        | _Empty_                                                                                                       |
| `SOCIAL_AUTH_GITHUB_SECRET`                                                                              | GitHub secret for allowing [sign up with GitHub](/docs/user-guides/sso#github).                                                                                                                                                                     | _Empty_                                                                                                       |
| `SOCIAL_AUTH_GITLAB_API_URL`                                                                             | Endpoint to be used for [GitLab authentication](/docs/user-guides/sso#gitlab). Changing this is only relevant for self-host GitLab users.                                                                                                           | `https://gitlab.com`                                                                                          |
| `SOCIAL_AUTH_GITLAB_KEY`                                                                                 | GitLab key for allowing [sign up with GitLab](/docs/user-guides/sso#gitlab).                                                                                                                                                                        | _Empty_                                                                                                       |
| `SOCIAL_AUTH_GITLAB_SECRET`                                                                              | GitLab secret for allowing [sign up with GitLab](/docs/user-guides/sso#gitlab).                                                                                                                                                                     | _Empty_                                                                                                       |
| `SOCIAL_AUTH_GOOGLE_OAUTH2_KEY`                                                                          | Google client ID for allowing [SSO with Google](/docs/user-guides/sso#google).                                                                                                                                                                      | _Empty_                                                                                                       |
| `SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET`                                                                       | Google client secret for allowing [SSO with Google](/docs/user-guides/sso#google).                                                                                                                                                                  | _Empty_                                                                                                       |
| `STATSD_HOST`                                                                                            | Host of a running StatsD daemon (e.g. 127.0.0.1)                                                                                                                                                                                                    | `None`                                                                                                        |
| `STATSD_PORT`                                                                                            | Port for the running StatsD daemon                                                                                                                                                                                                                  | `8125`                                                                                                        |
| `STATSD_PREFIX`                                                                                          | Prefix to be prepended to all stats used by StatsD. Useful for distinguishing environments using the same server.                                                                                                                                   | _Empty_                                                                                                       |
| `TEAM_NEGATIVE_CACHE_CAPACITY`                                                                           | Maximum number of entries in the feature flags negative cache for invalid API tokens (uses LRU eviction).                                                                                                                                           | `10000`                                                                                                       |
| `TEAM_NEGATIVE_CACHE_TTL_SECONDS`                                                                        | Time-to-live in seconds for entries in the feature flags negative cache.                                                                                                                                                                            | `300`                                                                                                         |
| `CLEAR_CLICKHOUSE_REMOVED_DATA_SCHEDULE_CRON`                                                            | When data is (asynchronously) deleted from the events table                                                                                                                                                                                         | `0 5 * * SAT`                                                                                                 |
| `LOG_LEVEL`                                                                                              | The log level for the plugin server.                                                                                                                                                                                                                | `info`                                                                                                        |
| `OBJECT_STORAGE_PUBLIC_ENDPOINT`                                                                         | Public-facing endpoint used for generating presigned URLs. Required when the internal object storage endpoint differs from the externally accessible URL (common in hobby deployments behind a reverse proxy).                                      | Defaults to `OBJECT_STORAGE_ENDPOINT`                                                                         |
| `WORKOS_RADAR_ENABLED`                                                                                   | Enables WorkOS Radar bot/fraud detection for authentication flows.                                                                                                                                                                                  | `False`                                                                                                       |
| `WORKOS_RADAR_API_KEY`                                                                                   | API key for the WorkOS Radar integration.                                                                                                                                                                                                           | _Empty_                                                                                                       |
| `CLOUDFLARE_TURNSTILE_SITE_KEY`                                                                          | Cloudflare Turnstile site key used to present a CAPTCHA challenge during signup when WorkOS Radar returns a "challenge" verdict. If not set, the challenge flow is skipped.                                                                         | _Empty_                                                                                                       |
| `CLOUDFLARE_TURNSTILE_SECRET_KEY`                                                                        | Cloudflare Turnstile secret key for server-side verification of challenge tokens. Required alongside `CLOUDFLARE_TURNSTILE_SITE_KEY`.                                                                                                               | _Empty_                                                                                                       |

## Instance settings

The following settings should mainly be managed with [Instance settings](/docs/self-host/configure/instance-settings). However, if you can still set them via environment variables if you prefer. Please be mindful that if these settings are overridden in the settings page, the overridden values will prevail.

| Variable                   | Description                                 | Default Value                               | Managed with Instance Settings |
| :------------------------- | :------------------------------------------ | :------------------------------------------ | :----------------------------- |
| `EMAIL_DEFAULT_FROM`       | Please see [configuring email] for details. | Please see [configuring email] for details. | ✅ Yes                         |
| `EMAIL_ENABLED`            | Please see [configuring email] for details. | Please see [configuring email] for details. | ✅ Yes                         |
| `EMAIL_HOST_PASSWORD`      | Please see [configuring email] for details. | Please see [configuring email] for details. | ✅ Yes                         |
| `EMAIL_HOST_USER`          | Please see [configuring email] for details. | Please see [configuring email] for details. | ✅ Yes                         |
| `EMAIL_HOST`               | Please see [configuring email] for details. | Please see [configuring email] for details. | ✅ Yes                         |
| `EMAIL_PORT`               | Please see [configuring email] for details. | Please see [configuring email] for details. | ✅ Yes                         |
| `EMAIL_USE_TLS`            | Please see [configuring email] for details. | Please see [configuring email] for details. | ✅ Yes                         |
| `EMAIL_USE_SSL`            | Please see [configuring email] for details. | Please see [configuring email] for details. | ✅ Yes                         |
| `SLACK_APP_CLIENT_ID`      | Please see [configuring slack] for details. | Please see [configuring slack] for details. | ✅ Yes                         |
| `SLACK_APP_CLIENT_SECRET`  | Please see [configuring slack] for details. | Please see [configuring slack] for details. | ✅ Yes                         |
| `SLACK_APP_SIGNING_SECRET` | Please see [configuring slack] for details. | Please see [configuring slack] for details. | ✅ Yes                         |

[configuring email]: /docs/self-host/configure/email#general-configuration
[configuring slack]: /docs/self-host/configure/slack
