Upgrading to Workspaces

:::note If you're new to Dagger, you can skip this page. It's for existing users encountering changes. :::

What changed

In previous versions, dagger.json served double duty — it defined both your module's code and your project's configuration (toolchains, blueprints, customizations). These are now separate:

• Module (dagger.json) — A package of code. That's it.
• Workspace (.dagger/config.toml) — Your project's Dagger configuration: which modules to use, how to configure them.

What happened to toolchains?

They're now just modules installed in your workspace. dagger mod install github.com/foo/bar adds a module to .dagger/config.toml. Same functionality, simpler model.

What happened to blueprints?

They're now workspace modules marked as entrypoint = true in .dagger/config.toml. The concept of "blueprint" as a distinct thing is gone — it's just a configuration flag.

What happened to customizations?

The customizations array in dagger.json is deprecated. Module configuration now uses settings in your workspace config:

[modules.go]
source = "github.com/dagger/go"

[modules.go.settings]
goVersion = "1.22"

Do I need to migrate right now?

No. Backwards compatibility will infer a workspace from your existing dagger.json. You'll see a warning, but everything will continue to work. When you're ready:

dagger migrate

This automatically converts your dagger.json workspace fields into .dagger/config.toml. If anything needs manual attention, it creates .dagger/migration-report.md with instructions.

What happened to module-management commands?

Workspace modules are managed with module commands. Use dagger mod recommend to detect modules for a project, dagger mod install <module> and dagger mod uninstall <module> to update .dagger/config.toml, and dagger mod list and dagger mod search to inspect available modules.

Module source metadata stays in dagger.json. Create or edit that file directly when authoring a module or adding code dependencies.

Quick reference