Local Defaults (.env)

Dagger supports persisting default arguments in a local .env file. This avoids typing the same CLI arguments on every call — set them once, and they're applied automatically.

How it works

1. Create a .env file in or above your module directory.
2. Add variables using the naming convention described below.
3. Call your module — omitted arguments are filled from .env.
4. Explicit CLI arguments always take priority over .env values.

Variable naming convention

Inside the module directory

Place an .env file next to your dagger.json. Variables map directly to argument names without any module-name prefix:

• Constructor arguments: ARGNAME=value
• Function arguments: FUNCTIONNAME_ARGNAME=value

# Constructor arg --registry
REGISTRY=ghcr.io/myorg

# Argument --tag on function "push"
PUSH_TAG=latest

Outside the module directory

Place an .env file in a parent directory (Dagger searches upward automatically). Variables must be prefixed with the module name:

• Constructor arguments: MODULENAME_ARGNAME=value
• Function arguments: MODULENAME_FUNCTIONNAME_ARGNAME=value

# Constructor arg --registry on module "deploy"
DEPLOY_REGISTRY=ghcr.io/myorg

# Argument --tag on function "push" of module "deploy"
DEPLOY_PUSH_TAG=latest

:::note All variable name matching is case-insensitive. TOKEN, token, and Token all match an argument named token. :::

Example

Consider a module called deploy with a constructor taking --registry and a function push taking --tag.

Without .env, you must pass every argument each time:

dagger call --registry=ghcr.io/myorg push --tag=latest

With an inner .env file (next to dagger.json):

REGISTRY=ghcr.io/myorg
PUSH_TAG=latest

# Arguments are filled in automatically
dagger call push

With an outer .env file (in a parent directory):

DEPLOY_REGISTRY=ghcr.io/myorg
DEPLOY_PUSH_TAG=latest

# Same result — module name prefix is stripped automatically
dagger call push

Supported values

Values use the same format as CLI arguments: strings, integers, booleans, JSON arrays, local and remote paths for Directory/File types, secret provider URIs (env://, file://, op://, etc.), and more. See the Arguments reference for the full list.

Priority

When the same argument is defined in multiple places, the highest-priority source wins:

1. Explicit CLI arguments (highest priority)
2. .env file defaults
3. Module-defined defaults in source code (lowest priority)

Tips

:::tip

• Add .env to .gitignore if it contains secrets or personal preferences.
• Inner .env files let you skip the module name prefix for shorter variable names.
• Variables support shell-style expansion (${VAR} syntax), with fallback to host environment variables. :::

Learn more

• Arguments — full argument types reference
• Secrets Integration — secret provider URIs you can use in .env values
• Constructors — module constructor arguments