Client

Automatically generated client from Dagger API.

class dagger.Address(ctx: Context)

Bases: Type

A standardized address to load containers, directories, secrets, and other object types. Address format depends on the type, and is validated at type selection.

container() → Container

Load a container from the address.

directory(*, exclude: list[str] | None = None, include: list[str] | None = None, gitignore: bool | None = False, no_cache: bool | None = False) → Directory

Load a directory from the address.

file(*, exclude: list[str] | None = None, include: list[str] | None = None, gitignore: bool | None = False, no_cache: bool | None = False) → File

Load a file from the address.

git_ref() → GitRef

Load a git ref (branch, tag or commit) from the address.

git_repository() → GitRepository

Load a git repository from the address.

async id() → str

A unique identifier for this Address.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

secret() → Secret

Load a secret from the address.

service() → Service

Load a service from the address.

socket() → Socket

Load a local socket from the address.

async value() → str

The address value

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.AddressID

Bases: Scalar

A unique identifier for an object.

class dagger.Binding(ctx: Context)

Bases: Type

as_address() → Address

Retrieve the binding value, as type Address

as_cache_volume() → CacheVolume

Retrieve the binding value, as type CacheVolume

as_changeset() → Changeset

Retrieve the binding value, as type Changeset

as_check() → Check

Retrieve the binding value, as type Check

as_check_group() → CheckGroup

Retrieve the binding value, as type CheckGroup

as_cloud() → Cloud

Retrieve the binding value, as type Cloud

as_container() → Container

Retrieve the binding value, as type Container

as_diff_stat() → DiffStat

Retrieve the binding value, as type DiffStat

as_directory() → Directory

Retrieve the binding value, as type Directory

as_env() → Env

Retrieve the binding value, as type Env

as_env_file() → EnvFile

Retrieve the binding value, as type EnvFile

as_file() → File

Retrieve the binding value, as type File

as_generator() → Generator

Retrieve the binding value, as type Generator

as_generator_group() → GeneratorGroup

Retrieve the binding value, as type GeneratorGroup

as_git_ref() → GitRef

Retrieve the binding value, as type GitRef

as_git_repository() → GitRepository

Retrieve the binding value, as type GitRepository

as_http_state() → HTTPState

Retrieve the binding value, as type HTTPState

as_json_value() → JSONValue

Retrieve the binding value, as type JSONValue

as_module() → Module

Retrieve the binding value, as type Module

as_module_config_client() → ModuleConfigClient

Retrieve the binding value, as type ModuleConfigClient

as_module_source() → ModuleSource

Retrieve the binding value, as type ModuleSource

as_search_result() → SearchResult

Retrieve the binding value, as type SearchResult

as_search_submatch() → SearchSubmatch

Retrieve the binding value, as type SearchSubmatch

as_secret() → Secret

Retrieve the binding value, as type Secret

as_service() → Service

Retrieve the binding value, as type Service

as_socket() → Socket

Retrieve the binding value, as type Socket

as_stat() → Stat

Retrieve the binding value, as type Stat

async as_string() → str | None

Returns the binding’s string value

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

as_up() → Up

Retrieve the binding value, as type Up

as_up_group() → UpGroup

Retrieve the binding value, as type UpGroup

as_workspace() → Workspace

Retrieve the binding value, as type Workspace

async digest() → str

Returns the digest of the binding value

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Binding.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async is_null() → bool

Returns true if the binding is null

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

Returns the binding name

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async type_name() → str

Returns the binding type

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.BindingID

Bases: Scalar

A unique identifier for an object.

class dagger.BuildArg(name: str, value: str)

Bases: Input

Key value object that represents a build argument.

name: str

value: str

class dagger.CacheSharingMode(*values)

Bases: Enum

Sharing mode of the cache volume.

LOCKED = 'LOCKED'

PRIVATE = 'PRIVATE'

SHARED = 'SHARED'

class dagger.CacheVolume(ctx: Context)

Bases: Type

A directory whose contents persist across runs.

async id() → str

A unique identifier for this CacheVolume.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.CacheVolumeID

Bases: Scalar

A unique identifier for an object.

class dagger.Changeset(ctx: Context)

Bases: Type

A comparison between two directories representing changes that can be applied.

async added_paths() → list[str]

Files and directories that were added in the newer directory.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

after() → Directory

The newer/upper snapshot.

as_patch() → File

Return a Git-compatible patch of the changes

before() → Directory

The older/lower snapshot to compare against.

async diff_stats() → list[DiffStat]

Structured per-path diff statistics (kind and line counts) for this changeset.

async export(path: str) → str

Applies the diff represented by this changeset to a path on the host.

Parameters:

