Projects

Dagster follows standard Python conventions, and most work in Dagster begins by creating a Python package called a project. This is where you’ll define your pipelines, as well as any dependencies within your project.

To streamline project creation, Dagster provides the create-dagster CLI, which quickly scaffolds a Python package containing a Dagster Definitions object. When you scaffold the project, the Definitions object will not contain any other Dagster objects.

1. Scaffold a Dagster project

uv

1. Open your terminal and scaffold a new Dagster project:

   uvx create-dagster@latest project dagster-tutorial

2. Respond y to the prompt to run uv sync after scaffolding:

   

3. Change to the dagster-tutorial directory:

   cd dagster-tutorial

4. Activate the virtual environment:

   MacOS/Unix

   source .venv/bin/activate

   Windows

   .venv\Scripts\activate

pip

1. Open your terminal and scaffold a new Dagster project:

   create-dagster project dagster-tutorial

2. Change to the dagster-tutorial directory:

   cd dagster-tutorial

3. Create and activate a virtual environment:

   MacOS/Unix

   python -m venv .venv

   source .venv/bin/activate

   Windows

   python -m venv .venv

   .venv\Scripts\activate

4. Install your project as an editable package:

   pip install --editable .

Dagster project structure

Your new Dagster project should have the following structure:

uv

 .
 ├── pyproject.toml
 ├── README.md
 ├── src
 │   └── dagster_tutorial
 │       ├── __init__.py
 │       ├── definitions.py
 │       └── defs
 │           └── __init__.py
 ├── tests
 │   └── __init__.py
 └── uv.lock

pip

 .
 ├── pyproject.toml
 ├── README.md
 ├── src
 │   └── dagster_tutorial
 │       ├── __init__.py
 │       ├── definitions.py
 │       └── defs
 │           └── __init__.py
 └── tests
     └── __init__.py

• pyproject.toml defines the metadata and Python dependencies for the project.
• The src directory will contain code for the project.
• src/definitions.py defines the main Dagster project object.
• The tests directory will contain tests for the project.

2. Start the Dagster webserver

When you initialize a project with create-dagster, the dagster-dg-cli library is installed. This provides the dg CLI, which includes several commands to help you structure and navigate Dagster projects. For more details, see the dg CLI documentation.

Use the following command to launch the Dagster UI locally:

dg dev

Then, in a browser, navigate to http://127.0.0.1:3000.

At this point, your project will be empty, but you’ll continue adding to it throughout the tutorial.

tip

As you develop with Dagster, it’s often useful to periodically run dg dev to view your project.