Filesystems

This page contains practical examples for working with files and directories in Dagger. Each section below provides code examples in multiple languages and demonstrates different approaches to filesystem operations.

Clone a remote Git repository into a container

The following Dagger Function accepts a Git repository URL and a Git reference. It copies the repository at the specified reference to the /src path in a container and returns the modified container.

note

For examples of SSH-based cloning, including private or public Git repositories with an SSH reference format, select the SSH tabs below. This approach requires explicitly forwarding the host SSH_AUTH_SOCK to the Dagger Function. Learn more about this in Dagger's security model.

Go

package main

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

// Demonstrates cloning a Git repository over HTTP(S).
//
// For SSH usage, see the SSH snippet (CloneWithSsh).
type MyModule struct{}

func (m *MyModule) Clone(ctx context.Context, repository string, ref string) *dagger.Container {
	d := dag.Git(repository).Ref(ref).Tree()

	return dag.Container().
		From("alpine:latest").
		WithDirectory("/src", d).
		WithWorkdir("/src")
}

Go (SSH)

package main

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

// Demonstrates an SSH-based clone requiring a user-supplied SSHAuthSocket.
type MyModule struct{}

func (m *MyModule) CloneWithSsh(ctx context.Context, repository string, ref string, sock *dagger.Socket) *dagger.Container {
	d := dag.Git(repository, dagger.GitOpts{SSHAuthSocket: sock}).Ref(ref).Tree()

	return dag.Container().
		From("alpine:latest").
		WithDirectory("/src", d).
		WithWorkdir("/src")
}

Python

import dagger
from dagger import dag, function, object_type


@object_type
class MyModule:
    """
    Demonstrates cloning a Git repository over HTTP(S).

    For SSH usage, see the SSH snippet (clone_with_ssh).
    """

    @function
    async def clone(
        self,
        repository: str,
        ref: str,
    ) -> dagger.Container:
        repo_dir = dag.git(repository).ref(ref).tree()

        return (
            dag.container()
            .from_("alpine:latest")
            .with_directory("/src", repo_dir)
            .with_workdir("/src")
        )

Python (SSH)

import dagger
from dagger import dag, function, object_type


@object_type
class MyModule:
    """Demonstrates an SSH-based clone requiring a user-supplied ssh_auth_socket."""

    @function
    async def clone_with_ssh(
        self, repository: str, ref: str, sock: dagger.Socket
    ) -> dagger.Container:
        repo_dir = dag.git(repository, ssh_auth_socket=sock).ref(ref).tree()

        return (
            dag.container()
            .from_("alpine:latest")
            .with_directory("/src", repo_dir)
            .with_workdir("/src")
        )

TypeScript

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

@object()
class MyModule {
  /**
    Demonstrates cloning a Git repository over HTTP(S).

    For SSH usage, see the SSH snippet (cloneWithSsh).
   */
  @func()
  clone(repository: string, ref: string): Container {
    const repoDir = dag.git(repository, { sshAuthSocket: sock }).ref(ref).tree()

    return dag
      .container()
      .from("alpine:latest")
      .withDirectory("/src", repoDir)
      .withWorkdir("/src")
  }
}

TypeScript (SSH)

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

@object()
class MyModule {
  /**
    Demonstrates an SSH-based clone requiring a user-supplied sshAuthSocket.
   */
  @func()
  cloneWithSsh(repository: string, ref: string, sock: Socket): Container {
    const repoDir = dag.git(repository, { sshAuthSocket: sock }).ref(ref).tree()

    return dag
      .container()
      .from("alpine:latest")
      .withDirectory("/src", repoDir)
      .withWorkdir("/src")
  }
}

PHP

<?php

declare(strict_types=1);

namespace DaggerModule;

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

use function Dagger\dag;

#[DaggerObject]
class MyModule
{
    #[DaggerFunction]
    public function clone(string $repository, string $ref): Container
    {
        $repoDir = dag()->git($repository)->ref($ref)->tree();

        return dag()
            ->container()
            ->from('alpine:latest')
            ->withDirectory('/src', $repoDir);
    }
}

Examples

Clone the public dagger/dagger GitHub repository to /src in the container:

System shell

dagger -c 'clone https://github.com/dagger/dagger 196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5'

Dagger Shell

First type 'dagger' for interactive mode.

clone https://github.com/dagger/dagger 196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5

Dagger CLI

dagger call clone --repository=https://github.com/dagger/dagger --ref=196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5

Clone the public dagger/dagger GitHub repository at reference 196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5 to /src in the container and open an interactive terminal to inspect the container filesystem:

System shell

dagger <<EOF
clone https://github.com/dagger/dagger 196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5 |
  terminal
EOF

Dagger Shell

First type 'dagger' for interactive mode.

clone https://github.com/dagger/dagger 196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5 | terminal

Dagger CLI

