Dagster project structure overview

This reference contains details about the default files and directories and additional deployment configuration files in a Dagster project.

Default files and directories

Below is the default project structure generated by the create-dagster project command:

uv

tree my-project

my-project
├── pyproject.toml
├── README.md
├── src
│   └── my_project
│       ├── __init__.py
│       ├── definitions.py
│       └── defs
│           └── __init__.py
├── tests
│   └── __init__.py
└── uv.lock

5 directories, 7 files

pip

tree my-project

my-project
├── pyproject.toml
├── README.md
├── src
│   └── my_project
│       ├── __init__.py
│       ├── definitions.py
│       └── defs
│           └── __init__.py
└── tests
    └── __init__.py

5 directories, 6 files

tip

To use tree, install it with brew install tree (Mac), or follow the installation instructions (Windows and Linux).

File or directory	Description
src/my_project	Python package that contains the deployable code that defines your Dagster pipelines.
src/my_project/definitions.py	The entry point that Dagster will load when deploying your project.
src/my_project/defs	Will contain your Dagster definitions and component definitions.
src/my_project/components (not pictured)	An optional folder used to define custom components, and optionally other code you wish to share across Dagster definitions.
tests	A separate Python package defined at the top level (outside src). It should contain tests for the my_project package.
pyproject.toml	A standard Python package configuration file. In addition to the regular Python package metadata, it contains a tool.dg section for dg-specific settings.

Dagster instance and deployment configuration files

Depending on your use case or if you're using Dagster+, you may also need to add additional configuration files to your project.

File/Directory	Description	OSS	Dagster+	Created by
dagster.yaml	Configures your Dagster instance, including defining storage locations, run launchers, sensors, and schedules. For more information. including a list of use cases and available options, see the dagster.yaml reference. For Dagster+ Hybrid deployments, this file can be used to customize the Hybrid agent.	Optional	Optional	Manually created
deployment_settings.yaml	Configures settings for full deployments in Dagster+, including run queue priority and concurrency limits. See the full deployment settings reference. Note: This file can be named anything, but we recommend choosing a name that is easy to understand.	Not applicable	Optional	Manually created
build.yaml	Defines projects for Dagster+ deployment. See the build.yaml reference.	Not applicable	Dagster+ Hybrid only	dg plus deploy configure CLI command
container_context.yaml	Allows you to set environment variables or resource limits for the code server or run containers used in your infrastructure (Kubernetes, ECS, Docker).	Not applicable	Dagster+ Hybrid only	dg plus deploy configure CLI command
Dockerfile	Contains instructions to build a Docker image for use in a Dagster deployment.	Not applicable	Dagster+ Hybrid only	dg plus deploy configure CLI command

CI/CD configuration files

• For OSS deployments, you can add your own CI/CD files as needed.
• For Dagter+ deployments, you can use the dg plus deploy configure CLI command to generate CI/CD files for GitHub or GitLab, or set your system to use the necessary dg deploy CLI commands if you use a different Git provider. For more information, see the Dagster+ CI/CD documentation.