Environment variables

Last updated:

As of PostHog 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 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 has more information about them.

VariableDescriptionDefault Value
SECRET_KEY❗️ Always required. Used by Django for cryptography. 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_COOKIESDetermines if Django should use secure cookies. Insecure cookies do not work without HTTPS.False if PostHog is running in DEBUG or TEST mode, else True
SENTRY_DSNUsed to integrate with Sentry error and event tracking. Ignored when running tests.None
IS_BEHIND_PROXYSpecifies if PostHog is running behind a proxy like Apache, NGINX or ELB. Be sure to properly set trusted proxies.False
ALLOWED_IP_BLOCKSSpecifies 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 if running behind a proxy.Empty
TRUSTED_PROXIESSpecifies the IPs of proxies that can be trusted.None
TRUST_ALL_PROXIESDetermines if all proxies can be trusted.False
ALLOWED_HOSTSA list of strings representing the host/domain names that Django can serve. More info.* (all)
SKIP_SERVICE_VERSION_REQUIREMENTSSet this to True if you want to disable checking for dependent service version requirements.False
ACTION_EVENT_MAPPING_INTERVAL_SECONDSSpecify how often (in seconds) PostHog should run a job to match events to actions.300
ASYNC_EVENT_ACTION_MAPPINGIf 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_METRICSSend some internal instrumentation to your own posthog instance, exposed via /instance/status page. For EE only.False
DATABASE_URLDatabase URL pointing to your PostgreSQL instance.postgres://localhost:5432/posthog if PostHog is running in DEBUG or TEST mode, must be specified otherwise.
DEBUG_QUERIESWhether debugging queries (ClickHouse) is enabled in the Command Palette.False
DEBUGDetermines if PostHog should run in DEBUG mode. You can set this to a truthy value when developing, but disable this in production!False
CLICKHOUSE_DISABLE_EXTERNAL_SCHEMASIf 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_SHOWCASINGWhether 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_REDIRECTDisables automatic redirect from port 80 (HTTP) to port 443 (HTTPS).False
GITHUB_TOKENGitHub personal access token, used to prevent rate limiting when using apps and to allow installation of apps from private reposNone
GITLAB_TOKENGitLab personal access token, used to prevent rate limiting when using apps and to allow installation of apps from private reposNone
JS_URLURL 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_URLAddress used by the application to contact kafkakafka://kafka
KAFKA_URL_FOR_CLICKHOUSEAddress used by ClickHouse to read from kafka. Falls back to KAFKA_URLNone
MATERIALIZE_COLUMNS_ANALYSIS_PERIOD_HOURSDiagnostic for what columns to materialize168
MATERIALIZE_COLUMNS_BACKFILL_PERIOD_DAYSHow far back backfill materialized columns90
MATERIALIZE_COLUMNS_MAX_AT_ONCEHow many columns to materialize at once10
MATERIALIZE_COLUMNS_MINIMUM_QUERY_TIMEDiagnostic for what columns to materialize3000
MATERIALIZE_COLUMNS_SCHEDULE_CRONHow frequently to run clickhouse column materialization.0 5 * * SAT
MULTI_ORG_ENABLEDAllows creating multiple organizations in your instance (multi-tenancy). Requires a premium license.False
NPM_TOKENAccess token for npm, used to allow installation of apps released as a private npm packageNone
OPT_OUT_CAPTURINGDisable sending product usage data to PostHog.False
POSTHOG_DB_NAMEDatabase name.Must be specified when DATABASE_URL is not set.
POSTHOG_DB_PASSWORDDatabase password."" if PostHog is running in DEBUG or TEST mode. Must be specified when DATABASE_URL is not set.
POSTHOG_DB_USERDatabase user name.postgres if PostHog is running in DEBUG or TEST mode. Must be specified when DATABASE_URL is not set.
POSTHOG_POSTGRES_CLI_SSL_CALocation of the SSL root certificate file for PostgreSQL. More info.None
POSTHOG_POSTGRES_CLI_SSL_CRTLocation of the SSL certificate file for PostgreSQL. More info.None
POSTHOG_POSTGRES_CLI_SSL_KEYLocation of the SSL key file for PostgreSQL. More info.None
POSTHOG_POSTGRES_HOSTHost 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_PORTPort 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_MODEPostgreSQL SSL mode. More info.None
REDIS_URLRedis URL pointing to your Redis instance.redis://localhost/ if PostHog is running in DEBUG or TEST mode, must be specified otherwise.
SOCIAL_AUTH_GITHUB_KEYGitHub key for allowing sign up with GitHub.Empty
SOCIAL_AUTH_GITHUB_SECRETGitHub secret for allowing sign up with GitHub.Empty
SOCIAL_AUTH_GITLAB_API_URLEndpoint to be used for GitLab authentication. Changing this is only relevant for self-host GitLab users.https://gitlab.com
SOCIAL_AUTH_GITLAB_KEYGitLab key for allowing sign up with GitLab.Empty
SOCIAL_AUTH_GITLAB_SECRETGitLab secret for allowing sign up with GitLab.Empty
SOCIAL_AUTH_GOOGLE_OAUTH2_KEYGoogle client ID for allowing SSO with Google.Empty
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRETGoogle client secret for allowing SSO with Google.Empty
STATSD_HOSTHost of a running StatsD daemon (e.g. 127.0.0.1)None
STATSD_PORTPort for the running StatsD daemon8125
STATSD_PREFIXPrefix to be prepended to all stats used by StatsD. Useful for distinguishing environments using the same server.Empty

Instance settings

The following settings should mainly be managed with 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.

VariableDescriptionDefault ValueManaged with Instance Settings
EMAIL_DEFAULT_FROMPlease see configuring email for details.Please see configuring email for details.✅ Yes
EMAIL_ENABLEDPlease see configuring email for details.Please see configuring email for details.✅ Yes
EMAIL_HOST_PASSWORDPlease see configuring email for details.Please see configuring email for details.✅ Yes
EMAIL_HOST_USERPlease see configuring email for details.Please see configuring email for details.✅ Yes
EMAIL_HOSTPlease see configuring email for details.Please see configuring email for details.✅ Yes
EMAIL_PORTPlease see configuring email for details.Please see configuring email for details.✅ Yes
EMAIL_USE_TLSPlease see configuring email for details.Please see configuring email for details.✅ Yes
EMAIL_USE_TLSPlease see configuring email for details.Please see configuring email for details.✅ Yes

Questions?