Environment variables

Many settings in Metabase can be configured via environment variables. Environment variables take precedence over settings configured in the Admin Panel and are not written to the application database.

Environment variables are ideal for production deployments as they keep sensitive configuration outside your codebase and allow different settings per environment.

How to set environment variables

The method for setting environment variables depends on how you’re running Metabase.

Export variables before running the JAR:

export MB_DB_TYPE=postgres
export MB_DB_DBNAME=metabase
export MB_SITE_NAME="My Company Analytics"
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

$env:MB_DB_TYPE="postgres"
$env:MB_DB_DBNAME="metabase"
$env:MB_SITE_NAME="My Company Analytics"
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

set MB_DB_TYPE=postgres
set MB_DB_DBNAME=metabase
set MB_SITE_NAME=My Company Analytics
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

Set as Java system properties (works on all platforms):

java -DMB_DB_TYPE=postgres -DMB_DB_DBNAME=metabase -jar metabase.jar

Use the -e flag for each variable:

docker run -d -p 3000:3000 \
  -e MB_DB_TYPE=postgres \
  -e MB_DB_DBNAME=metabase \
  -e MB_SITE_NAME="My Company Analytics" \
  --name metabase metabase/metabase

Define in your docker-compose.yml:

services:
  metabase:
    image: metabase/metabase:latest
    environment:
      MB_DB_TYPE: postgres
      MB_DB_DBNAME: metabase
      MB_DB_HOST: postgres
      MB_DB_PORT: 5432
      MB_DB_USER: metabase
      MB_DB_PASS: secretpassword

Add to your service file:

[Service]
Environment="MB_DB_TYPE=postgres"
Environment="MB_DB_DBNAME=metabase"
Environment="MB_SITE_NAME=My Company Analytics"
ExecStart=/usr/bin/java -jar /opt/metabase/metabase.jar

Core configuration variables

Application database

These variables configure where Metabase stores its application data.

MB_DB_TYPE

string

required

Database type for Metabase application dataOptions: postgres, mysql, h2Example: postgres

MB_DB_DBNAME

string

Name of the application databaseExample: metabase

MB_DB_HOST

string

Database server hostname or IP addressExample: localhost or db.example.com

MB_DB_PORT

integer

Database server portDefault: 5432 (PostgreSQL), 3306 (MySQL)

MB_DB_USER

string

Database usernameExample: metabase_user

MB_DB_PASS

string

Database password

Keep this secure. Consider using Docker secrets or environment files with restricted permissions.

MB_DB_CONNECTION_URI

string

Full JDBC connection string (overrides individual parameters)Example: jdbc:postgresql://localhost:5432/metabase?user=username&password=password

MB_DB_FILE

string

Path to H2 database file (H2 only)Example: /data/metabase.db

H2 automatically appends .mv.db or .h2.db - don’t include these extensions.

Server configuration

MB_JETTY_HOST

string

Hostname or IP address for the Jetty web server to bind toDefault: localhostExample: 0.0.0.0 (listen on all interfaces)

MB_JETTY_PORT

integer

Port for the Jetty web serverDefault: 3000

MB_JETTY_SSL

boolean

Enable SSL/HTTPSDefault: false

MB_JETTY_SSL_PORT

integer

Port for HTTPS when SSL is enabledDefault: 8443

MB_JETTY_SSL_KEYSTORE

string

Path to Java keystore file for SSL

MB_JETTY_SSL_KEYSTORE_PASSWORD

string

Password for the SSL keystore

Site settings

MB_SITE_NAME

string

The name of your Metabase siteDefault: MetabaseExample: Analytics Portal

MB_SITE_URL

string

The base URL where users access MetabaseExample: https://analytics.company.com

Important for email links and embedding.

MB_SITE_LOCALE

string

Default language for your Metabase instanceDefault: enOptions: en, es, fr, de, pt, zh, ja, and more

Email configuration

MB_EMAIL_SMTP_HOST

string

SMTP server hostnameExample: smtp.gmail.com

MB_EMAIL_SMTP_PORT

integer

SMTP server portCommon values: 587 (TLS), 465 (SSL), 25 (plain)

MB_EMAIL_SMTP_USERNAME

string

SMTP authentication username

MB_EMAIL_SMTP_PASSWORD

string

SMTP authentication password

MB_EMAIL_SMTP_SECURITY

string

SMTP security protocolOptions: none, tls, ssl, starttlsDefault: none

MB_EMAIL_FROM_ADDRESS

string

Email address to use as senderDefault: notifications@metabase.comExample: analytics@company.com

MB_EMAIL_FROM_NAME

string

Display name for email senderExample: Company Analytics

Performance and limits

MB_UNAGGREGATED_QUERY_ROW_LIMIT

integer

Maximum rows returned for unaggregated queriesDefault: 2000

MB_AGGREGATED_QUERY_ROW_LIMIT

integer

Maximum rows returned for aggregated queriesDefault: 10000Max: 1048575