dagger call \
  clone --repository=https://github.com/dagger/dagger --ref=196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5 \
  terminal

Clone over SSH with socket forwarding:

System shell

dagger <<EOF
clone-with-ssh git@github.com:dagger/dagger.git 196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5 $SSH_AUTH_SOCK |
  terminal
EOF

Dagger Shell

First type 'dagger' for interactive mode.

clone-with-ssh git@github.com:dagger/dagger.git 196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5 $SSH_AUTH_SOCK | terminal

Dagger CLI

dagger call \
  clone-with-ssh --repository=git@github.com:dagger/dagger.git --ref=196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5 --sock=$SSH_AUTH_SOCK \
  terminal

Mount or copy a directory or remote repository to a container

The following Dagger Function accepts a Directory argument, which could reference either a directory from the local filesystem or from a remote Git repository. It mounts the specified directory to the /src path in a container and returns the modified container.

note

When working with private Git repositories, ensure that SSH authentication is properly configured on your Dagger host.

Go

package main

import (
	"context"

	"dagger/my-module/internal/dagger"
)

type MyModule struct{}

// Return a container with a mounted directory
func (m *MyModule) MountDirectory(
	ctx context.Context,
	// Source directory
	source *dagger.Directory,
) *dagger.Container {
	return dag.Container().
		From("alpine:latest").
		WithMountedDirectory("/src", source)
}

Python

from typing import Annotated

import dagger
from dagger import Doc, dag, function, object_type


@object_type
class MyModule:
    @function
    def mount_directory(
        self, source: Annotated[dagger.Directory, Doc("Source directory")]
    ) -> dagger.Container:
        """Return a container with a mounted directory"""
        return (
            dag.container()
            .from_("alpine:latest")
            .with_mounted_directory("/src", source)
        )

TypeScript

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

@object()
class MyModule {
  /**
   * Return a container with a mounted directory
   */
  @func()
  mountDirectory(
    /**
     * Source directory
     */
    source: Directory,
  ): Container {
    return dag
      .container()
      .from("alpine:latest")
      .withMountedDirectory("/src", source)
  }
}

PHP

<?php

declare(strict_types=1);

namespace DaggerModule;

use Dagger\Attribute\DaggerFunction;
use Dagger\Attribute\DaggerObject;
use Dagger\Attribute\Doc;
use Dagger\Container;
use Dagger\Directory;

use function Dagger\dag;

#[DaggerObject]
class MyModule
{
    #[DaggerFunction]
    #[Doc('Return a container with a mounted directory')]
    public function mountDirectory(Directory $source): Container
    {
        return dag()
            ->container()
            ->from('alpine:latest')
            ->withMountedDirectory('/src', $source);
    }
}

An alternative option is to copy the target directory in the container. The difference between these two approaches is that mounts only take effect within your workflow invocation; they are not copied to, or included, in the final image. In addition, any changes to mounted files and/or directories will only be reflected in the target directory and not in the mount sources.

tip

Besides helping with the final image size, mounts are more performant and resource-efficient. The rule of thumb should be to always use mounts where possible.

Go

package main

import (
	"context"

	"dagger/my-module/internal/dagger"
)

type MyModule struct{}

// Return a container with a specified directory
func (m *MyModule) CopyDirectory(
	ctx context.Context,
	// Source directory
	source *dagger.Directory,
) *dagger.Container {
	return dag.Container().
		From("alpine:latest").
		WithDirectory("/src", source)
}

Python

from typing import Annotated

import dagger
from dagger import Doc, dag, function, object_type


@object_type
class MyModule:
    @function
    def copy_directory(
        self, source: Annotated[dagger.Directory, Doc("Source directory")]
    ) -> dagger.Container:
        """Return a container with a specified directory"""
        return dag.container().from_("alpine:latest").with_directory("/src", source)

TypeScript

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

@object()
class MyModule {
  /**
   * Return a container with a specified directory
   */
  @func()
  copyDirectory(
    /**
     * Source directory
     */
    source: Directory,
  ): Container {
    return dag.container().from("alpine:latest").withDirectory("/src", source)
  }
}

PHP

<?php

declare(strict_types=1);

namespace DaggerModule;

use Dagger\Attribute\DaggerFunction;
use Dagger\Attribute\DaggerObject;
use Dagger\Attribute\Doc;
use Dagger\Container;
use Dagger\Directory;

use function Dagger\dag;

#[DaggerObject]
class MyModule
{
    #[DaggerFunction]
    #[Doc('Return a container with a specified directory')]
    public function copyDirectory(Directory $source): Container
    {
        return dag()
            ->container()
            ->from('alpine:latest')
            ->withDirectory('/src', $source);
    }
}

Examples

• Mount the /myapp host directory to /src in the container and return the modified container:

  System shell

  dagger -c 'mount-directory ./myapp/'

  Dagger Shell

  First type 'dagger' for interactive mode.

  mount-directory ./myapp/

  Dagger CLI

  dagger call mount-directory --source=./myapp/

