File

The File type represents a single file. Some of its important fields are:

Common operations

Field	Description
`contents`	Returns the contents of the file
`export`	Writes the file to a path on the host

tip

Default paths are also available for File arguments. They are commonly used to load constant filesystem locations, such as an application's source code directory. Additionally, when a value is explicitly passed for the argument, it always overrides the default path.

Examples

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
Python
TypeScript

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)
}

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)
        )

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
Python
TypeScript

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)
}

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)

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 Shell
Dagger CLI

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

First type 'dagger' for interactive mode.
mount-file /home/admin/archives.zip

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 Shell
Dagger CLI

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

First type 'dagger' for interactive mode.
mount-file https://github.com/dagger/dagger.git#main:README.md

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 Shell
Dagger CLI

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

First type 'dagger' for interactive mode.
mount-file https://github.com/dagger/dagger.git#main:README.md | file /src/README.md | contents

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 Shell
Dagger CLI

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

First type 'dagger' for interactive mode.
copy-file /home/admin/archives.zip

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 Shell
Dagger CLI

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

First type 'dagger' for interactive mode.
copy-file /home/admin/archives.zip | directory /src | entries

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 Shell
Dagger CLI

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

First type 'dagger' for interactive mode.
copy-file https://github.com/dagger/dagger.git#main:README.md

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 Shell
Dagger CLI

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

First type 'dagger' for interactive mode.
copy-file https://github.com/dagger/dagger.git#main:README.md | file /src/README.md | contents

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
Python
TypeScript

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"))
}

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())

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 Shell
Dagger CLI

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

First type 'dagger' for interactive mode.
copy-file ../data.json

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

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

Go
Python
TypeScript

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)
}

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)

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 Shell
Dagger CLI

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

First type 'dagger' for interactive mode.
read-file-http https://raw.githubusercontent.com/dagger/dagger/refs/heads/main/README.md

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 Shell
Dagger CLI

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

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 call \
  read-file-http --url=https://raw.githubusercontent.com/dagger/dagger/refs/heads/main/README.md \
  file --path=/src/myfile \
  contents

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
Python
TypeScript

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"})
}

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"])
        )

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 Shell
- Dagger CLI
dagger -c 'get-dir | export /home/admin/export'
First type 'dagger' for interactive mode.
get-dir | export /home/admin/export
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 Shell
- Dagger CLI
dagger -c 'get-file | export /home/admin/myfile'
First type 'dagger' for interactive mode.
get-file | export /home/admin/myfile
dagger call get-file export --path=/home/admin/myfile

Common operations​

Examples​

Mount or copy a local or remote file to a container​

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

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

Export a directory or file to the host​

Examples​

Common operations

Examples

Mount or copy a local or remote file to a container

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

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

Export a directory or file to the host

Examples