Environment:Dagster io Dagster DAGSTER HOME Configuration

Knowledge Sources	dagster instance factory Instance Configuration
Domains	Infrastructure, Configuration
Last Updated	2026-02-10 12:00 GMT

Overview

Instance-level configuration environment defined by the DAGSTER_HOME environment variable and dagster.yaml file.

Description

DAGSTER_HOME is the primary environment variable that Dagster uses to locate its configuration directory. This directory contains the dagster.yaml configuration file, local artifact storage (SQLite databases by default), compute logs, and telemetry data. When not set, Dagster falls back to an ephemeral in-memory instance suitable only for testing.

Usage

Use this environment configuration for any production or development deployment of Dagster. It is required whenever you need persistent storage of run history, event logs, schedule state, or compute logs. The dagster dev command, dagster-webserver, and dagster-daemon all require DAGSTER_HOME to be set.

System Requirements

Category	Requirement	Notes
Filesystem	Writable directory at `$DAGSTER_HOME`	Must be an absolute path to an existing directory
Disk	Varies by usage	SQLite storage grows with run history; allocate based on retention needs
Network	Optional	Only needed if using remote storage (PostgreSQL, MySQL)

Dependencies

Configuration File

dagster.yaml - Located at $DAGSTER_HOME/dagster.yaml
Configures: storage backend, compute log manager, run launcher, run coordinator, telemetry

Storage Backends

SQLite (default) - No additional packages needed
PostgreSQL - Requires dagster-postgres package
MySQL - Requires dagster-mysql package

Credentials

The following environment variables are used for instance configuration:

DAGSTER_HOME: Required. Absolute path to the Dagster configuration directory.
DAGSTER_DISABLE_TELEMETRY: Optional. Set to disable telemetry reporting.
DAGSTER_PROJECT_ENV_FILE_PATHS: Optional. Paths to additional .env files for project configuration.
DAGSTER_REDACT_USER_CODE_ERRORS: Optional. Set to "1", "true", or "t" to redact sensitive information from error messages.

Quick Install

# Set DAGSTER_HOME (add to shell profile for persistence)
export DAGSTER_HOME=~/dagster_home
mkdir -p $DAGSTER_HOME

# Optionally create dagster.yaml for custom configuration
touch $DAGSTER_HOME/dagster.yaml

Code Evidence

DAGSTER_HOME requirement from factory.py:62-98:

def create_instance_from_dagster_home() -> "DagsterInstance":
    dagster_home_path = os.getenv("DAGSTER_HOME")

    if not dagster_home_path:
        raise DagsterHomeNotSetError(
            "The environment variable $DAGSTER_HOME is not set. ..."
        )

    dagster_home_path = os.path.expanduser(dagster_home_path)

    if not os.path.isabs(dagster_home_path):
        raise DagsterInvariantViolationError(
            f'$DAGSTER_HOME "{dagster_home_path}" must be an absolute path.'
        )

Telemetry control from telemetry_upload.py:12-19:

DAGSTER_TELEMETRY_URL = os.getenv(
    "DAGSTER_TELEMETRY_URL", "http://telemetry.dagster.io/actions"
)
DAGSTER_DISABLE_TELEMETRY = os.getenv("DAGSTER_DISABLE_TELEMETRY")

Common Errors

Error Message	Cause	Solution
`DagsterHomeNotSetError: The environment variable $DAGSTER_HOME is not set`	DAGSTER_HOME not exported	`export DAGSTER_HOME=~/dagster_home`
`DagsterInvariantViolationError: ... must be an absolute path`	Relative path provided	Use absolute path (e.g., `/home/user/dagster_home`)
`DagsterInvariantViolationError: ... is not a directory`	Directory does not exist	`mkdir -p $DAGSTER_HOME`

Compatibility Notes

Default storage: SQLite databases stored in $DAGSTER_HOME/storage/. Suitable for development but not recommended for production at scale.
Production: Use PostgreSQL (dagster-postgres) for production deployments requiring concurrent access and durability.
Ephemeral mode: DagsterInstance.ephemeral() can be used for testing without setting DAGSTER_HOME, but all data is lost on process exit.
Logs directory: Compute logs stored at $DAGSTER_HOME/logs/ by default.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment