Skip to main content

Configuring dg

warning

This feature is considered in a preview stage and is under active development. It can change significantly, or be removed completely. It is not considered ready for production use.

dg can be configured from both configuration files and the command line. There are three kinds of settings:

  • Application-level settings configure the dg application as a whole. They can be set in configuration files or on the command line, where they are listed as "global options" in the dg --help text.
  • Project-level settings configure a dg project. They can only be set in the configuration file for a project.
  • Workspace-level settings configure a dg workspace. They can only be set in the configuration file for a workspace.
tip

The application-level settings used in any given invocation of dg are the result of merging settings from one or more configuration files and the command line. The order of precedence is:

user config file < project/workspace config file < command line

Note that project and workspace config files are combined above. This is because, when projects are inside a workspace, application-level settings are sourced from the workspace configuration file and disallowed in the constituent project configuration files. In other words, application-level settings are only allowed in project configuration files if the project is not inside a workspace.

Configuration files​

There are three kinds of dg configuration files: user, project, and workspace.

  • User configuration files are optional and contain only application-level settings. They are located in a platform-specific location, ~/.dg.toml (Unix) or %APPDATA%/dg/dg.toml (Windows).
  • Project configuration files are required to mark a directory as a dg project. They are located in the root of a dg project and contain project-specific settings. They may also contain application-level settings if the project is not inside a workspace.
  • Workspace configuration files are required to mark a directory as a dg workspace. They are located in the root of a dg workspace and contain workspace-specific settings. They may also contain application-level settings. When projects are inside a workspace, the application-level settings of the workspace apply to all contained projects as well.

When dg is launched, it will attempt to discover all three configuration files by looking up the directory hierarchy from the CWD (and in the dedicated location for user configuration files). Many commands require a project or workspace to be in scope. If the corresponding configuration file is not found when launching such a command, dg will raise an error.

User configuration file​

A user configuration file can be placed at ~/.dg.toml (Unix) or %APPDATA%/dg/dg.toml (Windows).

Below is an example of a user configuration file. The cli section contains application-level settings and is the only permitted section. The settings listed in the below sample are comprehensive:

.dg.toml
[cli]
# (bool, optional) Specifies whether the `dg` cache is disabled.
#
# Defaults to `false`.
disable_cache = false

# (string, optional) Specifies the directory where the `dg` cache is stored.
#
# Defaults to a platform-specific cache directory.
cache_dir = "/path/to/my-cache"

# (bool, optional) Specifies whether to use verbose output.
# 
# Defaults to `false`.
verbose = false

# Telemetry-related settings.
[cli.telemetry]

# (bool, optional) Specifies whether to enable telemetry.
# 
# Defaults to `true`.
enabled = true


# The `cli.plus` section is a replacement for `.dagster_cloud_cli.yaml`. The
# settings here are required to run `dg plus` commands.
[cli.plus]

# (string, optional) Your Dagster Plus organization, to run dg plus commands against.
#
# Defaults to None.
organization = "hooli"

# (string, optional) The default deployment to run commands against, if another
# deployment is not explicitly specified
#
# Defaults to None.
default_deployment = "prod"

# (optional, str) A Dagster Plus user token to authenticate to your organization
#
# Defaults to None.
user_token = "user:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Project configuration file​

A project configuration file is located in the root of a dg project. It may either be a pyproject.toml file or a dg.toml file. If it is a pyproject.toml, then all settings are nested under the tool.dg key. If it is a dg.toml file, then settings should be placed at the top level. Usually pyproject.toml is used for project configuration.

Below is an example of the dg-scoped part of a pyproject.toml (note all settings are part of tool.dg.* tables) for a project named my-project. The tool.dg.project section is a comprehensive list of supported settings:

pyproject.toml
[tool.dg]

# ("project", required) Marks this as a Dagster project.
directory_type = "project"

[tool.dg.project]

# (string, required) Specifies the root module of the project.
root_module = "my_project" # this is required

# (string, optional) Specifies the project submodule where new components and
# definitions are scaffolded.
# 
# Defaults to `<root_module>.defs`.
defs_module = "my_project.defs" # 

# (string, optional) Specifies the project submodule containing the top-level `Definitions`
# object that is targeted when loading the project as a code location.
#
# Defaults to `<root_module>.definitions`.
code_location_target_module = "my_project.definitions"

# (string, optional) Specifies the name used for the code location when the project is
# loaded as a code location.
#
# Defaults to the project name (which is usually the # hyphenated variant of
# the root module name).
code_location_name = "my-project"

# (string, optional) Specifies the python environment to use when spawning subprocesses
# for this project. Subprocesses are spawned whenever `dg` needs to list
# available component types, check definitions, scaffold new components, etc.
# The value must be one of: 
#
# - "active" (default): use the currently active Python environment, i.e. the
#   Python environment corresponding to `which python`. This may be an
#   activated virtual environment.
# - "persistent_uv": use a dedicated project-scoped virtual environment that is
#   located at <project_root>/`.venv` and is managed by `uv`. Subprocesses are
#   launched with `uv run`.
#
# Defaults to "active".
python_environment = "active"

[tool.dg.cli]

# Application-level settings can be set here. See "User configuration file"
# section for a comprehensive list of available settings.

# If the project is inside a workspace, then this section is disallowed
# (`tool.dg.cli` should # be set in the workspace config instead).

Workspace configuration file​

A workspace configuration file is located in the root of a dg workspace. It may either be a pyproject.toml file or a dg.toml file. If it is a pyproject.toml, then all settings are nested under the tool.dg key. If it is a dg.toml file, then all settings are top-level keys. Usually dg.toml is used for workspace configuration.

Below is an example of a dg.toml file for a workspace. The workspace section is a comprehensive list of supported settings:

dg.toml
# ("workspace", required) Marks this as a Dagster workspace.
directory_type = "workspace"

[workspace]

# (array, required) Any projects in the workspace need to be listed as items in the
# `tool.dg.workspace.projects` array of tables.
#
# By default this array is empty.
[[workspace.projects]]

# (string, required) The path to the project relative to the workspace root.
path = "projects/project-1"

[[workspace.projects]]

# (string, required) The path to the project relative to the workspace root.
path = "projects/project-2"

[cli]

# Application-level settings can be set here. See "User configuration file"
# section for a comprehensive list of available settings.