Container

The Container type represents the state of an OCI-compatible container. This Container object is not merely a string referencing an image on a remote registry. It is the actual state of a container, managed by the Dagger Engine, and passed to a Dagger Function's code as if it were just another variable.

Common operations

Some of the common operations used on the Container type include:

Field	Description
from	Initializes the container from a specified base image
asService	Turns the container into a Service
asTarball	Returns a serialized tarball of the container as a File
export / import	Writes / reads the container as an OCI tarball to / from a file path on the host
publish	Publishes the container image to a registry
stdout / stderr	Returns the output / error stream of the last executed command
withDirectory / withMountedDirectory	Returns the container plus a directory copied / mounted at the given path
withEntrypoint	Returns the container with a custom entrypoint command
withExec	Returns the container after executing a command inside it
withFile / withMountedFile	Returns the container plus a file copied / mounted at the given path
withMountedCache	Returns the container plus a cache volume mounted at the given path
withRegistryAuth	Returns the container with registry authentication configured
withWorkdir	Returns the container configured with a specific working directory
withServiceBinding	Returns the container with runtime dependency on another Service
terminal	Opens an interactive terminal for this container

Default addresses

It is possible to assign a default address for a Container argument in a Dagger Function. Dagger will automatically use this default address to pull the container image when no value is specified for the argument.

tip

Default addresses are only available for Container arguments. They are commonly used to provide a sensible default base image for build or test operations. When a value is explicitly passed for the argument, it always overrides the default address.

Here's an example:

Go

The default address is set by adding a defaultAddress pragma on the corresponding Dagger Function ctr argument.

package main

import (
	"context"
	"dagger/my-module/internal/dagger"
)

type MyModule struct{}

func (m *MyModule) Version(
	ctx context.Context,
	// +defaultAddress="alpine:latest"
	ctr *dagger.Container,
) (string, error) {
	return ctr.WithExec([]string{"cat", "/etc/alpine-release"}).Stdout(ctx)
}

Python

The default address is set by adding a DefaultAddress annotation on the corresponding Dagger Function ctr argument.

from typing import Annotated

import dagger
from dagger import DefaultAddress, function, object_type


@object_type
class MyModule:
    @function
    async def version(
        self,
        ctr: Annotated[dagger.Container, DefaultAddress("alpine:latest")],
    ) -> str:
        return await ctr.with_exec(["cat", "/etc/alpine-release"]).stdout()

TypeScript

The default address is set by adding an @argument decorator with a defaultAddress parameter on the corresponding Dagger Function ctr argument.

import { Container, object, func, argument } from "@dagger.io/dagger"

@object()
class MyModule {
  @func()
  async version(
    @argument({ defaultAddress: "alpine:latest" })
    ctr: Container,
  ): Promise<string> {
    return ctr.withExec(["cat", "/etc/alpine-release"]).stdout()
  }
}

PHP

The default address is set by adding a #[DefaultAddress] Attribute on the corresponding Dagger Function ctr argument.

<?php

declare(strict_types=1);

namespace DaggerModule;

use Dagger\Attribute\DaggerFunction;
use Dagger\Attribute\DaggerObject;
use Dagger\Attribute\DefaultAddress;
use Dagger\Container;

#[DaggerObject]
class MyModule
{
    #[DaggerFunction]
    public function version(
        #[DefaultAddress('alpine:latest')]
        Container $ctr,
    ): string {
        return $ctr->withExec(['cat', '/etc/alpine-release'])->stdout();
    }
}

The default address can be any valid container image reference, such as:

• alpine:latest - Docker Hub image with tag
• alpine:3.19 - Docker Hub image with specific version
• ghcr.io/owner/image:tag - GitHub Container Registry image
• gcr.io/project/image:tag - Google Container Registry image