• Mount the public dagger/dagger GitHub repository to /src in the container and return the modified container:

  System shell

  dagger -c 'mount-directory https://github.com/dagger/dagger#main'

  Dagger Shell

  First type 'dagger' for interactive mode.

  mount-directory https://github.com/dagger/dagger#main

  Dagger CLI

  dagger call mount-directory --source=https://github.com/dagger/dagger#main

• Mount the private user/foo GitHub repository to /src in the container and return the modified container:

  System shell

  dagger -c 'mount-directory ssh://git@github.com/user/foo#main'

  Dagger Shell

  First type 'dagger' for interactive mode.

  mount-directory ssh://git@github.com/user/foo#main

  Dagger CLI

  dagger call mount-directory --source=ssh://git@github.com/user/foo#main

• Mount the public dagger/dagger GitHub repository to /src in the container and list the contents of the directory:

  System shell

  dagger -c 'mount-directory https://github.com/dagger/dagger#main | directory /src | entries'

  Dagger Shell

  First type 'dagger' for interactive mode.

  mount-directory https://github.com/dagger/dagger#main | directory /src | entries

  Dagger CLI

  dagger call \
    mount-directory --source=https://github.com/dagger/dagger#main \
    directory --path=/src \
    entries

• Copy the /myapp host directory to /src in the container and return the modified container:

  System shell

  dagger -c 'copy-directory ./myapp/'

  Dagger Shell

  First type 'dagger' for interactive mode.

  copy-directory ./myapp/

  Dagger CLI

  dagger call copy-directory --source=./myapp/

• Copy the public dagger/dagger GitHub repository to /src in the container and return the modified container:

  System shell

  dagger -c 'copy-directory https://github.com/dagger/dagger#main'

  Dagger Shell

  First type 'dagger' for interactive mode.

  copy-directory https://github.com/dagger/dagger#main

  Dagger CLI

  dagger call copy-directory --source=https://github.com/dagger/dagger#main

• Copy the private user/foo GitHub repository to /src in the container and return the modified container:

  System shell

  dagger -c 'copy-directory ssh://git@github.com/user/foo#main'

  Dagger Shell

  First type 'dagger' for interactive mode.

  copy-directory ssh://git@github.com/user/foo#main

  Dagger CLI

  dagger call copy-directory --source=ssh://git@github.com/user/foo#main

• Copy the public dagger/dagger GitHub repository to /src in the container and list the contents of the directory:

  System shell

  dagger -c 'copy-directory https://github.com/dagger/dagger#main | directory /src | entries'

  Dagger Shell

  First type 'dagger' for interactive mode.

  copy-directory https://github.com/dagger/dagger#main | directory /src | entries

  Dagger CLI

  dagger call \
    copy-directory --source=https://github.com/dagger/dagger#main \
    directory --path=/src \
    entries

Modify a copied directory or remote repository in a container

The following Dagger Function accepts a Directory argument, which could reference either a directory from the local filesystem or from a remote Git repository. It copies the specified directory to the /src path in a container, adds a file to it, and returns the modified container.

warning

When a host directory or file is copied or mounted to a container's filesystem, modifications made to it in the container do not automatically transfer back to the host.

Data flows only one way between Dagger operations, because they are connected in a DAG. To transfer modifications back to the local host, you must explicitly export the directory or file back to the host filesystem.

note

When working with private Git repositories, ensure that SSH authentication is properly configured on your Dagger host.

When working with private Git repositories, ensure that SSH authentication is properly configured on your Dagger host. :::

Go

package main

import (
	"context"

	"dagger/my-module/internal/dagger"
)

type MyModule struct{}

// Return a container with a specified directory and an additional file
func (m *MyModule) CopyAndModifyDirectory(
	ctx context.Context,
	// Source directory
	source *dagger.Directory,
) *dagger.Container {
	return dag.Container().
		From("alpine:latest").
		WithDirectory("/src", source).
		WithExec([]string{"/bin/sh", "-c", `echo foo > /src/foo`})
}

Python

from typing import Annotated

import dagger
from dagger import Doc, dag, function, object_type


@object_type
class MyModule:
    @function
    def copy_and_modify_directory(
        self, source: Annotated[dagger.Directory, Doc("Source directory")]
    ) -> dagger.Container:
        """Return a container with a specified directory and an additional file"""
        return (
            dag.container()
            .from_("alpine:latest")
            .with_directory("/src", source)
            .with_exec(["/bin/sh", "-c", "`echo foo > /src/foo`"])
        )

TypeScript

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