path – Location of the copied directory (e.g., “logs/”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Changeset.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async is_empty() → bool

Returns true if the changeset is empty (i.e. there are no changes).

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

layer() → Directory

Return a snapshot containing only the created and modified files

async modified_paths() → list[str]

Files and directories that existed before and were updated in the newer directory.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async removed_paths() → list[str]

Files and directories that were removed. Directories are indicated by a trailing slash, and their child paths are not included.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async sync() → Self

Force evaluation in the engine.

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_(cb: Callable[[Changeset], Changeset]) → Changeset

Call the provided callable with current Changeset.

This is useful for reusability and readability by not breaking the calling chain.

with_changeset(changes: Self, *, on_conflict: ChangesetMergeConflict | None = ChangesetMergeConflict.FAIL) → Self

Add changes to an existing changeset

By default the operation will fail in case of conflicts, for instance a file modified in both changesets. The behavior can be adjusted using onConflict argument

Parameters:

• changes – Changes to merge into the actual changeset

• on_conflict – What to do on a merge conflict

with_changesets(changes: list[Changeset], *, on_conflict: ChangesetsMergeConflict | None = ChangesetsMergeConflict.FAIL) → Self

Add changes from multiple changesets using git octopus merge strategy

This is more efficient than chaining multiple withChangeset calls when merging many changesets.

Only FAIL and FAIL_EARLY conflict strategies are supported (octopus merge cannot use -X ours/theirs).

Parameters:

• changes – List of changesets to merge into the actual changeset

• on_conflict – What to do on a merge conflict

class dagger.ChangesetID

Bases: Scalar

A unique identifier for an object.

class dagger.ChangesetMergeConflict(*values)

Bases: Enum

Strategy to use when merging changesets with conflicting changes.

FAIL = 'FAIL'

FAIL_EARLY = 'FAIL_EARLY'

LEAVE_CONFLICT_MARKERS = 'LEAVE_CONFLICT_MARKERS'

PREFER_OURS = 'PREFER_OURS'

PREFER_THEIRS = 'PREFER_THEIRS'

class dagger.ChangesetsMergeConflict(*values)

Bases: Enum

Strategy to use when merging multiple changesets with git octopus merge.

FAIL = 'FAIL'

FAIL_EARLY = 'FAIL_EARLY'

class dagger.Check(ctx: Context)

Bases: Type

async check_type() → str

The type of check: ‘check’ for annotated checks, ‘generate’ for generate-as-checks

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async completed() → bool

Whether the check completed

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async description() → str

The description of the check

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

error() → Error

If the check failed, this is the error

async id() → str

A unique identifier for this Check.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

Return the fully qualified name of the check

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

original_module() → Module

The original module in which the check has been defined

async passed() → bool

Whether the check passed

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async path() → list[str]

The path of the check within its module

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async result_emoji() → str

An emoji representing the result of the check

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

run() → Self

Execute the check

with_(cb: Callable[[Check], Check]) → Check

Call the provided callable with current Check.

This is useful for reusability and readability by not breaking the calling chain.

class dagger.CheckGroup(ctx: Context)

Bases: Type

async id() → str

A unique identifier for this CheckGroup.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async list_() → list[Check]

Return a list of individual checks and their details

report() → File

Generate a markdown report

run(*, fail_fast: bool | None = None) → Self

Execute all selected checks

Parameters:

fail_fast – If true, stop running checks as soon as any check fails.

with_(cb: Callable[[CheckGroup], CheckGroup]) → CheckGroup

Call the provided callable with current CheckGroup.

This is useful for reusability and readability by not breaking the calling chain.

class dagger.CheckGroupID

Bases: Scalar

A unique identifier for an object.

class dagger.CheckID

Bases: Scalar

A unique identifier for an object.

class dagger.Client(ctx: Context | None = None)

Bases: Query

The Dagger client.

Inherits all Query API methods and adds connection management.

class dagger.ClientFilesyncMirror(ctx: Context)

Bases: Type

An internal persistent filesync mirror.

async id() → str

A unique identifier for this ClientFilesyncMirror.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.ClientFilesyncMirrorID

Bases: Scalar

A unique identifier for an object.

class dagger.Cloud(ctx: Context)

Bases: Type

Dagger Cloud configuration and state

async id() → str

A unique identifier for this Cloud.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async trace_url() → str

The trace URL for the current session

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.CloudID

Bases: Scalar

A unique identifier for an object.

class dagger.Container(ctx: Context)

Bases: Type

An OCI-compatible container, also known as a Docker container.

as_service(*, args: list[str] | None = None, use_entrypoint: bool | None = False, experimental_privileged_nesting: bool | None = False, insecure_root_capabilities: bool | None = False, expand: bool | None = False, no_init: bool | None = False) → Service

Turn the container into a Service.

Be sure to set any exposed ports before this conversion.

Parameters:

• args – Command to run instead of the container’s default command (e.g., [“go”, “run”, “main.go”]). If empty, the container’s default command is used.

• use_entrypoint – If the container has an entrypoint, prepend it to the args.

• experimental_privileged_nesting – Provides Dagger access to the executed command.

• insecure_root_capabilities – Execute the command with all root capabilities. This is similar to running a command with “sudo” or executing “docker run” with the ” –privileged” flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.

• expand – Replace “${VAR}” or “$VAR” in the args according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

• no_init – If set, skip the automatic init process injected into containers by default. This should only be used if the user requires that their exec process be the pid 1 process in the container. Otherwise it may result in unexpected behavior.

as_tarball(*, platform_variants: list[Container] | None = None, forced_compression: ImageLayerCompression | None = None, media_types: ImageMediaTypes | None = ImageMediaTypes.OCIMediaTypes) → File

Package the container state as an OCI image, and return it as a tar archive

Parameters:

• platform_variants – Identifiers for other platform specific containers. Used for multi-platform images.

• forced_compression – Force each layer of the image to use the specified compression algorithm. If this is unset, then if a layer already has a compressed blob in the engine’s cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine’s cache, then it will be compressed using Gzip.

• media_types – Use the specified media types for the image’s layers. Defaults to OCI, which is largely compatible with most recent container runtimes, but Docker may be needed for older runtimes without OCI support.

async combined_output() → str

The combined buffered standard output and standard error stream of the last executed command

Returns an error if no command was executed

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async default_args() → list[str]

Return the container’s default arguments.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

directory(path: str, *, expand: bool | None = False) → Directory

Retrieve a directory from the container’s root filesystem

Mounts are included.

Parameters:

• path – The path of the directory to retrieve (e.g., “./src”).

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

docker_healthcheck() → HealthcheckConfig

Retrieves this container’s configured docker healthcheck.

async entrypoint() → list[str]

Return the container’s OCI entrypoint.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async env_variable(name: str) → str | None

Retrieves the value of the specified persistent environment variable.

Parameters:

name – The name of the environment variable to retrieve (e.g., “PATH”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async env_variables() → list[EnvVariable]

Retrieves the list of persistent environment variables configured on the container.

async exists(path: str, *, expected_type: ExistsType | None = None, do_not_follow_symlinks: bool | None = False) → bool

check if a file or directory exists

Parameters:

• path – Path to check (e.g., “/file.txt”).

• expected_type – If specified, also validate the type of file (e.g. “REGULAR_TYPE”, “DIRECTORY_TYPE”, or “SYMLINK_TYPE”).

• do_not_follow_symlinks – If specified, do not follow symlinks.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async exit_code() → int

The exit code of the last executed command

Returns an error if no command was executed

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

experimental_with_all_gp_us() → Self

EXPERIMENTAL API! Subject to change/removal at any time.

Configures all available GPUs on the host to be accessible to this container.

This currently works for Nvidia devices only.

experimental_with_gpu(devices: list[str]) → Self

EXPERIMENTAL API! Subject to change/removal at any time.

Configures the provided list of devices to be accessible to this container.

This currently works for Nvidia devices only.

Parameters:

devices – List of devices to be accessible to this container.

async export(path: str, *, platform_variants: list[Container] | None = None, forced_compression: ImageLayerCompression | None = None, media_types: ImageMediaTypes | None = ImageMediaTypes.OCIMediaTypes, expand: bool | None = False) → str

Writes the container as an OCI tarball to the destination file path on the host.

It can also export platform variants.

Parameters:

• path – Host’s destination path (e.g., “./tarball”). Path can be relative to the engine’s workdir or absolute.

• platform_variants – Identifiers for other platform specific containers. Used for multi-platform image.

• forced_compression – Force each layer of the exported image to use the specified compression algorithm. If this is unset, then if a layer already has a compressed blob in the engine’s cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine’s cache, then it will be compressed using Gzip.

• media_types – Use the specified media types for the exported image’s layers. Defaults to OCI, which is largely compatible with most recent container runtimes, but Docker may be needed for older runtimes without OCI support.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async export_image(name: str, *, platform_variants: list[Container] | None = None, forced_compression: ImageLayerCompression | None = None, media_types: ImageMediaTypes | None = ImageMediaTypes.OCIMediaTypes) → Void

Exports the container as an image to the host’s container image store.

Parameters:

• name – Name of image to export to in the host’s store

• platform_variants – Identifiers for other platform specific containers. Used for multi-platform image.

• forced_compression – Force each layer of the exported image to use the specified compression algorithm. If this is unset, then if a layer already has a compressed blob in the engine’s cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine’s cache, then it will be compressed using Gzip.

• media_types – Use the specified media types for the exported image’s layers. Defaults to OCI, which is largely compatible with most recent container runtimes, but Docker may be needed for older runtimes without OCI support.

Returns:

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.

Return type:

Void

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async exposed_ports() → list[Port]

Retrieves the list of exposed ports.

This includes ports already exposed by the image, even if not explicitly added with dagger.

file(path: str, *, expand: bool | None = False) → File

Retrieves a file at the given path.

Mounts are included.

Parameters:

• path – The path of the file to retrieve (e.g., “./README.md”).

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo.txt”).

from_(address: str) → Self

Download a container image, and apply it to the container state. All previous state will be lost.

Parameters:

address – Address of the container image to download, in standard OCI ref format. Example:”registry.dagger.io/engine:latest”

async id() → str

A unique identifier for this Container.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async image_ref() → str

The unique image reference which can only be retrieved immediately after the ‘Container.From’ call.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

import_(source: File, *, tag: str | None = '') → Self

Reads the container from an OCI tarball.

Parameters:

• source – File to read the container from.

• tag – Identifies the tag to import from the archive, if the archive bundles multiple tags.

async label(name: str) → str | None

Retrieves the value of the specified label.

Parameters:

name – The name of the label (e.g., “org.opencontainers.artifact.created”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async labels() → list[Label]

Retrieves the list of labels passed to container.

async mounts() → list[str]

Retrieves the list of paths where a directory is mounted.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async platform() → Platform

The platform this container executes and publishes as.

Returns:

The platform config OS and architecture in a Container. The format is [os]/[platform]/[version] (e.g., “darwin/arm64/v7”, “windows/amd64”, “linux/arm64”).

Return type:

Platform

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async publish(address: str, *, platform_variants: list[Container] | None = None, forced_compression: ImageLayerCompression | None = None, media_types: ImageMediaTypes | None = ImageMediaTypes.OCIMediaTypes) → str

Package the container state as an OCI image, and publish it to a registry

Returns the fully qualified address of the published image, with digest

Parameters:

• address – The OCI address to publish to Same format as “docker push”. Example: “registry.example.com/user/repo:tag”

• platform_variants – Identifiers for other platform specific containers. Used for multi-platform image.

• forced_compression – Force each layer of the published image to use the specified compression algorithm. If this is unset, then if a layer already has a compressed blob in the engine’s cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine’s cache, then it will be compressed using Gzip.

• media_types – Use the specified media types for the published image’s layers. Defaults to “OCI”, which is compatible with most recent registries, but “Docker” may be needed for older registries without OCI support.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

rootfs() → Directory

Return a snapshot of the container’s root filesystem. The snapshot can be modified then written back using withRootfs. Use that method for filesystem modifications.

stat(path: str, *, do_not_follow_symlinks: bool | None = False) → Stat

Return file status

Parameters:

• path – Path to check (e.g., “/file.txt”).

• do_not_follow_symlinks – If specified, do not follow symlinks.

async stderr() → str

The buffered standard error stream of the last executed command

Returns an error if no command was executed

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async stdout() → str

The buffered standard output stream of the last executed command

Returns an error if no command was executed

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async sync() → Self

Forces evaluation of the pipeline in the engine.

It doesn’t run the default command if no exec has been set.

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

terminal(*, cmd: list[str] | None = None, experimental_privileged_nesting: bool | None = False, insecure_root_capabilities: bool | None = False) → Self

Opens an interactive terminal for this container using its configured default terminal command if not overridden by args (or sh as a fallback default).

Parameters:

• cmd – If set, override the container’s default terminal command and invoke these command arguments instead.

• experimental_privileged_nesting – Provides Dagger access to the executed command.

• insecure_root_capabilities – Execute the command with all root capabilities. This is similar to running a command with “sudo” or executing “docker run” with the ” –privileged” flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.

async up(*, random: bool | None = False, ports: list[PortForward] | None = None, args: list[str] | None = None, use_entrypoint: bool | None = False, experimental_privileged_nesting: bool | None = False, insecure_root_capabilities: bool | None = False, expand: bool | None = False, no_init: bool | None = False) → Void | None

Starts a Service and creates a tunnel that forwards traffic from the caller’s network to that service.

Be sure to set any exposed ports before calling this api.

Parameters:

• random – Bind each tunnel port to a random port on the host.

• ports – List of frontend/backend port mappings to forward. Frontend is the port accepting traffic on the host, backend is the service port.

• args – Command to run instead of the container’s default command (e.g., [“go”, “run”, “main.go”]). If empty, the container’s default command is used.

• use_entrypoint – If the container has an entrypoint, prepend it to the args.

• experimental_privileged_nesting – Provides Dagger access to the executed command.

• insecure_root_capabilities – Execute the command with all root capabilities. This is similar to running a command with “sudo” or executing “docker run” with the ” –privileged” flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.

• expand – Replace “${VAR}” or “$VAR” in the args according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

• no_init – If set, skip the automatic init process injected into containers by default. This should only be used if the user requires that their exec process be the pid 1 process in the container. Otherwise it may result in unexpected behavior.

Returns:

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.

Return type:

Void | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async user() → str

Retrieves the user to be set for all commands.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_(cb: Callable[[Container], Container]) → Container

Call the provided callable with current Container.

This is useful for reusability and readability by not breaking the calling chain.

with_annotation(name: str, value: str) → Self

Retrieves this container plus the given OCI annotation.

Parameters:

• name – The name of the annotation.

• value – The value of the annotation.

with_default_args(args: list[str]) → Self

Configures default arguments for future commands. Like CMD in Dockerfile.

Parameters:

args – Arguments to prepend to future executions (e.g., [“-v”, “–no- cache”]).

with_default_terminal_cmd(args: list[str], *, experimental_privileged_nesting: bool | None = False, insecure_root_capabilities: bool | None = False) → Self

Set the default command to invoke for the container’s terminal API.

Parameters:

• args – The args of the command.

• experimental_privileged_nesting – Provides Dagger access to the executed command.

• insecure_root_capabilities – Execute the command with all root capabilities. This is similar to running a command with “sudo” or executing “docker run” with the ” –privileged” flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.

with_directory(path: str, source: Directory, *, exclude: list[str] | None = None, include: list[str] | None = None, gitignore: bool | None = False, owner: str | None = '', expand: bool | None = False, permissions: int | None = None) → Self

Return a new container snapshot, with a directory added to its filesystem

Parameters:

• path – Location of the written directory (e.g., “/tmp/directory”).

• source – Identifier of the directory to write

• exclude – Patterns to exclude in the written directory (e.g. [“node_modules/**”, “.gitignore”, “.git/”]).

• include – Patterns to include in the written directory (e.g. [”*.go”, “go.mod”, “go.sum”]).

• gitignore – Apply .gitignore rules when writing the directory.

• owner – A user:group to set for the directory and its contents. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

• permissions

with_docker_healthcheck(args: list[str], *, shell: bool | None = None, interval: str | None = None, timeout: str | None = None, start_period: str | None = None, start_interval: str | None = None, retries: int | None = None) → Self

Retrieves this container with the specificed docker healtcheck command set.

Parameters:

• args – Healthcheck command to execute. Example: [“go”, “run”, “main.go”].

• shell – When true, command must be a single element, which is run using the container’s shell

• interval – Interval between running healthcheck. Example: “30s”

• timeout – Healthcheck timeout. Example: “3s”

• start_period – StartPeriod allows for failures during this initial startup period which do not count towards maximum number of retries. Example: “0s”

• start_interval – StartInterval configures the duration between checks during the startup phase. Example: “5s”

• retries – The maximum number of consecutive failures before the container is marked as unhealthy. Example: “3”

with_entrypoint(args: list[str], *, keep_default_args: bool | None = False) → Self

Set an OCI-style entrypoint. It will be included in the container’s OCI configuration. Note, withExec ignores the entrypoint by default.

Parameters:

• args – Arguments of the entrypoint. Example: [“go”, “run”].

• keep_default_args – Don’t reset the default arguments when setting the entrypoint. By default it is reset, since entrypoint and default args are often tightly coupled.

with_env_file_variables(source: EnvFile) → Self

Export environment variables from an env-file to the container.

Parameters:

source – Identifier of the envfile

with_env_variable(name: str, value: str, *, expand: bool | None = False) → Self

Set a new environment variable in the container.

Parameters:

• name – Name of the environment variable (e.g., “HOST”).

• value – Value of the environment variable. (e.g., “localhost”).

• expand – Replace “${VAR}” or “$VAR” in the value according to the current environment variables defined in the container (e.g. “/opt/bin:$PATH”).

with_error(err: str) → Self

Raise an error.

Parameters:

err – Message of the error to raise. If empty, the error will be ignored.

with_exec(args: list[str], *, use_entrypoint: bool | None = False, stdin: str | None = '', redirect_stdin: str | None = '', redirect_stdout: str | None = '', redirect_stderr: str | None = '', expect: ReturnType | None = ReturnType.SUCCESS, experimental_privileged_nesting: bool | None = False, insecure_root_capabilities: bool | None = False, expand: bool | None = False, no_init: bool | None = False) → Self

Execute a command in the container, and return a new snapshot of the container state after execution.

Parameters:

• args – Command to execute. Must be valid exec() arguments, not a shell command. Example: [“go”, “run”, “main.go”]. To run a shell command, execute the shell and pass the shell command as argument. Example: [“sh”, “-c”, “ls -l | grep foo”] Defaults to the container’s default arguments (see “defaultArgs” and “withDefaultArgs”).

• use_entrypoint – Apply the OCI entrypoint, if present, by prepending it to the args. Ignored by default.

• stdin – Content to write to the command’s standard input. Example: “Hello world”)

• redirect_stdin – Redirect the command’s standard input from a file in the container. Example: “./stdin.txt”

• redirect_stdout – Redirect the command’s standard output to a file in the container. Example: “./stdout.txt”

• redirect_stderr – Redirect the command’s standard error to a file in the container. Example: “./stderr.txt”

• expect – Exit codes this command is allowed to exit with without error

• experimental_privileged_nesting – Provides Dagger access to the executed command.

• insecure_root_capabilities – Execute the command with all root capabilities. Like –privileged in Docker DANGER: this grants the command full access to the host system. Only use when 1) you trust the command being executed and 2) you specifically need this level of access.

• expand – Replace “${VAR}” or “$VAR” in the args according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

• no_init – Skip the automatic init process injected into containers by default. Only use this if you specifically need the command to be pid 1 in the container. Otherwise it may result in unexpected behavior. If you’re not sure, you don’t need this.

with_exposed_port(port: int, *, protocol: NetworkProtocol | None = NetworkProtocol.TCP, description: str | None = None, experimental_skip_healthcheck: bool | None = False) → Self

Expose a network port. Like EXPOSE in Dockerfile (but with healthcheck support)

Exposed ports serve two purposes:

• For health checks and introspection, when running services

• For setting the EXPOSE OCI field when publishing the container

Parameters:

• port – Port number to expose. Example: 8080

• protocol – Network protocol. Example: “tcp”

• description – Port description. Example: “payment API endpoint”

• experimental_skip_healthcheck – Skip the health check when run as a service.

with_file(path: str, source: File, *, permissions: int | None = None, owner: str | None = '', expand: bool | None = False) → Self

Return a container snapshot with a file added

Parameters:

• path – Path of the new file. Example: “/path/to/new-file.txt”

• source – File to add

• permissions – Permissions of the new file. Example: 0600

• owner – A user:group to set for the file. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo.txt”).

with_files(path: str, sources: list[File], *, permissions: int | None = None, owner: str | None = '', expand: bool | None = False) → Self

Retrieves this container plus the contents of the given files copied to the given path.

Parameters:

• path – Location where copied files should be placed (e.g., “/src”).

• sources – Identifiers of the files to copy.

• permissions – Permission given to the copied files (e.g., 0600).

• owner – A user:group to set for the files. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo.txt”).

with_label(name: str, value: str) → Self

Retrieves this container plus the given label.

Parameters:

• name – The name of the label (e.g., “org.opencontainers.artifact.created”).

• value – The value of the label (e.g., “2023-01-01T00:00:00Z”).

with_mounted_cache(path: str, cache: CacheVolume, *, source: Directory | None = None, sharing: CacheSharingMode | None = CacheSharingMode.SHARED, owner: str | None = '', expand: bool | None = False) → Self

Retrieves this container plus a cache volume mounted at the given path.

Parameters:

• path – Location of the cache directory (e.g., “/root/.npm”).

• cache – Identifier of the cache volume to mount.

• source – Identifier of the directory to use as the cache volume’s root.

• sharing – Sharing mode of the cache volume.

• owner – A user:group to set for the mounted cache directory. Note that this changes the ownership of the specified mount along with the initial filesystem provided by source (if any). It does not have any effect if/when the cache has already been created. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

with_mounted_directory(path: str, source: Directory, *, owner: str | None = '', read_only: bool | None = False, expand: bool | None = False) → Self

Retrieves this container plus a directory mounted at the given path.

Parameters:

• path – Location of the mounted directory (e.g., “/mnt/directory”).

• source – Identifier of the mounted directory.

• owner – A user:group to set for the mounted directory and its contents. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

• read_only – Mount the directory read-only.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

with_mounted_file(path: str, source: File, *, owner: str | None = '', expand: bool | None = False) → Self

Retrieves this container plus a file mounted at the given path.

Parameters:

• path – Location of the mounted file (e.g., “/tmp/file.txt”).

• source – Identifier of the mounted file.

• owner – A user or user:group to set for the mounted file. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo.txt”).

with_mounted_secret(path: str, source: Secret, *, owner: str | None = '', mode: int | None = 256, expand: bool | None = False) → Self

Retrieves this container plus a secret mounted into a file at the given path.

Parameters:

• path – Location of the secret file (e.g., “/tmp/secret.txt”).

• source – Identifier of the secret to mount.

• owner – A user:group to set for the mounted secret. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

• mode – Permission given to the mounted secret (e.g., 0600). This option requires an owner to be set to be active.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

with_mounted_temp(path: str, *, size: int | None = None, expand: bool | None = False) → Self

Retrieves this container plus a temporary directory mounted at the given path. Any writes will be ephemeral to a single withExec call; they will not be persisted to subsequent withExecs.

Parameters:

• path – Location of the temporary directory (e.g., “/tmp/temp_dir”).

• size – Size of the temporary directory in bytes.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

with_new_file(path: str, contents: str, *, permissions: int | None = 420, owner: str | None = '', expand: bool | None = False) → Self

Return a new container snapshot, with a file added to its filesystem with text content

Parameters:

• path – Path of the new file. May be relative or absolute. Example: “README.md” or “/etc/profile”

• contents – Contents of the new file. Example: “Hello world!”

• permissions – Permissions of the new file. Example: 0600

• owner – A user:group to set for the file. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo.txt”).

with_registry_auth(address: str, username: str, secret: Secret) → Self

Attach credentials for future publishing to a registry. Use in combination with publish

Parameters:

• address – The image address that needs authentication. Same format as “docker push”. Example: “registry.dagger.io/dagger:latest”

• username – The username to authenticate with. Example: “alice”

• secret – The API key, password or token to authenticate to this registry

with_rootfs(directory: Directory) → Self

Change the container’s root filesystem. The previous root filesystem will be lost.

Parameters:

directory – The new root filesystem.

with_secret_variable(name: str, secret: Secret) → Self

Set a new environment variable, using a secret value

Parameters:

• name – Name of the secret variable (e.g., “API_SECRET”).

• secret – Identifier of the secret value.

with_service_binding(alias: str, service: Service) → Self

Establish a runtime dependency from a container to a network service.

The service will be started automatically when needed and detached when it is no longer needed, executing the default command if none is set.

The service will be reachable from the container via the provided hostname alias.

The service dependency will also convey to any files or directories produced by the container.

Parameters:

• alias – Hostname that will resolve to the target service (only accessible from within this container)

• service – The target service

with_symlink(target: str, link_name: str, *, expand: bool | None = False) → Self

Return a snapshot with a symlink

Parameters:

• target – Location of the file or directory to link to (e.g., “/existing/file”).

• link_name – Location where the symbolic link will be created (e.g., “/new- file-link”).

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo.txt”).

with_unix_socket(path: str, source: Socket, *, owner: str | None = '', expand: bool | None = False) → Self

Retrieves this container plus a socket forwarded to the given Unix socket path.

Parameters:

• path – Location of the forwarded Unix socket (e.g., “/tmp/socket”).

• source – Identifier of the socket to forward.

• owner – A user:group to set for the mounted socket. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

with_user(name: str) → Self

Retrieves this container with a different command user.

Parameters:

name – The user to set (e.g., “root”).

with_volatile_variable(name: str, value: str) → Self

Set a new non-secret environment variable for future execs without invalidating exec cache when only its value changes.

This is an expert-only escape hatch. If a volatile value affects observable exec results, stale cached results may be reused.

Parameters:

• name – Name of the volatile variable (e.g., “CI_RUN_ID”).

• value – Value of the volatile variable.

with_workdir(path: str, *, expand: bool | None = False) → Self

Change the container’s working directory. Like WORKDIR in Dockerfile.

Parameters:

• path – The path to set as the working directory (e.g., “/app”).

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

without_annotation(name: str) → Self

Retrieves this container minus the given OCI annotation.

Parameters:

name – The name of the annotation.

without_default_args() → Self

Remove the container’s default arguments.

without_directory(path: str, *, expand: bool | None = False) → Self

Return a new container snapshot, with a directory removed from its filesystem

Parameters:

• path – Location of the directory to remove (e.g., “.github/”).

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

without_docker_healthcheck() → Self

Retrieves this container without a configured docker healtcheck command.

without_entrypoint(*, keep_default_args: bool | None = False) → Self

Reset the container’s OCI entrypoint.

Parameters:

keep_default_args – Don’t remove the default arguments when unsetting the entrypoint.

without_env_variable(name: str) → Self

Retrieves this container minus the given environment variable.

Parameters:

name – The name of the environment variable (e.g., “HOST”).

without_exposed_port(port: int, *, protocol: NetworkProtocol | None = NetworkProtocol.TCP) → Self

Unexpose a previously exposed port.

Parameters:

• port – Port number to unexpose

• protocol – Port protocol to unexpose

without_file(path: str, *, expand: bool | None = False) → Self

Retrieves this container with the file at the given path removed.

Parameters:

• path – Location of the file to remove (e.g., “/file.txt”).

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo.txt”).

without_files(paths: list[str], *, expand: bool | None = False) → Self

Return a new container spanshot with specified files removed

Parameters:

• paths – Paths of the files to remove. Example: [“foo.txt, “/root/.ssh/config”

• expand – Replace “${VAR}” or “$VAR” in the value of paths according to the current environment variables defined in the container (e.g. “/$VAR/foo.txt”).

without_label(name: str) → Self

Retrieves this container minus the given environment label.

Parameters:

name – The name of the label to remove (e.g., “org.opencontainers.artifact.created”).

without_mount(path: str, *, expand: bool | None = False) → Self

Retrieves this container after unmounting everything at the given path.

Parameters:

• path – Location of the cache directory (e.g., “/root/.npm”).

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

without_registry_auth(address: str) → Self

Retrieves this container without the registry authentication of a given address.

Parameters:

address – Registry’s address to remove the authentication from. Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).

without_secret_variable(name: str) → Self

Retrieves this container minus the given environment variable containing the secret.

Parameters:

name – The name of the environment variable (e.g., “HOST”).

without_unix_socket(path: str, *, expand: bool | None = False) → Self

Retrieves this container with a previously added Unix socket removed.

Parameters:

• path – Location of the socket to remove (e.g., “/tmp/socket”).

• expand – Replace “${VAR}” or “$VAR” in the value of path according to the current environment variables defined in the container (e.g. “/$VAR/foo”).

without_user() → Self

Retrieves this container with an unset command user.

Should default to root.

without_volatile_variable(name: str) → Self

Retrieves this container minus the given volatile environment variable.

Parameters:

name – The name of the volatile environment variable (e.g., “CI_RUN_ID”).

without_workdir() → Self

Unset the container’s working directory.

Should default to “/”.

async workdir() → str

Retrieves the working directory for all commands.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.ContainerID

Bases: Scalar

A unique identifier for an object.

class dagger.CurrentModule(ctx: Context)

Bases: Type

Reflective module API provided to functions at runtime.

async dependencies() → list[Module]

The dependencies of the module.

generated_context_directory() → Directory

The generated files and directories made on top of the module source’s context directory.

generators(*, include: list[str] | None = None) → GeneratorGroup

Return all generators defined by the module

Caution

Experimental: This API is highly experimental and may be removed or replaced entirely.

Parameters:

include – Only include generators matching the specified patterns

async id() → str

A unique identifier for this CurrentModule.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the module being executed in

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

source() → Directory

The directory containing the module’s source code loaded into the engine (plus any generated code that may have been created).

workdir(path: str, *, exclude: list[str] | None = None, include: list[str] | None = None, gitignore: bool | None = False) → Directory

Load a directory from the module’s scratch working directory, including any changes that may have been made to it during module function execution.

Parameters:

• path – Location of the directory to access (e.g., “.”).

• exclude – Exclude artifacts that match the given pattern (e.g., [“node_modules/”, “.git*”]).

• include – Include only artifacts that match the given pattern (e.g., [“app/”, “package.*”]).

• gitignore – Apply .gitignore filter rules inside the directory

workdir_file(path: str) → File

Load a file from the module’s scratch working directory, including any changes that may have been made to it during module function execution.Load a file from the module’s scratch working directory, including any changes that may have been made to it during module function execution.

Parameters:

path – Location of the file to retrieve (e.g., “README.md”).

class dagger.CurrentModuleID

Bases: Scalar

A unique identifier for an object.

class dagger.DiffStat(ctx: Context)

Bases: Type

async added_lines() → int

Number of added lines for this path.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this DiffStat.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async kind() → DiffStatKind

Type of change.

Returns:

The type of change for a diff stat entry.

Return type:

DiffStatKind

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async old_path() → str | None

Previous path of the file, set only for renames.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async path() → str

Path of the changed file or directory.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async removed_lines() → int

Number of removed lines for this path.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.DiffStatID

Bases: Scalar

A unique identifier for an object.

class dagger.DiffStatKind(*values)

Bases: Enum

The type of change for a diff stat entry.

ADDED = 'ADDED'

MODIFIED = 'MODIFIED'

REMOVED = 'REMOVED'

RENAMED = 'RENAMED'

class dagger.Directory(ctx: Context)

Bases: Type

A directory.

as_git() → GitRepository

Converts this directory to a local git repository

as_module(*, source_root_path: str | None = '.') → Module

Load the directory as a Dagger module source

Parameters:

source_root_path – An optional subpath of the directory which contains the module’s configuration file. If not set, the module source code is loaded from the root of the directory.

as_module_source(*, source_root_path: str | None = '.') → ModuleSource

Load the directory as a Dagger module source

Parameters:

source_root_path – An optional subpath of the directory which contains the module’s configuration file. If not set, the module source code is loaded from the root of the directory.

changes(from_: Self) → Changeset

Return the difference between this directory and another directory, typically an older snapshot.

The difference is encoded as a changeset, which also tracks removed files, and can be applied to other directories.

Parameters:

from – The base directory snapshot to compare against

chown(path: str, owner: str) → Self

Change the owner of the directory contents recursively.

Parameters:

• path – Path of the directory to change ownership of (e.g., “/”).

• owner – A user:group to set for the mounted directory and its contents. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

diff(other: Self) → Self

Return the difference between this directory and an another directory. The difference is encoded as a directory.

Parameters:

other – The directory to compare against

async digest() → str

Return the directory’s digest. The format of the digest is not guaranteed to be stable between releases of Dagger. It is guaranteed to be stable between invocations of the same Dagger engine.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

directory(path: str) → Self

Retrieves a directory at the given path.

Parameters:

path – Location of the directory to retrieve. Example: “/src”

docker_build(*, dockerfile: str | None = 'Dockerfile', platform: Platform | None = None, build_args: list[BuildArg] | None = None, target: str | None = '', secrets: list[Secret] | None = None, no_init: bool | None = False, ssh: Socket | None = None) → Container

Use Dockerfile compatibility to build a container from this directory. Only use this function for Dockerfile compatibility. Otherwise use the native Container type directly, it is feature-complete and supports all Dockerfile features.

Parameters:

• dockerfile – Path to the Dockerfile to use (e.g., “frontend.Dockerfile”).

• platform – The platform to build.

• build_args – Build arguments to use in the build.

• target – Target build stage to build.

• secrets – Secrets to pass to the build. They will be mounted at /run/secrets/[secret-name].

• no_init – If set, skip the automatic init process injected into containers created by RUN statements. This should only be used if the user requires that their exec processes be the pid 1 process in the container. Otherwise it may result in unexpected behavior.

• ssh – A socket to use for SSH authentication during the build (e.g., for Dockerfile RUN –mount=type=ssh instructions). Typically obtained via host.unixSocket() pointing to the SSH_AUTH_SOCK.

async entries(*, path: str | None = None) → list[str]

Returns a list of files and directories at the given path.

Parameters:

path – Location of the directory to look at (e.g., “/src”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async exists(path: str, *, expected_type: ExistsType | None = None, do_not_follow_symlinks: bool | None = False) → bool

check if a file or directory exists

Parameters:

• path – Path to check (e.g., “/file.txt”).

• expected_type – If specified, also validate the type of file (e.g. “REGULAR_TYPE”, “DIRECTORY_TYPE”, or “SYMLINK_TYPE”).

• do_not_follow_symlinks – If specified, do not follow symlinks.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async export(path: str, *, wipe: bool | None = False) → str

Writes the contents of the directory to a path on the host.

Parameters:

• path – Location of the copied directory (e.g., “logs/”).

• wipe – If true, then the host directory will be wiped clean before exporting so that it exactly matches the directory being exported; this means it will delete any files on the host that aren’t in the exported dir. If false (the default), the contents of the directory will be merged with any existing contents of the host directory, leaving any existing files on the host that aren’t in the exported directory alone.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

file(path: str) → File

Retrieve a file at the given path.

Parameters:

path – Location of the file to retrieve (e.g., “README.md”).

filter(*, exclude: list[str] | None = None, include: list[str] | None = None, gitignore: bool | None = False) → Self

Return a snapshot with some paths included or excluded

Parameters:

• exclude – If set, paths matching one of these glob patterns is excluded from the new snapshot. Example: [“node_modules/”, “.git*”, “.env”]

• include – If set, only paths matching one of these glob patterns is included in the new snapshot. Example: (e.g., [“app/”, “package.*”]).

• gitignore – If set, apply .gitignore rules when filtering the directory.

async find_up(name: str, start: str) → str | None

Search up the directory tree for a file or directory, and return its path. If no match, return null

Parameters:

• name – The name of the file or directory to search for

• start – The path to start the search from

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async glob(pattern: str) → list[str]

Returns a list of files and directories that matche the given pattern.

Parameters:

pattern – Pattern to match (e.g., “*.md”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Directory.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

Returns the name of the directory.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async search(pattern: str, *, paths: list[str] | None = None, globs: list[str] | None = None, literal: bool | None = False, multiline: bool | None = False, dotall: bool | None = False, insensitive: bool | None = False, skip_ignored: bool | None = False, skip_hidden: bool | None = False, files_only: bool | None = False, limit: int | None = None) → list[SearchResult]

Searches for content matching the given regular expression or literal string.

Uses Rust regex syntax; escape literal ., [, ], {, }, | with backslashes.

Parameters:

• pattern – The text to match.

• paths – Directory or file paths to search

• globs – Glob patterns to match (e.g., “*.md”)

• literal – Interpret the pattern as a literal string instead of a regular expression.

• multiline – Enable searching across multiple lines.

• dotall – Allow the . pattern to match newlines in multiline mode.

• insensitive – Enable case-insensitive matching.

• skip_ignored – Honor .gitignore, .ignore, and .rgignore files.

• skip_hidden – Skip hidden files (files starting with .).

• files_only – Only return matching files, not lines and content

• limit – Limit the number of results to return

stat(path: str, *, do_not_follow_symlinks: bool | None = False) → Stat

Return file status

Parameters:

• path – Path to stat (e.g., “/file.txt”).

• do_not_follow_symlinks – If specified, do not follow symlinks.

async sync() → Self

Force evaluation in the engine.

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

terminal(*, container: Container | None = None, cmd: list[str] | None = None, experimental_privileged_nesting: bool | None = False, insecure_root_capabilities: bool | None = False) → Self

Opens an interactive terminal in new container with this directory mounted inside.

Parameters:

• container – If set, override the default container used for the terminal.

• cmd – If set, override the container’s default terminal command and invoke these command arguments instead.

• experimental_privileged_nesting – Provides Dagger access to the executed command.

• insecure_root_capabilities – Execute the command with all root capabilities. This is similar to running a command with “sudo” or executing “docker run” with the ” –privileged” flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.

with_(cb: Callable[[Directory], Directory]) → Directory

Call the provided callable with current Directory.

This is useful for reusability and readability by not breaking the calling chain.

with_changes(changes: Changeset) → Self

Return a directory with changes from another directory applied to it.

Parameters:

changes – Changes to apply to the directory

with_directory(path: str, source: Self, *, exclude: list[str] | None = None, include: list[str] | None = None, gitignore: bool | None = False, owner: str | None = '', permissions: int | None = None) → Self

Return a snapshot with a directory added

Parameters:

• path – Location of the written directory (e.g., “/src/”).

• source – Identifier of the directory to copy.

• exclude – Exclude artifacts that match the given pattern (e.g., [“node_modules/”, “.git*”]).

• include – Include only artifacts that match the given pattern (e.g., [“app/”, “package.*”]).

• gitignore – Apply .gitignore filter rules inside the directory

• owner – A user:group to set for the copied directory and its contents. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

• permissions – Permission given to the copied directory and contents (e.g., 0755).

with_error(err: str) → Self

Raise an error.

Parameters:

err – Message of the error to raise. If empty, the error will be ignored.

with_file(path: str, source: File, *, permissions: int | None = None, owner: str | None = '') → Self

Retrieves this directory plus the contents of the given file copied to the given path.

Parameters:

• path – Location of the copied file (e.g., “/file.txt”).

• source – Identifier of the file to copy.

• permissions – Permission given to the copied file (e.g., 0600).

• owner – A user:group to set for the copied directory and its contents. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_files(path: str, sources: list[File], *, permissions: int | None = None) → Self

Retrieves this directory plus the contents of the given files copied to the given path.

Parameters:

• path – Location where copied files should be placed (e.g., “/src”).

• sources – Identifiers of the files to copy.

• permissions – Permission given to the copied files (e.g., 0600).

with_new_directory(path: str, *, permissions: int | None = 420) → Self

Retrieves this directory plus a new directory created at the given path.

Parameters:

• path – Location of the directory created (e.g., “/logs”).

• permissions – Permission granted to the created directory (e.g., 0777).

with_new_file(path: str, contents: str, *, permissions: int | None = 420) → Self

Return a snapshot with a new file added

Parameters:

• path – Path of the new file. Example: “foo/bar.txt”

• contents – Contents of the new file. Example: “Hello world!”

• permissions – Permissions of the new file. Example: 0600

with_patch(patch: str) → Self

Retrieves this directory with the given Git-compatible patch applied.

Caution

Experimental: This API is highly experimental and may be removed or replaced entirely.

patch:

Patch to apply (e.g., “diff –git a/file.txt b/file.txt

index

1234567..abcdef8 100644

— a/file.txt +++ b/file.txt @@ -1,1

+1,1 @@

-Hello +World “).

with_patch_file(patch: File) → Self

Retrieves this directory with the given Git-compatible patch file applied.

Caution

Experimental: This API is highly experimental and may be removed or replaced entirely.

Parameters:

patch – File containing the patch to apply

with_symlink(target: str, link_name: str) → Self

Return a snapshot with a symlink

Parameters:

• target – Location of the file or directory to link to (e.g., “/existing/file”).

• link_name – Location where the symbolic link will be created (e.g., “/new- file-link”).

with_timestamps(timestamp: int) → Self

Retrieves this directory with all file/dir timestamps set to the given time.

Parameters:

timestamp – Timestamp to set dir/files in. Formatted in seconds following Unix epoch (e.g., 1672531199).

without_directory(path: str) → Self

Return a snapshot with a subdirectory removed

Parameters:

path – Path of the subdirectory to remove. Example: “.github/workflows”

without_file(path: str) → Self

Return a snapshot with a file removed

Parameters:

path – Path of the file to remove (e.g., “/file.txt”).

without_files(paths: list[str]) → Self

Return a snapshot with files removed

Parameters:

paths – Paths of the files to remove (e.g., [“/file.txt”]).

class dagger.DirectoryID

Bases: Scalar

A unique identifier for an object.

class dagger.Engine(ctx: Context)

Bases: Type

The Dagger engine configuration and state

async clients() → list[str]

The list of connected client IDs

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Engine.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

local_cache() → EngineCache

The local engine cache state tracked by dagql

async name() → str

The name of the engine instance.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.EngineCache(ctx: Context)

Bases: Type

A cache storage for the Dagger engine

entry_set(*, key: str | None = '') → EngineCacheEntrySet

The current set of entries in the cache

async id() → str

A unique identifier for this EngineCache.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async max_used_space() → int

The maximum bytes to keep in the cache without pruning.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async min_free_space() → int

The target amount of free disk space the garbage collector will attempt to leave.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async prune(*, use_default_policy: bool | None = False, max_used_space: str | None = '', reserved_space: str | None = '', min_free_space: str | None = '', target_space: str | None = '') → Void | None

Prune the cache of releaseable entries

Parameters:

• use_default_policy – Use the engine-wide default pruning policy if true, otherwise prune the whole cache of any releasable entries.

• max_used_space – Override the maximum disk space to keep before pruning (e.g. “200GB” or “80%”).

• reserved_space – Override the minimum disk space to retain during pruning (e.g. “500GB” or “10%”).

• min_free_space – Override the minimum free disk space target during pruning (e.g. “20GB” or “20%”).

• target_space – Override the target disk space to keep after pruning (e.g. “200GB” or “50%”).

Returns:

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.

Return type:

Void | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async reserved_space() → int

The minimum amount of disk space this policy is guaranteed to retain.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async target_space() → int

The target number of bytes to keep when pruning.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.EngineCacheEntry(ctx: Context)

Bases: Type

An individual cache entry in a cache entry set

async actively_used() → bool

Whether the cache entry is actively being used.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async created_time_unix_nano() → int

The time the cache entry was created, in Unix nanoseconds.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async dagql_call() → str

The DagQL call that produced this cache entry.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async description() → str

The description of the cache entry.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async disk_space_bytes() → int

The disk space used by the cache entry.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this EngineCacheEntry.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async most_recent_use_time_unix_nano() → int

The most recent time the cache entry was used, in Unix nanoseconds.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async record_type() → str

The type of the cache record (e.g. regular, internal, frontend, source.local, source.git.checkout, exec.cachemount).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async record_types() → list[str]

The storage record types represented by this cache entry.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.EngineCacheEntryID

Bases: Scalar

A unique identifier for an object.

class dagger.EngineCacheEntrySet(ctx: Context)

Bases: Type

A set of cache entries returned by a query to a cache

async disk_space_bytes() → int

The total disk space used by the cache entries in this set.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async entries() → list[EngineCacheEntry]

The list of individual cache entries in the set

async entry_count() → int

The number of cache entries in this set.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this EngineCacheEntrySet.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.EngineCacheEntrySetID

Bases: Scalar

A unique identifier for an object.

class dagger.EngineCacheID

Bases: Scalar

A unique identifier for an object.

class dagger.EngineID

Bases: Scalar

A unique identifier for an object.

class dagger.EnumTypeDef(ctx: Context)

Bases: Type

A definition of a custom enum defined in a Module.

async description() → str

A doc string for the enum, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this EnumTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async members() → list[EnumValueTypeDef]

The members of the enum.

async name() → str

The name of the enum.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

source_map() → SourceMap

The location of this enum declaration.

async source_module_name() → str

If this EnumTypeDef is associated with a Module, the name of the module. Unset otherwise.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async values() → list[EnumValueTypeDef]

The members of the enum.

Deprecated

use members instead

class dagger.EnumTypeDefID

Bases: Scalar

A unique identifier for an object.

class dagger.EnumValueTypeDef(ctx: Context)

Bases: Type

A definition of a value in a custom enum defined in a Module.

async deprecated() → str | None

The reason this enum member is deprecated, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async description() → str

A doc string for the enum member, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this EnumValueTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the enum member.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

source_map() → SourceMap

The location of this enum member declaration.

async value() → str

The value of the enum member

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.EnumValueTypeDefID

Bases: Scalar

A unique identifier for an object.

class dagger.Env(ctx: Context)

Bases: Type

check(name: str) → Check

Return the check with the given name from the installed modules. Must match exactly one check.

Caution

Experimental: Checks API is highly experimental and may be removed or replaced entirely.

Parameters:

name – The name of the check to retrieve

checks(*, include: list[str] | None = None, no_generate: bool | None = None) → CheckGroup

Return all checks defined by the installed modules

Caution

Experimental: Checks API is highly experimental and may be removed or replaced entirely.

Parameters:

• include – Only include checks matching the specified patterns

• no_generate – When true, only return annotated check functions; exclude generate-as-checks

async id() → str

A unique identifier for this Env.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

input(name: str) → Binding

Retrieves an input binding by name

async inputs() → list[Binding]

Returns all input bindings provided to the environment

output(name: str) → Binding

Retrieves an output binding by name

async outputs() → list[Binding]

Returns all declared output bindings for the environment

services(*, include: list[str] | None = None) → UpGroup

Return all services defined by the installed modules

Caution

Experimental: Services API is highly experimental and may be removed or replaced entirely.

Parameters:

include – Only include services matching the specified patterns

with_(cb: Callable[[Env], Env]) → Env

Call the provided callable with current Env.

This is useful for reusability and readability by not breaking the calling chain.

with_address_input(name: str, value: Address, description: str) → Self

Create or update a binding of type Address in the environment

Parameters:

• name – The name of the binding

• value – The Address value to assign to the binding

• description – The purpose of the input

with_address_output(name: str, description: str) → Self

Declare a desired Address output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_cache_volume_input(name: str, value: CacheVolume, description: str) → Self

Create or update a binding of type CacheVolume in the environment

Parameters:

• name – The name of the binding

• value – The CacheVolume value to assign to the binding

• description – The purpose of the input

with_cache_volume_output(name: str, description: str) → Self

Declare a desired CacheVolume output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_changeset_input(name: str, value: Changeset, description: str) → Self

Create or update a binding of type Changeset in the environment

Parameters:

• name – The name of the binding

• value – The Changeset value to assign to the binding

• description – The purpose of the input

with_changeset_output(name: str, description: str) → Self

Declare a desired Changeset output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_check_group_input(name: str, value: CheckGroup, description: str) → Self

Create or update a binding of type CheckGroup in the environment

Parameters:

• name – The name of the binding

• value – The CheckGroup value to assign to the binding

• description – The purpose of the input

with_check_group_output(name: str, description: str) → Self

Declare a desired CheckGroup output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_check_input(name: str, value: Check, description: str) → Self

Create or update a binding of type Check in the environment

Parameters:

• name – The name of the binding

• value – The Check value to assign to the binding

• description – The purpose of the input

with_check_output(name: str, description: str) → Self

Declare a desired Check output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_cloud_input(name: str, value: Cloud, description: str) → Self

Create or update a binding of type Cloud in the environment

Parameters:

• name – The name of the binding

• value – The Cloud value to assign to the binding

• description – The purpose of the input

with_cloud_output(name: str, description: str) → Self

Declare a desired Cloud output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_container_input(name: str, value: Container, description: str) → Self

Create or update a binding of type Container in the environment

Parameters:

• name – The name of the binding

• value – The Container value to assign to the binding

• description – The purpose of the input

with_container_output(name: str, description: str) → Self

Declare a desired Container output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_current_module() → Self

Installs the current module into the environment, exposing its functions to the model

Contextual path arguments will be populated using the environment’s workspace.

with_diff_stat_input(name: str, value: DiffStat, description: str) → Self

Create or update a binding of type DiffStat in the environment

Parameters:

• name – The name of the binding

• value – The DiffStat value to assign to the binding

• description – The purpose of the input

with_diff_stat_output(name: str, description: str) → Self

Declare a desired DiffStat output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_directory_input(name: str, value: Directory, description: str) → Self

Create or update a binding of type Directory in the environment

Parameters:

• name – The name of the binding

• value – The Directory value to assign to the binding

• description – The purpose of the input

with_directory_output(name: str, description: str) → Self

Declare a desired Directory output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_env_file_input(name: str, value: EnvFile, description: str) → Self

Create or update a binding of type EnvFile in the environment

Parameters:

• name – The name of the binding

• value – The EnvFile value to assign to the binding

• description – The purpose of the input

with_env_file_output(name: str, description: str) → Self

Declare a desired EnvFile output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_env_input(name: str, value: Self, description: str) → Self

Create or update a binding of type Env in the environment

Parameters:

• name – The name of the binding

• value – The Env value to assign to the binding

• description – The purpose of the input

with_env_output(name: str, description: str) → Self

Declare a desired Env output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_file_input(name: str, value: File, description: str) → Self

Create or update a binding of type File in the environment

Parameters:

• name – The name of the binding

• value – The File value to assign to the binding

• description – The purpose of the input

with_file_output(name: str, description: str) → Self

Declare a desired File output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_generator_group_input(name: str, value: GeneratorGroup, description: str) → Self

Create or update a binding of type GeneratorGroup in the environment

Parameters:

• name – The name of the binding

• value – The GeneratorGroup value to assign to the binding

• description – The purpose of the input

with_generator_group_output(name: str, description: str) → Self

Declare a desired GeneratorGroup output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_generator_input(name: str, value: Generator, description: str) → Self

Create or update a binding of type Generator in the environment

Parameters:

• name – The name of the binding

• value – The Generator value to assign to the binding

• description – The purpose of the input

with_generator_output(name: str, description: str) → Self

Declare a desired Generator output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_git_ref_input(name: str, value: GitRef, description: str) → Self

Create or update a binding of type GitRef in the environment

Parameters:

• name – The name of the binding

• value – The GitRef value to assign to the binding

• description – The purpose of the input

with_git_ref_output(name: str, description: str) → Self

Declare a desired GitRef output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_git_repository_input(name: str, value: GitRepository, description: str) → Self

Create or update a binding of type GitRepository in the environment

Parameters:

• name – The name of the binding

• value – The GitRepository value to assign to the binding

• description – The purpose of the input

with_git_repository_output(name: str, description: str) → Self

Declare a desired GitRepository output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_http_state_input(name: str, value: HTTPState, description: str) → Self

Create or update a binding of type HTTPState in the environment

Parameters:

• name – The name of the binding

• value – The HTTPState value to assign to the binding

• description – The purpose of the input

with_http_state_output(name: str, description: str) → Self

Declare a desired HTTPState output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_json_value_input(name: str, value: JSONValue, description: str) → Self

Create or update a binding of type JSONValue in the environment

Parameters:

• name – The name of the binding

• value – The JSONValue value to assign to the binding

• description – The purpose of the input

with_json_value_output(name: str, description: str) → Self

Declare a desired JSONValue output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_main_module(module: Module) → Self

Sets the main module for this environment (the project being worked on)

Contextual path arguments will be populated using the environment’s workspace.

with_module(module: Module) → Self

Installs a module into the environment, exposing its functions to the model

Contextual path arguments will be populated using the environment’s workspace.

Deprecated

Use withMainModule instead

with_module_config_client_input(name: str, value: ModuleConfigClient, description: str) → Self

Create or update a binding of type ModuleConfigClient in the environment

Parameters:

• name – The name of the binding

• value – The ModuleConfigClient value to assign to the binding

• description – The purpose of the input

with_module_config_client_output(name: str, description: str) → Self

Declare a desired ModuleConfigClient output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_module_input(name: str, value: Module, description: str) → Self

Create or update a binding of type Module in the environment

Parameters:

• name – The name of the binding

• value – The Module value to assign to the binding

• description – The purpose of the input

with_module_output(name: str, description: str) → Self

Declare a desired Module output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_module_source_input(name: str, value: ModuleSource, description: str) → Self

Create or update a binding of type ModuleSource in the environment

Parameters:

• name – The name of the binding

• value – The ModuleSource value to assign to the binding

• description – The purpose of the input

with_module_source_output(name: str, description: str) → Self

Declare a desired ModuleSource output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_search_result_input(name: str, value: SearchResult, description: str) → Self

Create or update a binding of type SearchResult in the environment

Parameters:

• name – The name of the binding

• value – The SearchResult value to assign to the binding

• description – The purpose of the input

with_search_result_output(name: str, description: str) → Self

Declare a desired SearchResult output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_search_submatch_input(name: str, value: SearchSubmatch, description: str) → Self

Create or update a binding of type SearchSubmatch in the environment

Parameters:

• name – The name of the binding

• value – The SearchSubmatch value to assign to the binding

• description – The purpose of the input

with_search_submatch_output(name: str, description: str) → Self

Declare a desired SearchSubmatch output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_secret_input(name: str, value: Secret, description: str) → Self

Create or update a binding of type Secret in the environment

Parameters:

• name – The name of the binding

• value – The Secret value to assign to the binding

• description – The purpose of the input

with_secret_output(name: str, description: str) → Self

Declare a desired Secret output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_service_input(name: str, value: Service, description: str) → Self

Create or update a binding of type Service in the environment

Parameters:

• name – The name of the binding

• value – The Service value to assign to the binding

• description – The purpose of the input

with_service_output(name: str, description: str) → Self

Declare a desired Service output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_socket_input(name: str, value: Socket, description: str) → Self

Create or update a binding of type Socket in the environment

Parameters:

• name – The name of the binding

• value – The Socket value to assign to the binding

• description – The purpose of the input

with_socket_output(name: str, description: str) → Self

Declare a desired Socket output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_stat_input(name: str, value: Stat, description: str) → Self

Create or update a binding of type Stat in the environment

Parameters:

• name – The name of the binding

• value – The Stat value to assign to the binding

• description – The purpose of the input

with_stat_output(name: str, description: str) → Self

Declare a desired Stat output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_string_input(name: str, value: str, description: str) → Self

Provides a string input binding to the environment

Parameters:

• name – The name of the binding

• value – The string value to assign to the binding

• description – The description of the input

with_string_output(name: str, description: str) → Self

Declares a desired string output binding

Parameters:

• name – The name of the binding

• description – The description of the output

with_up_group_input(name: str, value: UpGroup, description: str) → Self

Create or update a binding of type UpGroup in the environment

Parameters:

• name – The name of the binding

• value – The UpGroup value to assign to the binding

• description – The purpose of the input

with_up_group_output(name: str, description: str) → Self

Declare a desired UpGroup output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_up_input(name: str, value: Up, description: str) → Self

Create or update a binding of type Up in the environment

Parameters:

• name – The name of the binding

• value – The Up value to assign to the binding

• description – The purpose of the input

with_up_output(name: str, description: str) → Self

Declare a desired Up output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

with_workspace(workspace: Directory) → Self

Returns a new environment with the provided workspace

Parameters:

workspace – The directory to set as the host filesystem

with_workspace_input(name: str, value: Workspace, description: str) → Self

Create or update a binding of type Workspace in the environment

Parameters:

• name – The name of the binding

• value – The Workspace value to assign to the binding

• description – The purpose of the input

with_workspace_output(name: str, description: str) → Self

Declare a desired Workspace output to be assigned in the environment

Parameters:

• name – The name of the binding

• description – A description of the desired value of the binding

without_outputs() → Self

Returns a new environment without any outputs

workspace() → Directory

class dagger.EnvFile(ctx: Context)

Bases: Type

A collection of environment variables.

as_file() → File

Return as a file

async exists(name: str) → bool

Check if a variable exists

Parameters:

name – Variable name

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async get(name: str, *, raw: bool | None = None) → str

Lookup a variable (last occurrence wins) and return its value, or an empty string

Parameters:

• name – Variable name

• raw – Return the value exactly as written to the file. No quote removal or variable expansion

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this EnvFile.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

namespace(prefix: str) → Self

Filters variables by prefix and removes the pref from keys. Variables without the prefix are excluded. For example, with the prefix “MY_APP_” and variables: MY_APP_TOKEN=topsecret MY_APP_NAME=hello FOO=bar the resulting environment will contain: TOKEN=topsecret NAME=hello

Parameters:

prefix – The prefix to filter by

async variables(*, raw: bool | None = None) → list[EnvVariable]

Return all variables

Parameters:

raw – Return values exactly as written to the file. No quote removal or variable expansion

with_(cb: Callable[[EnvFile], EnvFile]) → EnvFile

Call the provided callable with current EnvFile.

This is useful for reusability and readability by not breaking the calling chain.

with_variable(name: str, value: str) → Self

Add a variable

Parameters:

• name – Variable name

• value – Variable value

without_variable(name: str) → Self

Remove all occurrences of the named variable

Parameters:

name – Variable name

class dagger.EnvFileID

Bases: Scalar

A unique identifier for an object.

class dagger.EnvID

Bases: Scalar

A unique identifier for an object.

class dagger.EnvVariable(ctx: Context)

Bases: Type

An environment variable name and value.

async id() → str

A unique identifier for this EnvVariable.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The environment variable name.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async value() → str

The environment variable value.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.EnvVariableID

Bases: Scalar

A unique identifier for an object.

class dagger.Error(ctx: Context)

Bases: Type

async id() → str

A unique identifier for this Error.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async message() → str

A description of the error.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async values() → list[ErrorValue]

The extensions of the error.

with_(cb: Callable[[Error], Error]) → Error

Call the provided callable with current Error.

This is useful for reusability and readability by not breaking the calling chain.

with_value(name: str, value: JSON) → Self

Add a value to the error.

Parameters:

• name – The name of the value.

• value – The value to store on the error.

class dagger.ErrorID

Bases: Scalar

A unique identifier for an object.

class dagger.ErrorValue(ctx: Context)

Bases: Type

async id() → str

A unique identifier for this ErrorValue.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the value.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async value() → JSON

The value.

Returns:

An arbitrary JSON-encoded value.

Return type:

JSON

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.ErrorValueID

Bases: Scalar

A unique identifier for an object.

class dagger.ExistsType(*values)

Bases: Enum

File type.

DIRECTORY_TYPE = 'DIRECTORY_TYPE'

REGULAR_TYPE = 'REGULAR_TYPE'

SYMLINK_TYPE = 'SYMLINK_TYPE'

class dagger.Exportable(*args, **kwargs)

Bases: Protocol

An object that can be exported to the host. Calling export writes the object to a path on the host filesystem and returns the path that was written.

async export(path: str) → str

class dagger.ExportableID

Bases: Scalar

A unique identifier for an object.

class dagger.FieldTypeDef(ctx: Context)

Bases: Type

A definition of a field on a custom object defined in a Module. A field on an object has a static value, as opposed to a function on an object whose value is computed by invoking code (and can accept arguments).

async deprecated() → str | None

The reason this enum member is deprecated, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async description() → str

A doc string for the field, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this FieldTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the field in lowerCamelCase format.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

source_map() → SourceMap

The location of this field declaration.

type_def() → TypeDef

The type of the field.

class dagger.FieldTypeDefID

Bases: Scalar

A unique identifier for an object.

class dagger.File(ctx: Context)

Bases: Type

A file.

as_env_file(*, expand: bool | None = None) → EnvFile

Parse as an env file

Parameters:

expand – Replace “${VAR}” or “$VAR” with the value of other vars .. deprecated:: Variable expansion is now enabled by default

as_json() → JSONValue

Parse the file contents as JSON.

chown(owner: str) → Self

Change the owner of the file recursively.

Parameters:

owner – A user:group to set for the file. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

async contents(*, offset_lines: int | None = None, limit_lines: int | None = None) → str

Retrieves the contents of the file.

Parameters:

• offset_lines – Start reading after this line

• limit_lines – Maximum number of lines to read

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async digest(*, exclude_metadata: bool | None = False) → str

Return the file’s digest. The format of the digest is not guaranteed to be stable between releases of Dagger. It is guaranteed to be stable between invocations of the same Dagger engine.

Parameters:

exclude_metadata – If true, exclude metadata from the digest.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async export(path: str, *, allow_parent_dir_path: bool | None = False) → str

Writes the file to a file path on the host.

Parameters:

• path – Location of the written directory (e.g., “output.txt”).

• allow_parent_dir_path – If allowParentDirPath is true, the path argument can be a directory path, in which case the file will be created in that directory.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this File.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

Retrieves the name of the file.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async search(pattern: str, *, literal: bool | None = False, multiline: bool | None = False, dotall: bool | None = False, insensitive: bool | None = False, skip_ignored: bool | None = False, skip_hidden: bool | None = False, files_only: bool | None = False, limit: int | None = None, paths: list[str] | None = None, globs: list[str] | None = None) → list[SearchResult]

Searches for content matching the given regular expression or literal string.

Uses Rust regex syntax; escape literal ., [, ], {, }, | with backslashes.

Parameters:

• pattern – The text to match.

• literal – Interpret the pattern as a literal string instead of a regular expression.

• multiline – Enable searching across multiple lines.

• dotall – Allow the . pattern to match newlines in multiline mode.

• insensitive – Enable case-insensitive matching.

• skip_ignored – Honor .gitignore, .ignore, and .rgignore files.

• skip_hidden – Skip hidden files (files starting with .).

• files_only – Only return matching files, not lines and content

• limit – Limit the number of results to return

• paths

• globs

async size() → int

Retrieves the size of the file, in bytes.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

stat() → Stat

Return file status

async sync() → Self

Force evaluation in the engine.

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_(cb: Callable[[File], File]) → File

Call the provided callable with current File.

This is useful for reusability and readability by not breaking the calling chain.

with_name(name: str) → Self

Retrieves this file with its name set to the given name.

Parameters:

name – Name to set file to.

with_replaced(search: str, replacement: str, *, all: bool | None = False, first_from: int | None = None) → Self

Retrieves the file with content replaced with the given text.

If ‘all’ is true, all occurrences of the pattern will be replaced.

If ‘firstAfter’ is specified, only the first match starting at the specified line will be replaced.

If neither are specified, and there are multiple matches for the pattern, this will error.

If there are no matches for the pattern, this will error.

Parameters:

• search – The text to match.

• replacement – The text to match.

• all – Replace all occurrences of the pattern.

• first_from – Replace the first match starting from the specified line.

with_timestamps(timestamp: int) → Self

Retrieves this file with its created/modified timestamps set to the given time.

Parameters:

timestamp – Timestamp to set dir/files in. Formatted in seconds following Unix epoch (e.g., 1672531199).

class dagger.FileID

Bases: Scalar

A unique identifier for an object.

class dagger.FileType(*values)

Bases: Enum

File type.

DIRECTORY = 'DIRECTORY'

DIRECTORY_TYPE = 'DIRECTORY'

REGULAR = 'REGULAR'

REGULAR_TYPE = 'REGULAR'

SYMLINK = 'SYMLINK'

SYMLINK_TYPE = 'SYMLINK'

UNKNOWN = 'UNKNOWN'

class dagger.Function(ctx: Context)

Bases: Type

Function represents a resolver provided by a Module. A function always evaluates against a parent object and is given a set of named arguments.

async args() → list[FunctionArg]

Arguments accepted by the function, if any.

async deprecated() → str | None

The reason this function is deprecated, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async description() → str

A doc string for the function, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Function.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the function.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

return_type() → TypeDef

The type returned by the function.

source_map() → SourceMap

The location of this function declaration.

async source_module_name() → str

If this function is provided by a module, the name of the module. Unset otherwise.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_(cb: Callable[[Function], Function]) → Function

Call the provided callable with current Function.

This is useful for reusability and readability by not breaking the calling chain.

with_arg(name: str, type_def: TypeDef, *, description: str | None = '', default_value: JSON | None = None, default_path: str | None = '', ignore: list[str] | None = None, source_map: SourceMap | None = None, deprecated: str | None = None, default_address: str | None = '') → Self

Returns the function with the provided argument

Parameters:

• name – The name of the argument

• type_def – The type of the argument

• description – A doc string for the argument, if any

• default_value – A default value to use for this argument if not explicitly set by the caller, if any

• default_path – If the argument is a Directory or File type, default to load path from context directory, relative to root directory.

• ignore – Patterns to ignore when loading the contextual argument value.

• source_map – The source map for the argument definition.

• deprecated – If deprecated, the reason or migration path.

• default_address

with_cache_policy(policy: FunctionCachePolicy, *, time_to_live: str | None = None) → Self

Returns the function updated to use the provided cache policy.

Parameters:

• policy – The cache policy to use.

• time_to_live – The TTL for the cache policy, if applicable. Provided as a duration string, e.g. “5m”, “1h30s”.

with_check() → Self

Returns the function with a flag indicating it’s a check.

with_deprecated(*, reason: str | None = None) → Self

Returns the function with the provided deprecation reason.

Parameters:

reason – Reason or migration path describing the deprecation.

with_description(description: str) → Self

Returns the function with the given doc string.

Parameters:

description – The doc string to set.

with_generator() → Self

Returns the function with a flag indicating it’s a generator.

with_source_map(source_map: SourceMap) → Self

Returns the function with the given source map.

Parameters:

source_map – The source map for the function definition.

with_up() → Self

Returns the function with a flag indicating it returns a service for dagger up.

class dagger.FunctionArg(ctx: Context)

Bases: Type

An argument accepted by a function. This is a specification for an argument at function definition time, not an argument passed at function call time.

async default_address() → str

Only applies to arguments of type Container. If the argument is not set, load it from the given address (e.g. alpine:latest)

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async default_path() → str

Only applies to arguments of type File or Directory. If the argument is not set, load it from the given path in the context directory

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async default_value() → JSON

A default value to use for this argument when not explicitly set by the caller, if any.

Returns:

An arbitrary JSON-encoded value.

Return type:

JSON

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async deprecated() → str | None

The reason this function is deprecated, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async description() → str

A doc string for the argument, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this FunctionArg.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async ignore() → list[str]

Only applies to arguments of type Directory. The ignore patterns are applied to the input directory, and matching entries are filtered out, in a cache-efficient manner.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the argument in lowerCamelCase format.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

source_map() → SourceMap

The location of this arg declaration.

type_def() → TypeDef

The type of the argument.

class dagger.FunctionArgID

Bases: Scalar

A unique identifier for an object.

class dagger.FunctionCachePolicy(*values)

Bases: Enum

The behavior configured for function result caching.

Default = 'Default'

Never = 'Never'

PerSession = 'PerSession'

class dagger.FunctionCall(ctx: Context)

Bases: Type

An active function call.

async id() → str

A unique identifier for this FunctionCall.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async input_args() → list[FunctionCallArgValue]

The argument values the function is being invoked with.

async name() → str

The name of the function being called.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async parent() → JSON

The value of the parent object of the function being called. If the function is top-level to the module, this is always an empty object.

Returns:

An arbitrary JSON-encoded value.

Return type:

JSON

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async parent_name() → str

The name of the parent object of the function being called. If the function is top-level to the module, this is the name of the module.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async return_error(error: Error) → Void | None

Return an error from the function.

Parameters:

error – The error to return.

Returns:

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.

Return type:

Void | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async return_value(value: JSON) → Void | None

Set the return value of the function call to the provided value.

Parameters:

value – JSON serialization of the return value.

Returns:

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.

Return type:

Void | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.FunctionCallArgValue(ctx: Context)

Bases: Type

A value passed as a named argument to a function call.

async id() → str

A unique identifier for this FunctionCallArgValue.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the argument.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async value() → JSON

The value of the argument represented as a JSON serialized string.

Returns:

An arbitrary JSON-encoded value.

Return type:

JSON

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.FunctionCallArgValueID

Bases: Scalar

A unique identifier for an object.

class dagger.FunctionCallID

Bases: Scalar

A unique identifier for an object.

class dagger.FunctionID

Bases: Scalar

A unique identifier for an object.

class dagger.GeneratedCode(ctx: Context)

Bases: Type

The result of running an SDK’s codegen.

code() → Directory

The directory containing the generated code.

async id() → str

A unique identifier for this GeneratedCode.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async vcs_generated_paths() → list[str]

List of paths to mark generated in version control (i.e. .gitattributes).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async vcs_ignored_paths() → list[str]

List of paths to ignore in version control (i.e. .gitignore).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_(cb: Callable[[GeneratedCode], GeneratedCode]) → GeneratedCode

Call the provided callable with current GeneratedCode.

This is useful for reusability and readability by not breaking the calling chain.

with_vcs_generated_paths(paths: list[str]) → Self

Set the list of paths to mark generated in version control.

with_vcs_ignored_paths(paths: list[str]) → Self

Set the list of paths to ignore in version control.

class dagger.GeneratedCodeID

Bases: Scalar

A unique identifier for an object.

class dagger.Generator(ctx: Context)

Bases: Type

changes() → Changeset

The generated changeset from the last run

async completed() → bool

Whether the generator complete

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async description() → str

Return the description of the generator

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Generator.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async is_empty() → bool

Whether changeset from the last generator run is empty or not

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

Return the fully qualified name of the generator

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

original_module() → Module

The original module in which the generator has been defined

async path() → list[str]

The path of the generator within its module

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

run() → Self

Execute the generator

with_(cb: Callable[[Generator], Generator]) → Generator

Call the provided callable with current Generator.

This is useful for reusability and readability by not breaking the calling chain.

class dagger.GeneratorGroup(ctx: Context)

Bases: Type

changes(*, on_conflict: ChangesetsMergeConflict | None = ChangesetsMergeConflict.FAIL_EARLY) → Changeset

The combined changes from the last run of the generators

If any conflict occurs, for instance if the same file is modified by multiple generators, or if a file is both modified and deleted, an error is raised and the merge of the changesets will failed.

Set ‘continueOnConflicts’ flag to force to merge the changes in a ‘last write wins’ strategy.

Parameters:

on_conflict – Strategy to apply on conflicts between generators

async id() → str

A unique identifier for this GeneratorGroup.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async is_empty() → bool

Whether the generated changeset from the last run is empty or not

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async list_() → list[Generator]

Return a list of individual generators and their details

run() → Self

Execute all selected generators

with_(cb: Callable[[GeneratorGroup], GeneratorGroup]) → GeneratorGroup

Call the provided callable with current GeneratorGroup.

This is useful for reusability and readability by not breaking the calling chain.

class dagger.GeneratorGroupID

Bases: Scalar

A unique identifier for an object.

class dagger.GeneratorID

Bases: Scalar

A unique identifier for an object.

class dagger.GitRef(ctx: Context)

Bases: Type

A git ref (tag, branch, or commit).

async commit() → str

The resolved commit id at this ref.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

common_ancestor(other: Self) → Self

Find the best common ancestor between this ref and another ref.

Parameters:

other – The other ref to compare against.

async id() → str

A unique identifier for this GitRef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async ref() → str

The resolved ref name at this ref.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

tree(*, discard_git_dir: bool | None = False, depth: int | None = 1, include_tags: bool | None = False) → Directory

The filesystem tree at this ref.

Parameters:

• discard_git_dir – Set to true to discard .git directory.

• depth – The depth of the tree to fetch.

• include_tags – Set to true to populate tag refs in the local checkout .git.

with_(cb: Callable[[GitRef], GitRef]) → GitRef

Call the provided callable with current GitRef.

This is useful for reusability and readability by not breaking the calling chain.

class dagger.GitRefID

Bases: Scalar

A unique identifier for an object.

class dagger.GitRepository(ctx: Context)

Bases: Type

A git repository.

branch(name: str) → GitRef

Returns details of a branch.

Parameters:

name – Branch’s name (e.g., “main”).

async branches(*, patterns: list[str] | None = None) → list[str]

branches that match any of the given glob patterns.

Parameters:

patterns – Glob patterns (e.g., “refs/tags/v*”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

commit(id: str) → GitRef

Returns details of a commit.

Parameters:

id – Identifier of the commit (e.g., “b6315d8f2810962c601af73f86831f6866ea798b”).

head() → GitRef

Returns details for HEAD.

async id() → str

A unique identifier for this GitRepository.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

latest_version() → GitRef

Returns details for the latest semver tag.

ref(name: str) → GitRef

Returns details of a ref.

Parameters:

name – Ref’s name (can be a commit identifier, a tag name, a branch name, or a fully-qualified ref).

tag(name: str) → GitRef

Returns details of a tag.

Parameters:

name – Tag’s name (e.g., “v0.3.9”).

async tags(*, patterns: list[str] | None = None) → list[str]

tags that match any of the given glob patterns.

Parameters:

patterns – Glob patterns (e.g., “refs/tags/v*”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

uncommitted() → Changeset

Returns the changeset of uncommitted changes in the git repository.

async url() → str | None

The URL of the git repository.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.GitRepositoryID

Bases: Scalar

A unique identifier for an object.

class dagger.HTTPState(ctx: Context)

Bases: Type

An internal persistent HTTP state.

async id() → str

A unique identifier for this HTTPState.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.HTTPStateID

Bases: Scalar

A unique identifier for an object.

class dagger.HealthcheckConfig(ctx: Context)

Bases: Type

Image healthcheck configuration.

async args() → list[str]

Healthcheck command arguments.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this HealthcheckConfig.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async interval() → str

Interval between running healthcheck. Example:30s

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async retries() → int

The maximum number of consecutive failures before the container is marked as unhealthy. Example:3

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async shell() → bool

Healthcheck command is a shell command.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async start_interval() → str

StartInterval configures the duration between checks during the startup phase. Example:5s

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async start_period() → str

StartPeriod allows for failures during this initial startup period which do not count towards maximum number of retries. Example:0s

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async timeout() → str

Healthcheck timeout. Example:3s

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.HealthcheckConfigID

Bases: Scalar

A unique identifier for an object.

class dagger.Host(ctx: Context)

Bases: Type

Information about the host environment.

container_image(name: str) → Container

Accesses a container image on the host.

Parameters:

name – Name of the image to access.

directory(path: str, *, exclude: list[str] | None = None, include: list[str] | None = None, no_cache: bool | None = False, gitignore: bool | None = False) → Directory

Accesses a directory on the host.

Parameters:

• path – Location of the directory to access (e.g., “.”).

• exclude – Exclude artifacts that match the given pattern (e.g., [“node_modules/”, “.git*”]).

• include – Include only artifacts that match the given pattern (e.g., [“app/”, “package.*”]).

• no_cache – If true, the directory will always be reloaded from the host.

• gitignore – Apply .gitignore filter rules inside the directory

file(path: str, *, no_cache: bool | None = False) → File

Accesses a file on the host.

Parameters:

• path – Location of the file to retrieve (e.g., “README.md”).

• no_cache – If true, the file will always be reloaded from the host.

async find_up(name: str, *, no_cache: bool | None = False) → str | None

Search for a file or directory by walking up the tree from system workdir. Return its relative path. If no match, return null

Parameters:

• name – name of the file or directory to search for

• no_cache

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Host.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

service(ports: list[PortForward], *, host: str | None = 'localhost') → Service

Creates a service that forwards traffic to a specified address via the host.

Parameters:

• ports – Ports to expose via the service, forwarding through the host network. If a port’s frontend is unspecified or 0, it defaults to the same as the backend port. An empty set of ports is not valid; an error will be returned.

• host – Upstream host to forward traffic to.

tunnel(service: Service, *, native: bool | None = False, ports: list[PortForward] | None = None) → Service

Creates a tunnel that forwards traffic from the host to a service.

Parameters:

• service – Service to send traffic from the tunnel.

• native – Map each service port to the same port on the host, as if the service were running natively. Note: enabling may result in port conflicts.

• ports – Configure explicit port forwarding rules for the tunnel. If a port’s frontend is unspecified or 0, a random port will be chosen by the host. If no ports are given, all of the service’s ports are forwarded. If native is true, each port maps to the same port on the host. If native is false, each port maps to a random port chosen by the host. If ports are given and native is true, the ports are additive.

unix_socket(path: str) → Socket

Accesses a Unix socket on the host.

Parameters:

path – Location of the Unix socket (e.g., “/var/run/docker.sock”).

class dagger.HostID

Bases: Scalar

A unique identifier for an object.

class dagger.ImageLayerCompression(*values)

Bases: Enum

Compression algorithm to use for image layers.

ESTARGZ = 'EStarGZ'

EStarGZ = 'EStarGZ'

GZIP = 'Gzip'

Gzip = 'Gzip'

UNCOMPRESSED = 'Uncompressed'

Uncompressed = 'Uncompressed'

ZSTD = 'Zstd'

Zstd = 'Zstd'

class dagger.ImageMediaTypes(*values)

Bases: Enum

Mediatypes to use in published or exported image metadata.

DOCKER = 'DockerMediaTypes'

DockerMediaTypes = 'DockerMediaTypes'

OCI = 'OCIMediaTypes'

OCIMediaTypes = 'OCIMediaTypes'

class dagger.InputTypeDef(ctx: Context)

Bases: Type

A graphql input type, which is essentially just a group of named args. This is currently only used to represent pre-existing usage of graphql input types in the core API. It is not used by user modules and shouldn’t ever be as user module accept input objects via their id rather than graphql input types.

async fields() → list[FieldTypeDef]

Static fields defined on this input object, if any.

async id() → str

A unique identifier for this InputTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the input object.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.InputTypeDefID

Bases: Scalar

A unique identifier for an object.

class dagger.InterfaceTypeDef(ctx: Context)

Bases: Type

A definition of a custom interface defined in a Module.

async description() → str

The doc string for the interface, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async functions() → list[Function]

Functions defined on this interface, if any.

async id() → str

A unique identifier for this InterfaceTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the interface.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

source_map() → SourceMap

The location of this interface declaration.

async source_module_name() → str

If this InterfaceTypeDef is associated with a Module, the name of the module. Unset otherwise.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.InterfaceTypeDefID

Bases: Scalar

A unique identifier for an object.

class dagger.JSON

Bases: Scalar

An arbitrary JSON-encoded value.

class dagger.JSONValue(ctx: Context)

Bases: Type

async as_array() → list[JSONValue]

Decode an array from json

async as_boolean() → bool

Decode a boolean from json

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async as_integer() → int

Decode an integer from json

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async as_string() → str

Decode a string from json

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async contents(*, pretty: bool | None = False, indent: str | None = '  ') → JSON

Return the value encoded as json

Parameters:

• pretty – Pretty-print

• indent – Optional line prefix

Returns:

An arbitrary JSON-encoded value.

Return type:

JSON

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

field(path: list[str]) → Self

Lookup the field at the given path, and return its value.

Parameters:

path – Path of the field to lookup, encoded as an array of field names

async fields() → list[str]

List fields of the encoded object

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this JSONValue.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

new_boolean(value: bool) → Self

Encode a boolean to json

Parameters:

value – New boolean value

new_integer(value: int) → Self

Encode an integer to json

Parameters:

value – New integer value

new_string(value: str) → Self

Encode a string to json

Parameters:

value – New string value

with_(cb: Callable[[JSONValue], JSONValue]) → JSONValue

Call the provided callable with current JSONValue.

This is useful for reusability and readability by not breaking the calling chain.

with_contents(contents: JSON) → Self

Return a new json value, decoded from the given content

Parameters:

contents – New JSON-encoded contents

with_field(path: list[str], value: Self) → Self

Set a new field at the given path

Parameters:

• path – Path of the field to set, encoded as an array of field names

• value – The new value of the field

class dagger.JSONValueID

Bases: Scalar

A unique identifier for an object.

class dagger.LLM(ctx: Context)

Bases: Type

attempt(number: int) → Self

create a branch in the LLM’s history

bind_result(name: str) → Binding

returns the type of the current state

env() → Env

return the LLM’s current environment

async has_prompt() → bool

Indicates whether there are any queued prompts or tool results to send to the model

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async history() → list[str]

return the llm message history

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async history_json() → JSON

return the raw llm message history as json

Returns:

An arbitrary JSON-encoded value.

Return type:

JSON

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this LLM.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async last_reply() → str

return the last llm reply from the history

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

loop() → Self

Submit the queued prompt, evaluate any tool calls, queue their results, and keep going until the model ends its turn

async model() → str

return the model used by the llm

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async provider() → str

return the provider used by the llm

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async step() → Self

Submit the queued prompt or tool call results, evaluate any tool calls, and queue their results

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async sync() → Self

synchronize LLM state

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

token_usage() → LLMTokenUsage

returns the token usage of the current state

async tools() → str

print documentation for available tools

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_(cb: Callable[[LLM], LLM]) → LLM

Call the provided callable with current LLM.

This is useful for reusability and readability by not breaking the calling chain.

with_blocked_function(type_name: str, function: str) → Self

Return a new LLM with the specified function no longer exposed as a tool

Parameters:

• type_name – The type name whose function will be blocked

• function – The function to block Will be converted to lowerCamelCase if necessary.

with_env(env: Env) → Self

allow the LLM to interact with an environment via MCP

with_mcp_server(name: str, service: Service) → Self

Add an external MCP server to the LLM

Parameters:

• name – The name of the MCP server

• service – The MCP service to run and communicate with over stdio

with_model(model: str) → Self

swap out the llm model

Parameters:

model – The model to use

with_prompt(prompt: str) → Self

append a prompt to the llm context

Parameters:

prompt – The prompt to send

with_prompt_file(file: File) → Self

append the contents of a file to the llm context

Parameters:

file – The file to read the prompt from

with_static_tools() → Self

Use a static set of tools for method calls, e.g. for MCP clients that do not support dynamic tool registration

with_system_prompt(prompt: str) → Self

Add a system prompt to the LLM’s environment

Parameters:

prompt – The system prompt to send

without_default_system_prompt() → Self

Disable the default system prompt

without_message_history() → Self

Clear the message history, leaving only the system prompts

without_system_prompts() → Self

Clear the system prompts, leaving only the default system prompt

class dagger.LLMID

Bases: Scalar

A unique identifier for an object.

class dagger.LLMTokenUsage(ctx: Context)

Bases: Type

async cached_token_reads() → int

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async cached_token_writes() → int

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this LLMTokenUsage.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async input_tokens() → int

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async output_tokens() → int

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async total_tokens() → int

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.LLMTokenUsageID

Bases: Scalar

A unique identifier for an object.

class dagger.Label(ctx: Context)

Bases: Type

A simple key value object that represents a label.

async id() → str

A unique identifier for this Label.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The label name.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async value() → str

The label value.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.LabelID

Bases: Scalar

A unique identifier for an object.

class dagger.ListTypeDef(ctx: Context)

Bases: Type

A definition of a list type in a Module.

element_type_def() → TypeDef

The type of the elements in the list.

async id() → str

A unique identifier for this ListTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.ListTypeDefID

Bases: Scalar

A unique identifier for an object.

class dagger.Module(ctx: Context)

Bases: Type

A Dagger module.

check(name: str) → Check

Return the check defined by the module with the given name. Must match to exactly one check.

Caution

Experimental: This API is highly experimental and may be removed or replaced entirely.

Parameters:

name – The name of the check to retrieve

checks(*, include: list[str] | None = None, no_generate: bool | None = None) → CheckGroup

Return all checks defined by the module

Caution

Experimental: This API is highly experimental and may be removed or replaced entirely.

Parameters:

• include – Only include checks matching the specified patterns

• no_generate – When true, only return annotated check functions; exclude generate-as-checks

async dependencies() → list[Module]

The dependencies of the module.

async description() → str

The doc string of the module, if any

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async enums() → list[TypeDef]

Enumerations served by this module.

generated_context_directory() → Directory

The generated files and directories made on top of the module source’s context directory.

generator(name: str) → Generator

Return the generator defined by the module with the given name. Must match to exactly one generator.

Caution

Experimental: This API is highly experimental and may be removed or replaced entirely.

Parameters:

name – The name of the generator to retrieve

generators(*, include: list[str] | None = None) → GeneratorGroup

Return all generators defined by the module

Caution

Experimental: This API is highly experimental and may be removed or replaced entirely.

Parameters:

include – Only include generators matching the specified patterns

async id() → str

A unique identifier for this Module.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async interfaces() → list[TypeDef]

Interfaces served by this module.

introspection_schema_json() → File

The introspection schema JSON file for this module.

This file represents the schema visible to the module’s source code, including all core types and those from the dependencies.

Note: this is in the context of a module, so some core types may be hidden.

async name() → str

The name of the module

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async objects() → list[TypeDef]

Objects served by this module.

runtime() → Container

The container that runs the module’s entrypoint. It will fail to execute if the module doesn’t compile.

sdk() → SDKConfig

The SDK config used by this module.

async serve(*, include_dependencies: bool | None = None, entrypoint: bool | None = None) → Void | None

Serve a module’s API in the current session.

Note: this can only be called once per session. In the future, it could return a stream or service to remove the side effect.

Parameters:

• include_dependencies – Expose the dependencies of this module to the client

• entrypoint – Install the module as the entrypoint, promoting its main-object methods onto the Query root

Returns:

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.

Return type:

Void | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

services(*, include: list[str] | None = None) → UpGroup

Return all services defined by the module

Caution

Experimental: This API is highly experimental and may be removed or replaced entirely.

Parameters:

include – Only include services matching the specified patterns

source() → ModuleSource

The source for the module.

async sync() → Self

Forces evaluation of the module, including any loading into the engine and associated validation.

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

user_defaults() → EnvFile

User-defined default values, loaded from local .env files.

with_(cb: Callable[[Module], Module]) → Module

Call the provided callable with current Module.

This is useful for reusability and readability by not breaking the calling chain.

with_description(description: str) → Self

Retrieves the module with the given description

Parameters:

description – The description to set

with_enum(enum: TypeDef) → Self

This module plus the given Enum type and associated values

with_interface(iface: TypeDef) → Self

This module plus the given Interface type and associated functions

with_object(object: TypeDef) → Self

This module plus the given Object type and associated functions.

class dagger.ModuleConfigClient(ctx: Context)

Bases: Type

The client generated for the module.

async directory() → str

The directory the client is generated in.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async generator() → str

The generator to use

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this ModuleConfigClient.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.ModuleConfigClientID

Bases: Scalar

A unique identifier for an object.

class dagger.ModuleID

Bases: Scalar

A unique identifier for an object.

class dagger.ModuleSource(ctx: Context)

Bases: Type

The source needed to load and run a module, along with any metadata about the source such as versions/urls/etc.

as_module() → Module

Load the source as a module. If this is a local source, the parent directory must have been provided during module source creation

async as_string() → str

A human readable ref string representation of this module source.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

blueprint() → Self

The blueprint referenced by the module source.

async clone_ref() → str

The ref to clone the root of the git repo from. Only valid for git sources.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async commit() → str

The resolved commit of the git repo this source points to.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async config_clients() → list[ModuleConfigClient]

The clients generated for the module.

async config_exists() → bool

Whether an existing dagger.json for the module was found.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

context_directory() → Directory

The full directory loaded for the module source, including the source code as a subdirectory.

async dependencies() → list[ModuleSource]

The dependencies of the module source.

async digest() → str

A content-hash of the module source. Module sources with the same digest will output the same generated context and convert into the same module instance.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

directory(path: str) → Directory

The directory containing the module configuration and source code (source code may be in a subdir).

Parameters:

path – A subpath from the source directory to select.

async engine_version() → str

The engine version of the module.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

generated_context_changeset() → Changeset

The generated files and directories made on top of the module source’s context directory, returned as a Changeset.

generated_context_directory() → Directory

The generated files and directories made on top of the module source’s context directory.

async html_repo_url() → str

The URL to access the web view of the repository (e.g., GitHub, GitLab, Bitbucket).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async html_url() → str

The URL to the source’s git repo in a web browser. Only valid for git sources.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this ModuleSource.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

introspection_schema_json() → File

The introspection schema JSON file for this module source.

This file represents the schema visible to the module’s source code, including all core types and those from the dependencies.

Note: this is in the context of a module, so some core types may be hidden.

async kind() → ModuleSourceKind

The kind of module source (currently local, git or dir).

Returns:

The kind of module source.

Return type:

ModuleSourceKind

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async local_context_directory_path() → str

The full absolute path to the context directory on the caller’s host filesystem that this module source is loaded from. Only valid for local module sources.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async module_name() → str

The name of the module, including any setting via the withName API.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async module_original_name() → str

The original name of the module as read from the module’s dagger.json (or set for the first time with the withName API).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async original_subpath() → str

The original subpath used when instantiating this module source, relative to the context directory.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async pin() → str

The pinned version of this module source.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async repo_root_path() → str

The import path corresponding to the root of the git repo this source points to. Only valid for git sources.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

sdk() → SDKConfig

The SDK configuration of the module.

async source_root_subpath() → str

The path, relative to the context directory, that contains the module’s dagger.json.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async source_subpath() → str

The path to the directory containing the module’s source code, relative to the context directory.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async sync() → Self

Forces evaluation of the module source, including any loading into the engine and associated validation.

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async toolchains() → list[ModuleSource]

The toolchains referenced by the module source.

user_defaults() → EnvFile

User-defined defaults read from local .env files

async version() → str

The specified version of the git repo this source points to.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_(cb: Callable[[ModuleSource], ModuleSource]) → ModuleSource

Call the provided callable with current ModuleSource.

This is useful for reusability and readability by not breaking the calling chain.

with_blueprint(blueprint: Self) → Self

Set a blueprint for the module source.

Parameters:

blueprint – The blueprint module to set.

with_client(generator: str, output_dir: str) → Self

Update the module source with a new client to generate.

Parameters:

• generator – The generator to use

• output_dir – The output directory for the generated client.

with_dependencies(dependencies: list[ModuleSource]) → Self

Append the provided dependencies to the module source’s dependency list.

Parameters:

dependencies – The dependencies to append.

with_engine_version(version: str) → Self

Upgrade the engine version of the module to the given value.

Parameters:

version – The engine version to upgrade to.

with_experimental_features(features: list[ModuleSourceExperimentalFeature]) → Self

Enable the experimental features for the module source.

Parameters:

features – The experimental features to enable.

with_includes(patterns: list[str]) → Self

Update the module source with additional include patterns for files+directories from its context that are required for building it

Parameters:

patterns – The new additional include patterns.

with_name(name: str) → Self

Update the module source with a new name.

Parameters:

name – The name to set.

with_sdk(source: str) → Self

Update the module source with a new SDK.

Parameters:

source – The SDK source to set.

with_source_subpath(path: str) → Self

Update the module source with a new source subpath.

Parameters:

path – The path to set as the source subpath. Must be relative to the module source’s source root directory.

with_toolchains(toolchains: list[ModuleSource]) → Self

Add toolchains to the module source.

Parameters:

toolchains – The toolchain modules to add.

with_update_blueprint() → Self

Update the blueprint module to the latest version.

with_update_dependencies(dependencies: list[str]) → Self

Update one or more module dependencies.

Parameters:

dependencies – The dependencies to update.

with_update_toolchains(toolchains: list[str]) → Self

Update one or more toolchains.

Parameters:

toolchains – The toolchains to update.

with_updated_clients(clients: list[str]) → Self

Update one or more clients.

Parameters:

clients – The clients to update

without_blueprint() → Self

Remove the current blueprint from the module source.

without_client(path: str) → Self

Remove a client from the module source.

Parameters:

path – The path of the client to remove.

without_dependencies(dependencies: list[str]) → Self

Remove the provided dependencies from the module source’s dependency list.

Parameters:

dependencies – The dependencies to remove.

without_experimental_features(features: list[ModuleSourceExperimentalFeature]) → Self

Disable experimental features for the module source.

Parameters:

features – The experimental features to disable.

without_toolchains(toolchains: list[str]) → Self

Remove the provided toolchains from the module source.

Parameters:

toolchains – The toolchains to remove.

class dagger.ModuleSourceExperimentalFeature(*values)

Bases: Enum

Experimental features of a module

SELF_CALLS = 'SELF_CALLS'

class dagger.ModuleSourceID

Bases: Scalar

A unique identifier for an object.

class dagger.ModuleSourceKind(*values)

Bases: Enum

The kind of module source.

DIR = 'DIR_SOURCE'

DIR_SOURCE = 'DIR_SOURCE'

GIT = 'GIT_SOURCE'

GIT_SOURCE = 'GIT_SOURCE'

LOCAL = 'LOCAL_SOURCE'

LOCAL_SOURCE = 'LOCAL_SOURCE'

class dagger.NetworkProtocol(*values)

Bases: Enum

Transport layer network protocol associated to a port.

TCP = 'TCP'

UDP = 'UDP'

class dagger.Node(*args, **kwargs)

Bases: Protocol

An object with a globally unique ID.

class dagger.ObjectTypeDef(ctx: Context)

Bases: Type

A definition of a custom object defined in a Module.

constructor() → Function

The function used to construct new instances of this object, if any.

async deprecated() → str | None

The reason this enum member is deprecated, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async description() → str

The doc string for the object, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async fields() → list[FieldTypeDef]

Static fields defined on this object, if any.

async functions() → list[Function]

Functions defined on this object, if any.

async id() → str

A unique identifier for this ObjectTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the object.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

source_map() → SourceMap

The location of this object declaration.

async source_module_name() → str

If this ObjectTypeDef is associated with a Module, the name of the module. Unset otherwise.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.ObjectTypeDefID

Bases: Scalar

A unique identifier for an object.

class dagger.PipelineLabel(name: str, value: str)

Bases: Input

Key value object that represents a pipeline label.

name: str

value: str

class dagger.Platform

Bases: Scalar

The platform config OS and architecture in a Container. The format is [os]/[platform]/[version] (e.g., “darwin/arm64/v7”, “windows/amd64”, “linux/arm64”).

class dagger.Port(ctx: Context)

Bases: Type

A port exposed by a container.

async description() → str | None

The port description.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async experimental_skip_healthcheck() → bool

Skip the health check when run as a service.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Port.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async port() → int

The port number.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async protocol() → NetworkProtocol

The transport layer protocol.

Returns:

Transport layer network protocol associated to a port.

Return type:

NetworkProtocol

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.PortForward(backend: int, frontend: int | None = None, protocol: NetworkProtocol | None = NetworkProtocol.TCP)

Bases: Input

Port forwarding rules for tunneling network traffic.

backend: int

frontend: int | None

protocol: NetworkProtocol | None

class dagger.PortID

Bases: Scalar

A unique identifier for an object.

class dagger.Query(ctx: Context | None = None)

Bases: Root

The root of the DAG.

address(value: str) → Address

initialize an address to load directories, containers, secrets or other object types.

cache_volume(key: str, *, source: Directory | None = None, sharing: CacheSharingMode | None = CacheSharingMode.SHARED, owner: str | None = '') → CacheVolume

Constructs a cache volume for a given cache key.

Parameters:

• key – A string identifier to target this cache volume (e.g., “modules- cache”).

• source – Identifier of the directory to use as the cache volume’s root.

• sharing – Sharing mode of the cache volume.

• owner – A user:group to set for the cache volume root. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

changeset() → Changeset

Creates an empty changeset

cloud() → Cloud

Dagger Cloud configuration and state

container(*, platform: Platform | None = None) → Container

Creates a scratch container, with no image or metadata.

To pull an image, follow up with the “from” function.

Parameters:

platform – Platform to initialize the container with. Defaults to the native platform of the current engine

current_env() → Env

Returns the current environment

When called from a function invoked via an LLM tool call, this will be the LLM’s current environment, including any modifications made through calling tools. Env values returned by functions become the new environment for subsequent calls, and Changeset values returned by functions are applied to the environment’s workspace.

When called from a module function outside of an LLM, this returns an Env with the current module installed, and with the current module’s source directory as its workspace.

Caution

Experimental: Programmatic env access is speculative and might be replaced.

current_function_call() → FunctionCall

The FunctionCall context that the SDK caller is currently executing in.

If the caller is not currently executing in a function, this will return an error.

current_module() → CurrentModule

The module currently being served in the session, if any.

async current_type_defs(*, return_all_types: bool | None = False, hide_core: bool | None = None) → list[TypeDef]

The TypeDef representations of the objects currently being served in the session.

Parameters:

• return_all_types – Return the full referenced typedef closure instead of only top- level served typedefs.

• hide_core – Strip core API functions from the Query type, leaving only module- sourced functions (constructors, entrypoint proxies, etc.). Core types (Container, Directory, etc.) are kept so return types and method chaining still work.

current_workspace() → Workspace

Detect and return the current workspace.

Caution

Experimental: Highly experimental API extracted from a more ambitious workspace implementation.

async default_platform() → Platform

The default platform of the engine.

Returns:

The platform config OS and architecture in a Container. The format is [os]/[platform]/[version] (e.g., “darwin/arm64/v7”, “windows/amd64”, “linux/arm64”).

Return type:

Platform

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

directory() → Directory

Creates an empty directory.

engine() → Engine

The Dagger engine container configuration and state

env(*, privileged: bool | None = False, writable: bool | None = False) → Env

Initializes a new environment

Caution

Experimental: Environments are not yet stabilized

Parameters:

• privileged – Give the environment the same privileges as the caller: core API including host access, current module, and dependencies

• writable – Allow new outputs to be declared and saved in the environment

env_file(*, expand: bool | None = None) → EnvFile

Initialize an environment file

Parameters:

expand – Replace “${VAR}” or “$VAR” with the value of other vars .. deprecated:: Variable expansion is now enabled by default

error(message: str) → Error

Create a new error.

Parameters:

message – A brief description of the error.

file(name: str, contents: str, *, permissions: int | None = 420) → File

Creates a file with the specified contents.

Parameters:

• name – Name of the new file. Example: “foo.txt”

• contents – Contents of the new file. Example: “Hello world!”

• permissions – Permissions of the new file. Example: 0600

function(name: str, return_type: TypeDef) → Function

Creates a function.

Parameters:

• name – Name of the function, in its original format from the implementation language.

• return_type – Return type of the function.

generated_code(code: Directory) → GeneratedCode

Create a code generation result, given a directory containing the generated code.

git(url: str, *, keep_git_dir: bool | None = True, ssh_known_hosts: str | None = '', ssh_auth_socket: Socket | None = None, http_auth_username: str | None = '', http_auth_token: Secret | None = None, http_auth_header: Secret | None = None, experimental_service_host: Service | None = None) → GitRepository

Queries a Git repository.

Parameters:

• url – URL of the git repository. Can be formatted as https://{host}/{owner}/{repo}, git@{host}:{owner}/{repo}. Suffix “.git” is optional.

• keep_git_dir – DEPRECATED: Set to true to keep .git directory. .. deprecated:: Set to true to keep .git directory.

• ssh_known_hosts – Set SSH known hosts

• ssh_auth_socket – Set SSH auth socket

• http_auth_username – Username used to populate the password during basic HTTP Authorization

• http_auth_token – Secret used to populate the password during basic HTTP Authorization

• http_auth_header – Secret used to populate the Authorization HTTP header

• experimental_service_host – A service which must be started before the repo is fetched.

host() → Host

Queries the host environment.

http(url: str, *, name: str | None = None, permissions: int | None = None, checksum: str | None = None, auth_header: Secret | None = None, experimental_service_host: Service | None = None) → File

Returns a file containing an http remote url content.

Parameters:

• url – HTTP url to get the content from (e.g., “https://docs.dagger.io”).

• name – File name to use for the file. Defaults to the last part of the URL.

• permissions – Permissions to set on the file.

• checksum – Expected digest of the downloaded content (e.g., “sha256:…”).

• auth_header – Secret used to populate the Authorization HTTP header

• experimental_service_host – A service which must be started before the URL is fetched.

async id() → str

A unique identifier for this Query.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

json() → JSONValue

Initialize a JSON value

llm(*, model: str | None = None, max_api_calls: int | None = None) → LLM

Initialize a Large Language Model (LLM)

Caution

Experimental: LLM support is not yet stabilized

Parameters:

• model – Model to use

• max_api_calls – Cap the number of API calls for this LLM

load_address_from_id(id: AddressID) → Address

Load a Address from its ID.

load_binding_from_id(id: BindingID) → Binding

Load a Binding from its ID.

load_cache_volume_from_id(id: CacheVolumeID) → CacheVolume

Load a CacheVolume from its ID.

load_changeset_from_id(id: ChangesetID) → Changeset

Load a Changeset from its ID.

load_check_from_id(id: CheckID) → Check

Load a Check from its ID.

load_check_group_from_id(id: CheckGroupID) → CheckGroup

Load a CheckGroup from its ID.

load_client_filesync_mirror_from_id(id: ClientFilesyncMirrorID) → ClientFilesyncMirror

Load a ClientFilesyncMirror from its ID.

load_cloud_from_id(id: CloudID) → Cloud

Load a Cloud from its ID.

load_container_from_id(id: ContainerID) → Container

Load a Container from its ID.

load_current_module_from_id(id: CurrentModuleID) → CurrentModule

Load a CurrentModule from its ID.

load_diff_stat_from_id(id: DiffStatID) → DiffStat

Load a DiffStat from its ID.

load_directory_from_id(id: DirectoryID) → Directory

Load a Directory from its ID.

load_engine_cache_entry_from_id(id: EngineCacheEntryID) → EngineCacheEntry

Load a EngineCacheEntry from its ID.

load_engine_cache_entry_set_from_id(id: EngineCacheEntrySetID) → EngineCacheEntrySet

Load a EngineCacheEntrySet from its ID.

load_engine_cache_from_id(id: EngineCacheID) → EngineCache

Load a EngineCache from its ID.

load_engine_from_id(id: EngineID) → Engine

Load a Engine from its ID.

load_enum_type_def_from_id(id: EnumTypeDefID) → EnumTypeDef

Load a EnumTypeDef from its ID.

load_enum_value_type_def_from_id(id: EnumValueTypeDefID) → EnumValueTypeDef

Load a EnumValueTypeDef from its ID.

load_env_file_from_id(id: EnvFileID) → EnvFile

Load a EnvFile from its ID.

load_env_from_id(id: EnvID) → Env

Load a Env from its ID.

load_env_variable_from_id(id: EnvVariableID) → EnvVariable

Load a EnvVariable from its ID.

load_error_from_id(id: ErrorID) → Error

Load a Error from its ID.

load_error_value_from_id(id: ErrorValueID) → ErrorValue

Load a ErrorValue from its ID.

load_exportable_from_id(id: ExportableID) → Exportable

Load a Exportable from its ID.

load_field_type_def_from_id(id: FieldTypeDefID) → FieldTypeDef

Load a FieldTypeDef from its ID.

load_file_from_id(id: FileID) → File

Load a File from its ID.

load_function_arg_from_id(id: FunctionArgID) → FunctionArg

Load a FunctionArg from its ID.

load_function_call_arg_value_from_id(id: FunctionCallArgValueID) → FunctionCallArgValue

Load a FunctionCallArgValue from its ID.

load_function_call_from_id(id: FunctionCallID) → FunctionCall

Load a FunctionCall from its ID.

load_function_from_id(id: FunctionID) → Function

Load a Function from its ID.

load_generated_code_from_id(id: GeneratedCodeID) → GeneratedCode

Load a GeneratedCode from its ID.

load_generator_from_id(id: GeneratorID) → Generator

Load a Generator from its ID.

load_generator_group_from_id(id: GeneratorGroupID) → GeneratorGroup

Load a GeneratorGroup from its ID.

load_git_ref_from_id(id: GitRefID) → GitRef

Load a GitRef from its ID.

load_git_repository_from_id(id: GitRepositoryID) → GitRepository

Load a GitRepository from its ID.

load_healthcheck_config_from_id(id: HealthcheckConfigID) → HealthcheckConfig

Load a HealthcheckConfig from its ID.

load_host_from_id(id: HostID) → Host

Load a Host from its ID.

load_http_state_from_id(id: HTTPStateID) → HTTPState

Load a HTTPState from its ID.

load_input_type_def_from_id(id: InputTypeDefID) → InputTypeDef

Load a InputTypeDef from its ID.

load_interface_type_def_from_id(id: InterfaceTypeDefID) → InterfaceTypeDef

Load a InterfaceTypeDef from its ID.

load_json_value_from_id(id: JSONValueID) → JSONValue

Load a JSONValue from its ID.

load_label_from_id(id: LabelID) → Label

Load a Label from its ID.

load_list_type_def_from_id(id: ListTypeDefID) → ListTypeDef

Load a ListTypeDef from its ID.

load_llm_from_id(id: LLMID) → LLM

Load a LLM from its ID.

load_llm_token_usage_from_id(id: LLMTokenUsageID) → LLMTokenUsage

Load a LLMTokenUsage from its ID.

load_module_config_client_from_id(id: ModuleConfigClientID) → ModuleConfigClient

Load a ModuleConfigClient from its ID.

load_module_from_id(id: ModuleID) → Module

Load a Module from its ID.

load_module_source_from_id(id: ModuleSourceID) → ModuleSource

Load a ModuleSource from its ID.

load_object_type_def_from_id(id: ObjectTypeDefID) → ObjectTypeDef

Load a ObjectTypeDef from its ID.

load_port_from_id(id: PortID) → Port

Load a Port from its ID.

load_remote_git_mirror_from_id(id: RemoteGitMirrorID) → RemoteGitMirror

Load a RemoteGitMirror from its ID.

load_scalar_type_def_from_id(id: ScalarTypeDefID) → ScalarTypeDef

Load a ScalarTypeDef from its ID.

load_sdk_config_from_id(id: SDKConfigID) → SDKConfig

Load a SDKConfig from its ID.

load_search_result_from_id(id: SearchResultID) → SearchResult

Load a SearchResult from its ID.

load_search_submatch_from_id(id: SearchSubmatchID) → SearchSubmatch

Load a SearchSubmatch from its ID.

load_secret_from_id(id: SecretID) → Secret

Load a Secret from its ID.

load_service_from_id(id: ServiceID) → Service

Load a Service from its ID.

load_socket_from_id(id: SocketID) → Socket

Load a Socket from its ID.

load_source_map_from_id(id: SourceMapID) → SourceMap

Load a SourceMap from its ID.

load_stat_from_id(id: StatID) → Stat

Load a Stat from its ID.

load_syncer_from_id(id: SyncerID) → Syncer

Load a Syncer from its ID.

load_terminal_from_id(id: TerminalID) → Terminal

Load a Terminal from its ID.

load_type_def_from_id(id: TypeDefID) → TypeDef

Load a TypeDef from its ID.

load_up_from_id(id: UpID) → Up

Load a Up from its ID.

load_up_group_from_id(id: UpGroupID) → UpGroup

Load a UpGroup from its ID.

load_workspace_from_id(id: WorkspaceID) → Workspace

Load a Workspace from its ID.

module() → Module

Create a new module.

module_source(ref_string: str, *, ref_pin: str | None = '', disable_find_up: bool | None = False, allow_not_exists: bool | None = False, require_kind: ModuleSourceKind | None = None) → ModuleSource

Create a new module source instance from a source ref string

Parameters:

• ref_string – The string ref representation of the module source

• ref_pin – The pinned version of the module source

• disable_find_up – If true, do not attempt to find dagger.json in a parent directory of the provided path. Only relevant for local module sources.

• allow_not_exists – If true, do not error out if the provided ref string is a local path and does not exist yet. Useful when initializing new modules in directories that don’t exist yet.

• require_kind – If set, error out if the ref string is not of the provided requireKind.

node(id: Type) → Node

Load any object by its ID.

secret(uri: str, *, cache_key: str | None = None) → Secret

Creates a new secret.

Parameters:

• uri – The URI of the secret store

• cache_key – If set, the given string will be used as the cache key for this secret. This means that any secrets with the same cache key will be considered equivalent in terms of cache lookups, even if they have different URIs or plaintext values. For example, two secrets with the same cache key provided as secret env vars to other wise equivalent containers will result in the container withExecs hitting the cache for each other. If not set, the cache key for the secret will be derived from its plaintext value as looked up when the secret is constructed.

set_secret(name: str, plaintext: str) → Secret

Sets a secret given a user defined name to its plaintext and returns the secret.

The plaintext value is limited to a size of 128000 bytes.

Parameters:

• name – The user defined name for this secret

• plaintext – The plaintext of the secret

source_map(filename: str, line: int, column: int) → SourceMap

Creates source map metadata.

Parameters:

• filename – The filename from the module source.

• line – The line number within the filename.

• column – The column number within the line.

type_def() → TypeDef

Create a new TypeDef.

async version() → str

Get the current Dagger Engine version.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.RemoteGitMirror(ctx: Context)

Bases: Type

An internal persistent bare git mirror.

async id() → str

A unique identifier for this RemoteGitMirror.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.RemoteGitMirrorID

Bases: Scalar

A unique identifier for an object.

class dagger.ReturnType(*values)

Bases: Enum

Expected return type of an execution

ANY = 'ANY'

FAILURE = 'FAILURE'

SUCCESS = 'SUCCESS'

class dagger.SDKConfig(ctx: Context)

Bases: Type

The SDK config of the module.

async debug() → bool

Whether to start the SDK runtime in debug mode with an interactive terminal.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this SDKConfig.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async source() → str

Source of the SDK. Either a name of a builtin SDK or a module source ref string pointing to the SDK’s implementation.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.SDKConfigID

Bases: Scalar

A unique identifier for an object.

class dagger.ScalarTypeDef(ctx: Context)

Bases: Type

A definition of a custom scalar defined in a Module.

async description() → str

A doc string for the scalar, if any.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this ScalarTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of the scalar.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async source_module_name() → str

If this ScalarTypeDef is associated with a Module, the name of the module. Unset otherwise.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.ScalarTypeDefID

Bases: Scalar

A unique identifier for an object.

class dagger.SearchResult(ctx: Context)

Bases: Type

async absolute_offset() → int

The byte offset of this line within the file.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async file_path() → str

The path to the file that matched.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this SearchResult.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async line_number() → int

The first line that matched.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async matched_lines() → str

The line content that matched.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async submatches() → list[SearchSubmatch]

Sub-match positions and content within the matched lines.

class dagger.SearchResultID

Bases: Scalar

A unique identifier for an object.

class dagger.SearchSubmatch(ctx: Context)

Bases: Type

async end() → int

The match’s end offset within the matched lines.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this SearchSubmatch.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async start() → int

The match’s start offset within the matched lines.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async text() → str

The matched text.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.SearchSubmatchID

Bases: Scalar

A unique identifier for an object.

class dagger.Secret(ctx: Context)

Bases: Type

A reference to a secret value, which can be handled more safely than the value itself.

async id() → str

A unique identifier for this Secret.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The name of this secret.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async plaintext() → str

The value of this secret.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async uri() → str

The URI of this secret.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.SecretID

Bases: Scalar

A unique identifier for an object.

class dagger.Service(ctx: Context)

Bases: Type

A content-addressed service providing TCP connectivity.

async endpoint(*, port: int | None = None, scheme: str | None = '') → str

Retrieves an endpoint that clients can use to reach this container.

If no port is specified, the first exposed port is used. If none exist an error is returned.

If a scheme is specified, a URL is returned. Otherwise, a host:port pair is returned.

Parameters:

• port – The exposed port number for the endpoint

• scheme – Return a URL with the given scheme, eg. http for http://

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async hostname() → str

Retrieves a hostname which can be used by clients to reach this container.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Service.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async ports() → list[Port]

Retrieves the list of ports provided by the service.

async start() → Self

Start the service and wait for its health checks to succeed.

Services bound to a Container do not need to be manually started.

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async stop(*, kill: bool | None = False) → Self

Stop the service.

Parameters:

kill – Immediately kill the service without waiting for a graceful exit

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async sync() → Self

Forces evaluation of the pipeline in the engine.

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

terminal(*, cmd: list[str] | None = None) → Self

async up(*, ports: list[PortForward] | None = None, random: bool | None = False) → Void | None

Creates a tunnel that forwards traffic from the caller’s network to this service.

Parameters:

• ports – List of frontend/backend port mappings to forward. Frontend is the port accepting traffic on the host, backend is the service port.

• random – Bind each tunnel port to a random port on the host.

Returns:

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.

Return type:

Void | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_(cb: Callable[[Service], Service]) → Service

Call the provided callable with current Service.

This is useful for reusability and readability by not breaking the calling chain.

with_hostname(hostname: str) → Self

Configures a hostname which can be used by clients within the session to reach this container.

Parameters:

hostname – The hostname to use.

class dagger.ServiceID

Bases: Scalar

A unique identifier for an object.

class dagger.Socket(ctx: Context)

Bases: Type

A Unix or TCP/IP socket that can be mounted into a container.

async id() → str

A unique identifier for this Socket.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.SocketID

Bases: Scalar

A unique identifier for an object.

class dagger.SourceMap(ctx: Context)

Bases: Type

Source location information.

async column() → int

The column number within the line.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async filename() → str

The filename from the module source.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this SourceMap.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async line() → int

The line number within the filename.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async module() → str

The module dependency this was declared in.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async url() → str

The URL to the file, if any. This can be used to link to the source map in the browser.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.SourceMapID

Bases: Scalar

A unique identifier for an object.

class dagger.Stat(ctx: Context)

Bases: Type

A file or directory status object.

async file_type() → FileType | None

file type

Returns:

File type.

Return type:

FileType | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Stat.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

file name

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async permissions() → int

permission bits

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async size() → int

file size

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.StatID

Bases: Scalar

A unique identifier for an object.

class dagger.Syncer(*args, **kwargs)

Bases: Protocol

An object that can be force-evaluated. Calling sync ensures that the object’s entire dependency DAG has been evaluated, returning the object’s ID once complete.

async sync() → Self

class dagger.SyncerID

Bases: Scalar

A unique identifier for an object.

class dagger.Terminal(ctx: Context)

Bases: Type

An interactive terminal that clients can connect to.

async id() → str

A unique identifier for this Terminal.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async sync() → Self

Forces evaluation of the pipeline in the engine.

It doesn’t run the default command if no exec has been set.

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

class dagger.TerminalID

Bases: Scalar

A unique identifier for an object.

class dagger.TypeDef(ctx: Context)

Bases: Type

A definition of a parameter or return type in a Module.

as_enum() → EnumTypeDef

If kind is ENUM, the enum-specific type definition. If kind is not ENUM, this will be null.

as_input() → InputTypeDef

If kind is INPUT, the input-specific type definition. If kind is not INPUT, this will be null.

as_interface() → InterfaceTypeDef

If kind is INTERFACE, the interface-specific type definition. If kind is not INTERFACE, this will be null.

as_list() → ListTypeDef

If kind is LIST, the list-specific type definition. If kind is not LIST, this will be null.

as_object() → ObjectTypeDef

If kind is OBJECT, the object-specific type definition. If kind is not OBJECT, this will be null.

as_scalar() → ScalarTypeDef

If kind is SCALAR, the scalar-specific type definition. If kind is not SCALAR, this will be null.

async id() → str

A unique identifier for this TypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async kind() → TypeDefKind

The kind of type this is (e.g. primitive, list, object).

Returns:

Distinguishes the different kinds of TypeDefs.

Return type:

TypeDefKind

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

The canonical non-optional name of the type.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async optional() → bool

Whether this type can be set to null. Defaults to false.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

with_(cb: Callable[[TypeDef], TypeDef]) → TypeDef

Call the provided callable with current TypeDef.

This is useful for reusability and readability by not breaking the calling chain.

with_constructor(function: Function) → Self

Adds a function for constructing a new instance of an Object TypeDef, failing if the type is not an object.

with_enum(name: str, *, description: str | None = '', source_map: SourceMap | None = None) → Self

Returns a TypeDef of kind Enum with the provided name.

Note that an enum’s values may be omitted if the intent is only to refer to an enum. This is how functions are able to return their own, or any other circular reference.

Parameters:

• name – The name of the enum

• description – A doc string for the enum, if any

• source_map – The source map for the enum definition.

with_enum_member(name: str, *, value: str | None = '', description: str | None = '', source_map: SourceMap | None = None, deprecated: str | None = None) → Self

Adds a static value for an Enum TypeDef, failing if the type is not an enum.

Parameters:

• name – The name of the member in the enum

• value – The value of the member in the enum

• description – A doc string for the member, if any

• source_map – The source map for the enum member definition.

• deprecated – If deprecated, the reason or migration path.

with_enum_value(value: str, *, description: str | None = '', source_map: SourceMap | None = None, deprecated: str | None = None) → Self

Adds a static value for an Enum TypeDef, failing if the type is not an enum.

Deprecated

Use with_enum_member() instead

Parameters:

• value – The name of the value in the enum

• description – A doc string for the value, if any

• source_map – The source map for the enum value definition.

• deprecated – If deprecated, the reason or migration path.

with_field(name: str, type_def: Self, *, description: str | None = '', source_map: SourceMap | None = None, deprecated: str | None = None) → Self

Adds a static field for an Object TypeDef, failing if the type is not an object.

Parameters:

• name – The name of the field in the object

• type_def – The type of the field

• description – A doc string for the field, if any

• source_map – The source map for the field definition.

• deprecated – If deprecated, the reason or migration path.

with_function(function: Function) → Self

Adds a function for an Object or Interface TypeDef, failing if the type is not one of those kinds.

with_interface(name: str, *, description: str | None = '', source_map: SourceMap | None = None) → Self

Returns a TypeDef of kind Interface with the provided name.

with_kind(kind: TypeDefKind) → Self

Sets the kind of the type.

with_list_of(element_type: Self) → Self

Returns a TypeDef of kind List with the provided type for its elements.

with_object(name: str, *, description: str | None = '', source_map: SourceMap | None = None, deprecated: str | None = None) → Self

Returns a TypeDef of kind Object with the provided name.

Note that an object’s fields and functions may be omitted if the intent is only to refer to an object. This is how functions are able to return their own object, or any other circular reference.

with_optional(optional: bool) → Self

Sets whether this type can be set to null.

with_scalar(name: str, *, description: str | None = '') → Self

Returns a TypeDef of kind Scalar with the provided name.

class dagger.TypeDefID

Bases: Scalar

A unique identifier for an object.

class dagger.TypeDefKind(*values)

Bases: Enum

Distinguishes the different kinds of TypeDefs.

BOOLEAN = 'BOOLEAN_KIND'

BOOLEAN_KIND = 'BOOLEAN_KIND'

ENUM = 'ENUM_KIND'

ENUM_KIND = 'ENUM_KIND'

FLOAT = 'FLOAT_KIND'

FLOAT_KIND = 'FLOAT_KIND'

INPUT = 'INPUT_KIND'

INPUT_KIND = 'INPUT_KIND'

INTEGER = 'INTEGER_KIND'

INTEGER_KIND = 'INTEGER_KIND'

INTERFACE = 'INTERFACE_KIND'

INTERFACE_KIND = 'INTERFACE_KIND'

LIST = 'LIST_KIND'

LIST_KIND = 'LIST_KIND'

OBJECT = 'OBJECT_KIND'

OBJECT_KIND = 'OBJECT_KIND'

SCALAR = 'SCALAR_KIND'

SCALAR_KIND = 'SCALAR_KIND'

STRING = 'STRING_KIND'

STRING_KIND = 'STRING_KIND'

VOID = 'VOID_KIND'

VOID_KIND = 'VOID_KIND'

class dagger.Up(ctx: Context)

Bases: Type

async description() → str

The description of the service

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Up.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async name() → str

Return the fully qualified name of the service

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

original_module() → Module

The original module in which the service has been defined

async path() → list[str]

The path of the service within its module

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

run() → Self

Execute the service function

with_(cb: Callable[[Up], Up]) → Up

Call the provided callable with current Up.

This is useful for reusability and readability by not breaking the calling chain.

class dagger.UpGroup(ctx: Context)

Bases: Type

async id() → str

A unique identifier for this UpGroup.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async list_() → list[Up]

Return a list of individual services and their details

run() → Self

Execute all selected service functions

with_(cb: Callable[[UpGroup], UpGroup]) → UpGroup

Call the provided callable with current UpGroup.

This is useful for reusability and readability by not breaking the calling chain.

class dagger.UpGroupID

Bases: Scalar

A unique identifier for an object.

class dagger.UpID

Bases: Scalar

A unique identifier for an object.

class dagger.Void

Bases: Scalar

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.

class dagger.Workspace(ctx: Context)

Bases: Type

A Dagger workspace detected from the current working directory.

async address() → str

Canonical Dagger address of the workspace directory.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

checks(*, include: list[str] | None = None, no_generate: bool | None = None, only_generate: bool | None = None) → CheckGroup

Return all checks from modules loaded in the workspace.

Parameters:

• include – Only include checks matching the specified patterns

• no_generate – When true, only return annotated check functions; exclude generate-as-checks

• only_generate – When true, only return generate-as-checks; exclude annotated check functions

async client_id() → str

The client ID that owns this workspace’s host filesystem.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async config_path() → str

Path to config.toml relative to the workspace boundary (empty if not initialized).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

directory(path: str, *, exclude: list[str] | None = None, include: list[str] | None = None, gitignore: bool | None = False) → Directory

Returns a Directory from the workspace.

Relative paths resolve from the workspace directory. Absolute paths resolve from the workspace boundary.

Parameters:

• path – Location of the directory to retrieve. Relative paths (e.g., “src”) resolve from the workspace directory; absolute paths (e.g., “/src”) resolve from the workspace boundary.

• exclude – Exclude artifacts that match the given pattern (e.g., [“node_modules/”, “.git*”]).

• include – Include only artifacts that match the given pattern (e.g., [“app/”, “package.*”]).

• gitignore – Apply .gitignore filter rules inside the directory.

file(path: str) → File

Returns a File from the workspace.

Relative paths resolve from the workspace directory. Absolute paths resolve from the workspace boundary.

Parameters:

path – Location of the file to retrieve. Relative paths (e.g., “go.mod”) resolve from the workspace directory; absolute paths (e.g., “/go.mod”) resolve from the workspace boundary.

async find_up(name: str, *, from_: str | None = '.') → str | None

Search for a file or directory by walking up from the start path within the workspace.

Returns the absolute workspace path if found, or null if not found.

Relative start paths resolve from the workspace directory.

The search stops at the workspace boundary and will not traverse above it.

Parameters:

• name – The name of the file or directory to search for.

• from – Path to start the search from. Relative paths resolve from the workspace directory; absolute paths resolve from the workspace boundary.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

generators(*, include: list[str] | None = None) → GeneratorGroup

Return all generators from modules loaded in the workspace.

Parameters:

include – Only include generators matching the specified patterns

async has_config() → bool

Whether a config.toml file exists in the workspace.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async id() → str

A unique identifier for this Workspace.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async initialized() → bool

Whether .dagger/config.toml exists.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

async path() → str

Workspace directory path relative to the workspace boundary.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:

• ExecuteTimeoutError – If the time to execute the query exceeds the configured timeout.

• QueryError – If the API returns an error.

services(*, include: list[str] | None = None) → UpGroup

Return all services from modules loaded in the workspace.

Parameters:

include – Only include services matching the specified patterns

update() → Changeset

Refresh workspace-managed state and return the resulting changeset.

Currently this refreshes existing lockfile entries only.

Caution

Experimental: Experimental workspace update API currently refreshes existing lockfile entries only.

class dagger.WorkspaceID

Bases: Scalar

A unique identifier for an object.