MB_DOWNLOAD_ROW_LIMIT

integer

Row limit for file downloads (excluding header)

XLSX files are limited to 1,048,575 rows regardless of this setting.

MB_QUERY_CACHING_MAX_KB

integer

Maximum cache size per saved question (in kilobytes)Default: 2000

MB_QUERY_CACHING_MAX_TTL

number

Maximum time to cache query results (in seconds)Default: 3024000 (35 days)

MB_DB_CONNECTION_TIMEOUT_MS

integer

Database connection timeout in millisecondsDefault: 10000 (10 seconds)

Increase for SSH tunnels or slow networks.

MB_DB_QUERY_TIMEOUT_MINUTES

integer

Query execution timeout in minutesDefault: 20

Frontend and reverse proxy timeouts may still apply.

MB_JDBC_DATA_WAREHOUSE_MAX_CONNECTION_POOL_SIZE

integer

Maximum connection pool size for data warehousesDefault: 15

Security settings

MB_EMBEDDING_SECRET_KEY

string

Secret key for signing embedded analytics tokens

Keep this secret secure. Changing it will invalidate all existing embedded URLs.

MB_ENABLE_EMBEDDING_STATIC

boolean

Enable static embeddingDefault: false

MB_ENABLE_EMBEDDING_INTERACTIVE

boolean

Enable interactive embeddingDefault: false

Pro/Enterprise only

Allow creating public links for questions and dashboardsDefault: true

MB_REDIRECT_ALL_REQUESTS_TO_HTTPS

boolean

Force HTTPS redirect when site URL uses HTTPSDefault: false

MB_SESSION_COOKIES

boolean

Use session cookies instead of persistent cookiesDefault: false

MB_PASSWORD_COMPLEXITY

string

Password complexity requirementsOptions: weak, normal, strongDefault: normal

Authentication

LDAP

MB_LDAP_ENABLED

boolean

Enable LDAP authenticationDefault: false

MB_LDAP_HOST

string

LDAP server hostname

MB_LDAP_PORT

integer

LDAP server portDefault: 389 (plain), 636 (SSL)

MB_LDAP_SECURITY

string

LDAP security protocolOptions: none, ssl, starttls

MB_LDAP_BIND_DN

string

Distinguished Name for LDAP bind userExample: cn=admin,dc=company,dc=com

MB_LDAP_PASSWORD

string

Password for LDAP bind user

MB_LDAP_USER_BASE

string

Base DN for user searchesExample: ou=users,dc=company,dc=com

SAML (Pro/Enterprise)

MB_SAML_ENABLED

boolean

Enable SAML authenticationDefault: false

Pro/Enterprise only

MB_SAML_IDENTITY_PROVIDER_URI

string

SAML identity provider URL

MB_SAML_IDENTITY_PROVIDER_CERTIFICATE

string

Identity provider certificate (base64 encoded)

JWT (Pro/Enterprise)

MB_JWT_ENABLED

boolean

Enable JWT authenticationDefault: false

Pro/Enterprise only

MB_JWT_SHARED_SECRET

string

Secret for JWT token validation

Use a strong 256-bit key (64 hex characters)

MB_JWT_IDENTITY_PROVIDER_URI

string

URL for JWT-based login page

Docker-specific variables

JAVA_TIMEZONE

string

Java timezone for the Metabase applicationExample: US/Pacific, Europe/London, Asia/TokyoDefault: System timezone

MUID

integer

User ID for the Metabase process in DockerExample: 1000

MGID

integer

Group ID for the Metabase process in DockerExample: 1000

Logging and monitoring

MB_AUDIT_MAX_RETENTION_DAYS

integer

Days to retain audit log dataDefault: null (keep forever)Minimum: 30 daysNote: Set to 0 to keep all data

MB_HEALTH_CHECK_LOGGING_ENABLED

boolean

Log health check requestsDefault: true

MB_HIDE_STACKTRACES

boolean

Hide stack traces in error responsesDefault: false

Enable in production to avoid exposing internal details.

Feature flags

MB_CHECK_FOR_UPDATES

boolean

Check for new Metabase versionsDefault: true

MB_ENABLE_XRAYS

boolean

Enable X-ray auto-exploration featuresDefault: true

MB_ANON_TRACKING_ENABLED

boolean

Send anonymous usage statisticsDefault: true

MB_PERSISTED_MODELS_ENABLED

boolean

Allow persisting models to source databasesDefault: false

MB_ENABLE_PIVOTED_EXPORTS

boolean

Enable pivoted exports and subscriptionsDefault: true

Licensing (Pro/Enterprise)

MB_PREMIUM_EMBEDDING_TOKEN

string

License token for Pro or Enterprise features

Get your token from the MetaStore

Advanced configuration

MB_APPLICATION_DB_MAX_CONNECTION_POOL_SIZE

integer

Maximum connection pool size for application databaseDefault: Calculated based on available connections