@object()
class MyModule {
  /**
   * Return a container with a specified directory and an additional file
   */
  @func()
  copyAndModifyDirectory(
    /**
     * Source directory
     */
    source: Directory,
  ): Container {
    return dag
      .container()
      .from("alpine:latest")
      .withDirectory("/src", source)
      .withExec(["/bin/sh", "-c", "`echo foo > /src/foo`"])
  }
}

PHP

<?php

declare(strict_types=1);

namespace DaggerModule;

use Dagger\Attribute\DaggerFunction;
use Dagger\Attribute\DaggerObject;
use Dagger\Attribute\Doc;
use Dagger\Container;
use Dagger\Directory;

use function Dagger\dag;

#[DaggerObject]
class MyModule
{
    #[DaggerFunction]
    #[Doc('Return a container with a specified directory and an additional file')]
    public function copyAndModifyDirectory(Directory $source): Container
    {
        return dag()
            ->container()
            ->from('alpine:latest')
            ->withDirectory('/src', $source)
            ->withExec(['/bin/sh', '-c', `echo foo > /src/foo`]);
    }
}

Examples

Copy the /myapp host directory to /src in the container, add a file to it, and return the modified container:

System shell

dagger -c 'copy-and-modify-directory ./myapp/'

Dagger Shell

First type 'dagger' for interactive mode.

copy-and-modify-directory ./myapp/

Dagger CLI

dagger call copy-and-modify-directory --source=./myapp/

Copy the public dagger/dagger GitHub repository to /src in the container, add a file to it, and return the modified container:

System shell

dagger -c 'copy-and-modify-directory github.com/dagger/dagger#main'

Dagger Shell

First type 'dagger' for interactive mode.

copy-and-modify-directory github.com/dagger/dagger#main

Dagger CLI

dagger call copy-and-modify-directory --source=github.com/dagger/dagger#main

Copy the private user/foo GitHub repository to /src in the container, add a file to it, and return the modified container:

System shell

dagger -c 'copy-and-modify-directory ssh://git@github.com/user/foo#main'

Dagger Shell

First type 'dagger' for interactive mode.

copy-and-modify-directory ssh://git@github.com/user/foo#main

Dagger CLI

dagger call copy-and-modify-directory --source=ssh://git@github.com/user/foo#main

Copy the public dagger/dagger GitHub repository to /src in the container, add a file to it, and list the contents of the directory:

System shell

dagger -c 'copy-and-modify-directory https://github.com/dagger/dagger#main | directory /src | entries'

Dagger Shell

First type 'dagger' for interactive mode.

copy-and-modify-directory https://github.com/dagger/dagger#main | directory /src | entries

Dagger CLI

dagger call \
  copy-and-modify-directory --source=https://github.com/dagger/dagger#main \
  directory --path=/src \
  entries

Copy a subset of a directory or remote repository to a container using filters specified at run-time

The following Dagger Function accepts a Directory argument, which could reference either a directory from the local filesystem or a remote Git repository. It copies the specified directory to the /src path in a container, using a filter pattern specified at call-time to exclude specified sub-directories and files, and returns the modified container.

note

When working with private Git repositories, ensure that SSH authentication is properly configured on your Dagger host.

note

This is an example of post-call filtering with directory filters.

Go

package main

import (
	"context"

	"dagger/my-module/internal/dagger"
)

type MyModule struct{}

// Return a container with a filtered directory
func (m *MyModule) CopyDirectoryWithExclusions(
	ctx context.Context,
	// Source directory
	source *dagger.Directory,
	// Exclusion pattern
	// +optional
	exclude []string,
) *dagger.Container {
	return dag.Container().
		From("alpine:latest").
		WithDirectory("/src", source, dagger.ContainerWithDirectoryOpts{Exclude: exclude})
}

Python

from typing import Annotated

import dagger
from dagger import Doc, dag, function, object_type


@object_type
class MyModule:
    @function
    def copy_directory_with_exclusions(
        self,
        source: Annotated[dagger.Directory, Doc("Source directory")],
        exclude: Annotated[list[str], Doc("Exclusion pattern")] | None,
    ) -> dagger.Container:
        """Return a container with a filtered directory"""
        return (
            dag.container()
            .from_("alpine:latest")
            .with_directory("/src", source, exclude=exclude)
        )

TypeScript

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

@object()
class MyModule {
  /**
   * Return a container with a filtered directory
   */
  @func()
  copyDirectoryWithExclusions(
    /**
     * Source directory
     */
    source: Directory,
    /**
     * Exclusion pattern
     */
    exclude?: string[],
  ): Container {
    return dag
      .container()
      .from("alpine:latest")
      .withDirectory("/src", source, { exclude: exclude })
  }
}

Examples

Copy the current host directory to /src in the container, excluding all sub-directories and files starting with dagger, and return the modified container:

System shell

dagger -c 'copy-directory-with-exclusions . --exclude=dagger*'

Dagger Shell

First type 'dagger' for interactive mode.

