Initializing a dg project

info

This feature is considered in a preview stage and is under active development. There may be API changes and feature gaps. Please go to the #dg-components channel in our Slack to report issues or give feedback.

dg provides support for generating a special type of Python package, called a project, that defines a Dagster code location. dg can be used with any Python package manager, but we recommend uv for the best experience.

uv

Install uv

Mac

brew install uv

Windows

powershell -ExecutionPolicy ByPass -c 'irm https://astral.sh/uv/install.ps1 | iex'

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

For more detailed uv installation instructions, see the uv docs.

Ensure you have dg installed globally as a uv tool:

uv tool install dagster-dg

Now run the below command. Say yes to the prompt to run uv sync after scaffolding:

dg init my-project

The dg init command builds a project at my-project. Running uv sync after scaffolding creates a virtual environment and installs the dependencies listed in pyproject.toml, along with my-project itself as an editable install. Now let's enter the directory and activate the virtual environment:

cd my-project && source .venv/bin/activate

pip

Because pip does not support global installations, you will install dg inside your project virtual environment. We'll create and enter our project directory, initialize and activate a virtual environment, and install the dagster-dg package into it:

mkdir my-project && cd my-project

python -m venv .venv

source .venv/bin/activate

pip install dagster-dg

The dg executable is now available via the activated virtual environment. Let's run dg init . to scaffold a new project. The . tells dg to scaffold the project in the current directory.

dg init .

Finally, install the newly created project package into the virtual environment as an editable install:

pip install -e .

Project structure

The dg init command creates a directory with a standard Python package structure with some additions:

uv

tree

.
├── pyproject.toml
├── src
│   └── jaffle_platform
│       ├── __init__.py
│       ├── definitions.py
│       ├── defs
│       │   └── __init__.py
│       └── lib
│           └── __init__.py
├── tests
│   └── __init__.py
└── uv.lock

6 directories, 7 files

pip

tree

.
├── pyproject.toml
├── src
│   └── jaffle_platform
│       ├── __init__.py
│       ├── definitions.py
│       ├── defs
│       │   └── __init__.py
│       └── lib
│           └── __init__.py
└── tests
    └── __init__.py

6 directories, 6 files

• The Python package my_project lives in src/my_project and contains the deployable code that defines your Dagster pipelines.
• my_project/defs will contain your Dagster definitions.
• my_project/lib is where you will define custom component types, and optionally other code you wish to share across Dagster definitions.
• my_project/definitions.py is the entry point that Dagster will load when deploying your code location. It is configured to load all definitions from my_project/defs. You should not need to modify this file.
• tests is a separate Python package defined at the top level (outside src). It should contain tests for the my_project package.
• pyproject.toml is a standard Python package configuration file. In addition to the regular Python package metadata, it contains a tool.dg section for dg-specific settings.
• uv.lock is the lockfile for the Python package manager uv. dg projects use uv by default. For more information, see uv integration.