MB_NOTIFICATION_THREAD_POOL_SIZE

integer

Thread pool size for sending notificationsDefault: 3

Increase if alerts are slow to send.

MB_NOTIFICATION_LINK_BASE_URL

string

Override base URL for notification links (Pro/Enterprise)Use case: Different URL for embedded vs. direct access

Using Docker secrets

For sensitive configuration, use Docker secrets instead of environment variables:

docker-compose.yml

services:
  metabase:
    image: metabase/metabase:latest
    environment:
      MB_DB_TYPE: postgres
      MB_DB_DBNAME: metabase
      MB_DB_PORT: 5432
      MB_DB_USER_FILE: /run/secrets/db_user
      MB_DB_PASS_FILE: /run/secrets/db_password
      MB_DB_HOST: postgres
    secrets:
      - db_user
      - db_password

secrets:
  db_user:
    file: ./db_user.txt
  db_password:
    file: ./db_password.txt

Supported secret variables (append _FILE):

MB_DB_USER_FILE
MB_DB_PASS_FILE
MB_DB_CONNECTION_URI_FILE
MB_EMAIL_SMTP_PASSWORD_FILE
MB_EMAIL_SMTP_USERNAME_FILE
MB_LDAP_PASSWORD_FILE
MB_LDAP_BIND_DN_FILE

Environment file example

Create a .env file for easy configuration:

.env

# Database
MB_DB_TYPE=postgres
MB_DB_DBNAME=metabase
MB_DB_HOST=localhost
MB_DB_PORT=5432
MB_DB_USER=metabase_user
MB_DB_PASS=secure_password

# Server
MB_JETTY_HOST=0.0.0.0
MB_JETTY_PORT=3000

# Site
MB_SITE_NAME=Company Analytics
MB_SITE_URL=https://analytics.company.com
MB_SITE_LOCALE=en

# Email
MB_EMAIL_SMTP_HOST=smtp.gmail.com
MB_EMAIL_SMTP_PORT=587
MB_EMAIL_SMTP_USERNAME=analytics@company.com
MB_EMAIL_SMTP_PASSWORD=app_password
MB_EMAIL_SMTP_SECURITY=tls
MB_EMAIL_FROM_ADDRESS=analytics@company.com

# Performance
MB_QUERY_CACHING_MAX_KB=5000
MB_AGGREGATED_QUERY_ROW_LIMIT=20000

# Security
MB_REDIRECT_ALL_REQUESTS_TO_HTTPS=true
MB_PASSWORD_COMPLEXITY=strong

# Features
MB_CHECK_FOR_UPDATES=true
MB_ENABLE_XRAYS=true

Never commit .env files with passwords to version control. Add to .gitignore.

Configuration precedence

When Metabase looks for configuration, the order of precedence is:

Environment variables (highest priority)
Java system properties (-D flags)
Admin panel settings (stored in database)
Default values (lowest priority)

Metabase Cloud

For Metabase Cloud instances, contact support to configure environment variables.

Next steps

Configure database

Set up your application database

Running on Docker

Deploy with Docker and environment variables

Customizing Jetty

Advanced web server configuration

Email setup

Configure email notifications

Getting Started

Questions & Dashboards

Data Modeling

Database Connections

Embedding

Administration

Installation & Operations

AI Features

Environment variables

How to set environment variables

Core configuration variables

Application database

Server configuration

Site settings

Email configuration

Performance and limits

Security settings

Authentication

LDAP

SAML (Pro/Enterprise)

JWT (Pro/Enterprise)

Docker-specific variables

Logging and monitoring

Feature flags

Licensing (Pro/Enterprise)

Advanced configuration

Using Docker secrets

Environment file example

Configuration precedence

Metabase Cloud

Next steps

Configure database

Running on Docker

Customizing Jetty

Email setup

Getting Started

Questions & Dashboards

Data Modeling

Database Connections

Embedding

Administration

Installation & Operations

AI Features

Documentation Index

​How to set environment variables

​Core configuration variables

​Application database

​Server configuration

​Site settings

​Email configuration

​Performance and limits

​Security settings

​Authentication

​LDAP

​SAML (Pro/Enterprise)

​JWT (Pro/Enterprise)

​Docker-specific variables

​Logging and monitoring

​Feature flags

​Licensing (Pro/Enterprise)

​Advanced configuration

​Using Docker secrets

​Environment file example

​Configuration precedence

​Metabase Cloud

​Next steps

Configure database

Running on Docker

Customizing Jetty

Email setup

How to set environment variables

Core configuration variables

Application database

Server configuration

Site settings

Email configuration

Performance and limits

Security settings

Authentication

LDAP

SAML (Pro/Enterprise)

JWT (Pro/Enterprise)

Docker-specific variables

Logging and monitoring

Feature flags

Licensing (Pro/Enterprise)

Advanced configuration

Using Docker secrets

Environment file example

Configuration precedence

Metabase Cloud

Next steps