copy-directory-with-exclusions . --exclude=dagger*

Dagger CLI

dagger call copy-directory-with-exclusions --source=. --exclude=dagger*

Copy the public dagger/dagger GitHub repository to /src in the container, excluding all Markdown files, and list the contents of the directory:

System shell

dagger <<EOF
copy-directory-with-exclusions https://github.com/dagger/dagger#main --exclude=*.md |
  directory /src |
  entries
EOF

Dagger Shell

First type 'dagger' for interactive mode.

copy-directory-with-exclusions https://github.com/dagger/dagger#main --exclude=*.md | directory /src | entries

Dagger CLI

dagger call \
  copy-directory-with-exclusions --source=https://github.com/dagger/dagger#main --exclude=*.md \
  directory --path=/src \
  entries

Copy the private user/foo GitHub repository to /src in the container, excluding all Markdown files, and list the contents of the directory:

System shell

dagger <<EOF
copy-directory-with-exclusions ssh://git@github.com/user/foo#main --exclude=*.md |
  directory /src |
  entries
EOF

Dagger Shell

First type 'dagger' for interactive mode.

copy-directory-with-exclusions ssh://git@github.com/user/foo#main --exclude=*.md | directory /src | entries

Dagger CLI

dagger call \
  copy-directory-with-exclusions --source=ssh://git@github.com/user/foo#main --exclude=*.md \
  directory --path=/src \
  entries

Copy a subset of a directory or remote repository to a container using pre-defined filters

The following Dagger Function accepts a Directory argument, which could reference either a directory from the local filesystem or a remote Git repository. It copies the specified directory to the /src path in a container, using pre-defined filter patterns to exclude specified sub-directories and files, and returns the modified container.

note

When working with private Git repositories, ensure that SSH authentication is properly configured on your Dagger host.

note

This is an example of pre-call filtering with directory filters.

Go

package main

import (
	"context"
	"main/internal/dagger"
)

type MyModule struct{}

func (m *MyModule) CopyDirectoryWithExclusions(
	ctx context.Context,
	// +ignore=["*", "!**/*.md"]
	source *dagger.Directory,
) (*dagger.Container, error) {
	return dag.
		Container().
		From("alpine:latest").
		WithDirectory("/src", source).
		Sync(ctx)
}

Python

from typing import Annotated

import dagger
from dagger import Ignore, dag, function, object_type


@object_type
class MyModule:
    @function
    async def copy_directory_with_exclusions(
        self,
        source: Annotated[dagger.Directory, Ignore(["*", "!*.md"])],
    ) -> dagger.Container:
        return await (
            dag.container().from_("alpine:latest").with_directory("/src", source).sync()
        )

TypeScript

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

@object()
class MyModule {
  @func()
  async copy_directory_with_exclusions(
    @argument({ ignore: ["*", "!**/*.md"] }) source: Directory,
  ): Promise<Container> {
    return await dag
      .container()
      .from("alpine:latest")
      .withDirectory("/src", source)
      .sync()
  }
}

Examples

Copy the specified host directory to /src in the container, excluding everything except Markdown files, and return the modified container:

System shell

dagger -c 'copy-directory-with-exclusions ../docs'

Dagger Shell

First type 'dagger' for interactive mode.

copy-directory-with-exclusions ../docs

Dagger CLI

dagger call copy-directory-with-exclusions --source=../docs

Copy the public dagger/dagger GitHub repository to /src in the container, excluding everything except Markdown files, and list the contents of the /src directory in the container:

System shell

dagger -c 'copy-directory-with-exclusions https://github.com/dagger/dagger#main | directory /src | entries'

Dagger Shell

First type 'dagger' for interactive mode.

copy-directory-with-exclusions https://github.com/dagger/dagger#main | directory /src | entries

Dagger CLI

dagger call \
  copy-directory-with-exclusions --source=https://github.com/dagger/dagger#main \
  directory --path=/src \
  entries

Mount or copy a local or remote file to a container

The following Dagger Function accepts a File argument, which could reference either a file from the local filesystem or from a remote Git repository. It mounts the specified file to a container in the /src/ directory and returns the modified container.

Go

package main

import (
	"context"
	"fmt"

	"dagger/my-module/internal/dagger"
)

type MyModule struct{}

// Return a container with a mounted file
func (m *MyModule) MountFile(
	ctx context.Context,
	// Source file
	f *dagger.File,
) *dagger.Container {
	name, _ := f.Name(ctx)
	return dag.Container().
		From("alpine:latest").
		WithMountedFile(fmt.Sprintf("/src/%s", name), f)
}

Python

from typing import Annotated

import dagger
from dagger import Doc, dag, function, object_type


@object_type
class MyModule:
    @function
    async def copy_file(
        self,
        f: Annotated[dagger.File, Doc("Source file")],
    ) -> dagger.Container:
        """Return a container with a mounted file"""
        name = await f.name()
        return (
            dag.container().from_("alpine:latest").with_mounted_file(f"/src/{name}", f)
        )

