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-module.toml) - A package of code.
• Workspace (dagger.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 install github.com/foo/bar adds a module to dagger.toml. Same functionality, simpler model.

What happened to blueprints?

They're now workspace modules marked as entrypoint = true in dagger.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 legacy dagger.json is deprecated. Workspace module settings now use settings in dagger.toml:

[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 setup

dagger setup prompts before each step. Its migration step converts workspace fields from your legacy dagger.json into dagger.toml, and converts module-shaped dagger.json files to dagger-module.toml in place — module files are never moved, and only the root dagger.json plus the local dependencies and toolchains it references are touched. If anything needs manual attention, it creates .dagger/migration-report.md with instructions.

A few migration behaviors worth knowing:

• If your repo is a dagger module — the root dagger.json describes a module whose source lives at the repo root — migration converts the config in place and writes a minimal dagger.toml that only pins the module's SDK. The module is not installed into the workspace, so load it explicitly: dagger -m . call --help.
• Running dagger setup from a module subdirectory — a dagger.json below the repository root — migrates just that module: dagger.json becomes dagger-module.toml in place (along with any local dependencies it references) and no workspace is created. Module recommendations are skipped in this case.
• Nested dagger.toml files are never created. If a subdirectory dagger.json lists toolchains, migration installs them into a dagger.toml at the repository root, with local source paths rebased; the module itself is not installed into that workspace. A subdirectory dagger.json with a blueprint is left as legacy with a warning.
• Modules now commit their generated code (e.g. dagger.gen.go) instead of regenerating it at runtime. Migration removes the legacy .gitignore rules that ignored those files — after migrating, run dagger generate and commit the output.
• Applying a migration ends the setup run; run dagger setup again to see module recommendations for the migrated workspace.

What happened to module-management commands?

Workspace modules are managed with the top-level commands. Use dagger search to find modules, dagger install <module> and dagger uninstall <module> to update dagger.toml.

Module source metadata moves to dagger-module.toml. Create or edit that file directly when authoring a module or adding code dependencies.

Quick reference

Before	Now
dagger -m <ref> (with toolchains)	dagger -W <ref>
dagger toolchain install <module>	dagger install <module>
dagger install <dep> (module code dependency)	Add the dependency to [[dependencies]] in dagger-module.toml
toolchains array in dagger.json	[modules.*] in dagger.toml
blueprint in dagger.json	entrypoint = true in dagger.toml
customizations in dagger.json	[modules.*.settings] in dagger.toml
.env for constructor defaults	[modules.*.settings] in dagger.toml