TypeScript

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

@object()
class MyModule {
  /**
   * Return a container with a mounted file
   */
  @func()
  async copyFile(
    /**
     * Source file
     */
    f: File,
  ): Promise<Container> {
    const name = await f.name()
    return dag
      .container()
      .from("alpine:latest")
      .withMountedFile(`/src/${name}`, f)
  }
}

An alternative option is to copy the target file to the container. The difference between these two approaches is that mounts only take effect within your workflow invocation; they are not copied to, or included, in the final image. In addition, any changes to mounted files and/or directories will only be reflected in the target directory and not in the mount sources.

tip

Besides helping with the final image size, mounts are more performant and resource-efficient. The rule of thumb should be to always use mounts where possible.

Go

package main

import (
	"context"
	"fmt"

	"dagger/my-module/internal/dagger"
)

type MyModule struct{}

// Return a container with a specified file
func (m *MyModule) CopyFile(
	ctx context.Context,
	// Source file
	f *dagger.File,
) *dagger.Container {
	name, _ := f.Name(ctx)
	return dag.Container().
		From("alpine:latest").
		WithFile(fmt.Sprintf("/src/%s", name), f)
}

Python

from typing import Annotated

import dagger
from dagger import Doc, dag, function, object_type


@object_type
class MyModule:
    @function
    async def copy_file(
        self,
        f: Annotated[dagger.File, Doc("Source file")],
    ) -> dagger.Container:
        """Return a container with a specified file"""
        name = await f.name()
        return dag.container().from_("alpine:latest").with_file(f"/src/{name}", f)

TypeScript

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

@object()
class MyModule {
  /**
   * Return a container with a specified file
   */
  @func()
  async copyFile(
    /**
     * Source file
     */
    f: File,
  ): Promise<Container> {
    const name = await f.name()
    return dag.container().from("alpine:latest").withFile(`/src/${name}`, f)
  }
}

Examples

Mount the /home/admin/archives.zip file on the host to the /src directory in the container and return the modified container:

System shell

dagger -c 'mount-file /home/admin/archives.zip'

Dagger Shell

First type 'dagger' for interactive mode.

mount-file /home/admin/archives.zip

Dagger CLI

dagger call mount-file --f=/home/admin/archives.zip

Mount the README.md file from the public dagger/dagger GitHub repository to the /src directory in the container:

System shell

dagger -c 'mount-file https://github.com/dagger/dagger.git#main:README.md'

Dagger Shell

First type 'dagger' for interactive mode.

mount-file https://github.com/dagger/dagger.git#main:README.md

Dagger CLI

dagger call mount-file --f=https://github.com/dagger/dagger.git#main:README.md

Mount the README.md file from the public dagger/dagger GitHub repository to the /src directory in the container and display its contents:

System shell

dagger <<EOF
mount-file https://github.com/dagger/dagger.git#main:README.md |
  file /src/README.md |
  contents
EOF

Dagger Shell

First type 'dagger' for interactive mode.

mount-file https://github.com/dagger/dagger.git#main:README.md | file /src/README.md | contents

Dagger CLI

dagger call \
  mount-file --f=https://github.com/dagger/dagger.git#main:README.md \
  file --path=/src/README.md \
  contents

Copy the /home/admin/archives.zip file on the host to the /src directory in the container and return the modified container:

System shell

dagger -c 'copy-file /home/admin/archives.zip'

Dagger Shell

First type 'dagger' for interactive mode.

copy-file /home/admin/archives.zip

Dagger CLI

dagger call copy-file --f=/home/admin/archives.zip

Copy the /home/admin/archives.zip file on the host to the /src directory in the container and list the contents of the directory:

System shell

dagger -c 'copy-file /home/admin/archives.zip | directory /src | entries'

Dagger Shell

First type 'dagger' for interactive mode.

copy-file /home/admin/archives.zip | directory /src | entries

Dagger CLI

dagger call \
  copy-file --f=/home/admin/archives.zip \
  directory --path=/src \
  entries

Copy the README.md file from the public dagger/dagger GitHub repository to the /src directory in the container:

System shell

dagger -c 'copy-file https://github.com/dagger/dagger.git#main:README.md'

Dagger Shell

First type 'dagger' for interactive mode.

copy-file https://github.com/dagger/dagger.git#main:README.md

Dagger CLI

dagger call copy-file --f=https://github.com/dagger/dagger.git#main:README.md

Copy the README.md file from the public dagger/dagger GitHub repository to the /src directory in the container and display its contents:

System shell

dagger <<EOF
copy-file https://github.com/dagger/dagger.git#main:README.md |
  file /src/README.md |
  contents
EOF

Dagger Shell

First type 'dagger' for interactive mode.

copy-file https://github.com/dagger/dagger.git#main:README.md | file /src/README.md | contents

Dagger CLI

dagger call \
  copy-file --f=https://github.com/dagger/dagger.git#main:README.md \
  file --path=/src/README.md \
  contents

Copy a file to the Dagger module runtime container for custom processing

The following Dagger Function accepts a File argument and copies the specified file to the Dagger module runtime container. This makes it possible to add one or more files to the runtime container and manipulate them using custom logic.

Go

package main

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

type MyModule struct{}

// Copy a file to the Dagger module runtime container for custom processing
func (m *MyModule) CopyFile(ctx context.Context, source *dagger.File) {
	source.Export(ctx, "foo.txt")
	// your custom logic here
	// for example, read and print the file in the Dagger Engine container
	fmt.Println(os.ReadFile("foo.txt"))
}

Python

import anyio

import dagger
from dagger import function, object_type


@object_type
class MyModule:
    @function
    async def copy_file(self, source: dagger.File):
        """Copy a file to the Dagger module runtime container for custom processing"""
        await source.export("foo.txt")
        # your custom logic here
        # for example, read and print the file in the Dagger Engine container
        print(await anyio.Path("foo.txt").read_text())

TypeScript

import { object, func, File } from "@dagger.io/dagger"
import * as fs from "fs"

@object()
class MyModule {
  // Copy a file to the Dagger module runtime container for custom processing
  @func()
  async copyFile(source: File) {
    await source.export("foo.txt")
    // your custom logic here
    // for example, read and print the file in the Dagger Engine container
    console.log(fs.readFileSync("foo.txt", "utf8"))
  }
}

Examples

Copy the data.json host file to the runtime container and process it:

System shell

dagger -c 'copy-file ../data.json'

Dagger Shell

First type 'dagger' for interactive mode.

copy-file ../data.json

Dagger CLI

dagger call copy-file --source=../data.json

Export a directory or file to the host

The following Dagger Functions return a just-in-time directory and file. These outputs can be exported to the host with dagger call ... export ....

note

When a host directory or file is copied or mounted to a container's filesystem, modifications made to it in the container do not automatically transfer back to the host. Data flows only one way between Dagger operations, because they are connected in a DAG. To transfer modifications back to the local host, you must explicitly export the directory or file back to the host filesystem.

Go

package main

import "dagger/my-module/internal/dagger"

type MyModule struct{}

// Return a directory
func (m *MyModule) GetDir() *dagger.Directory {
	return m.Base().
		Directory("/src")
}

// Return a file
func (m *MyModule) GetFile() *dagger.File {
	return m.Base().
		File("/src/foo")
}

// Return a base container
func (m *MyModule) Base() *dagger.Container {
	return dag.Container().
		From("alpine:latest").
		WithExec([]string{"mkdir", "/src"}).
		WithExec([]string{"touch", "/src/foo", "/src/bar"})
}

Python

import dagger
from dagger import dag, function, object_type


@object_type
class MyModule:
    @function
    def get_dir(self) -> dagger.Directory:
        """Return a directory"""
        return self.base().directory("/src")

    @function
    def get_file(self) -> dagger.File:
        """Return a file"""
        return self.base().file("/src/foo")

    @function
    def base(self) -> dagger.Container:
        """Return a base container"""
        return (
            dag.container()
            .from_("alpine:latest")
            .with_exec(["mkdir", "/src"])
            .with_exec(["touch", "/src/foo", "/src/bar"])
        )

TypeScript

import {
  dag,
  Directory,
  Container,
  File,
  object,
  func,
} from "@dagger.io/dagger"

@object()
class MyModule {
  /**
   * Return a directory
   */
  @func()
  getDir(): Directory {
    return this.base().directory("/src")
  }

  /**
   * Return a file
   */
  @func()
  getFile(): File {
    return this.base().file("/src/foo")
  }

  /**
   * Return a base container
   */
  @func()
  base(): Container {
    return dag
      .container()
      .from("alpine:latest")
      .withExec(["mkdir", "/src"])
      .withExec(["touch", "/src/foo", "/src/bar"])
  }
}

Examples

• Export the directory returned by the Dagger Function to the /home/admin/export path on the host:

  System shell

  dagger -c 'get-dir | export /home/admin/export'

  Dagger Shell

  First type 'dagger' for interactive mode.

  get-dir | export /home/admin/export

  Dagger CLI

  dagger call get-dir export --path=/home/admin/export

• Export the file returned by the Dagger Function to the /home/admin/myfile path on the host:

  System shell

  dagger -c 'get-file | export /home/admin/myfile'

  Dagger Shell

  First type 'dagger' for interactive mode.

  get-file | export /home/admin/myfile

  Dagger CLI

  dagger call get-file export --path=/home/admin/myfile

Request a file over HTTP/HTTPS and save it in a container

Go

package main

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

type MyModule struct{}

func (m *MyModule) ReadFileHttp(
	ctx context.Context,
	url string,
) *dagger.Container {
	file := dag.HTTP(url)
	return dag.Container().
		From("alpine:latest").
		WithFile("/src/myfile", file)
}

Python

import dagger
from dagger import dag, function, object_type


@object_type
class MyModule:
    @function
    def read_file_http(self, url: str) -> dagger.Container:
        file = dag.http(url)
        return dag.container().from_("alpine:latest").with_file("/src/myfile", file)

TypeScript

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

@object()
class MyModule {
  @func()
  readFileHttp(url: string): Container {
    const file = dag.http(url)
    return dag.container().from("alpine:latest").withFile("/src/myfile", file)
  }
}

Examples

Request the README.md file from the public dagger/dagger GitHub repository over HTTPS, save it as /src/myfile in the container, and return the container:

System shell

dagger -c 'read-file-http https://raw.githubusercontent.com/dagger/dagger/refs/heads/main/README.md'

Dagger Shell

First type 'dagger' for interactive mode.

read-file-http https://raw.githubusercontent.com/dagger/dagger/refs/heads/main/README.md

Dagger CLI

dagger call read-file-http --url=https://raw.githubusercontent.com/dagger/dagger/refs/heads/main/README.md

Request the README.md file from the public dagger/dagger GitHub repository over HTTPS, save it as /src/myfile in the container, and display its contents:

System shell

dagger <<EOF
read-file-http https://raw.githubusercontent.com/dagger/dagger/refs/heads/main/README.md |
  file /src/myfile |
  contents
EOF

Dagger Shell

First type 'dagger' for interactive mode.

read-file-http https://raw.githubusercontent.com/dagger/dagger/refs/heads/main/README.md | file /src/myfile | contents

Dagger CLI

dagger call \
  read-file-http --url=https://raw.githubusercontent.com/dagger/dagger/refs/heads/main/README.md \
  file --path=/src/myfile \
  contents

Set a module-wide default path

The following Dagger module uses a constructor to set a module-wide Directory argument and point it to a default path on the host. This eliminates the need to pass a common Directory argument individually to each Dagger Function in the module. If required, the default path can be overridden by specifying a different Directory value at call time.

Go

package main

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

type MyModule struct {
	Source *dagger.Directory
}

func New(
	// +defaultPath="."
	source *dagger.Directory,
) *MyModule {
	return &MyModule{
		Source: source,
	}
}

func (m *MyModule) Foo(ctx context.Context) ([]string, error) {
	return dag.Container().
		From("alpine:latest").
		WithMountedDirectory("/app", m.Source).
		Directory("/app").
		Entries(ctx)
}

Python

from typing import Annotated

import dagger
from dagger import DefaultPath, dag, function, object_type


@object_type
class MyModule:
    source: Annotated[dagger.Directory, DefaultPath(".")]

    @function
    async def foo(self) -> str:
        return await (
            dag.container()
            .from_("alpine:latest")
            .with_mounted_directory("/app", self.source)
            .directory("/app")
            .entries()
        )

TypeScript

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

@object()
class MyModule {
  source: Directory

  constructor(
    @argument({ defaultPath: "." })
    source: Directory,
  ) {
    this.source = source
  }

  @func()
  async foo(): Promise<string[]> {
    return await dag
      .container()
      .from("alpine:latest")
      .withMountedDirectory("/app", this.source)
      .directory("/app")
      .entries()
  }
}

PHP

<?php

declare(strict_types=1);

namespace DaggerModule;

use Dagger\Attribute\DaggerFunction;
use Dagger\Attribute\DaggerObject;
use Dagger\Attribute\DefaultPath;
use Dagger\Attribute\ReturnsListOfType;
use Dagger\Directory;

use function Dagger\dag;

#[DaggerObject]
class MyModule
{
    #[DaggerFunction]
    public function __construct(
        #[DefaultPath('.')]
        public Directory $source
    ) {
    }

    #[DaggerFunction]
    #[ReturnsListOfType('string')]
    public function foo(): array
    {
        return dag()
            ->container()
            ->from('alpine:latest')
            ->withMountedDirectory('/app', $this->source)
            ->directory('/app')
            ->entries();
    }
}

Examples

Call the Dagger Function without arguments. The default path (the current directory .) is used:

System shell

dagger -c foo

Dagger Shell

First type 'dagger' for interactive mode.

foo

Dagger CLI

dagger call foo

Call the Dagger Function with a constructor argument. The specified directory (/src/myapp) is used:

System shell

dagger -c 'my-module --source $(host | directory /src/myapp) | foo'

Dagger Shell

First type 'dagger' for interactive mode.

my-module --source $(host | directory /src/myapp) | foo

Dagger CLI

dagger call --source=/src/myapp foo