embed: files inside the binary

The //go:embed directive puts a file or a directory into the binary at build time, so a program that needs a template, a schema or a static asset does not need it next to the executable. The embedded data is read-only, the access goes through io/fs, and the cost is the bytes in the binary. The previous part worked with files a test reads; this one ships them.

A string, a byte slice or a tree

A single file can fill a string or a []byte variable, and a directory fills an embed.FS. The directive must sit immediately above the variable, the variable must not be local, and the embed import is needed even when only string is embedded, because the compiler looks for the package. The file paths are relative to the package directory and the pattern may not leave it.

package assets import "embed" //go:embed data/hello.txt var Hello string //go:embed data var Data embed.FS

package main import ( "fmt" "io/fs" "strings" "example.com/app/assets" ) func main() { fmt.Print(strings.ToUpper(assets.Hello)) entries, err := fs.ReadDir(assets.Data, "data") if err != nil { panic(err) } for _, e := range entries { fmt.Println("entry:", e.Name(), e.IsDir()) } content, err := assets.Data.ReadFile("data/number.txt") if err != nil { panic(err) } fmt.Print("number:", string(content)) }

go run .

HELLO FROM THE BINARY
entry: hello.txt false
entry: number.txt false
number:42

go build -o app . && stat -c 'app: %s bytes' app

app: 2604952 bytes

go build -ldflags='-s -w' -o app-stripped . && stat -c 'app-stripped: %s bytes' app-stripped

app-stripped: 1732770 bytes

The program printed the file it embedded, listed the directory through fs.ReadDir and read the second file by path, all without touching the disk. The two builds show the size: the stripped one is smaller, and both contain the embedded bytes, which is the trade the directive makes.

Directories and globs

A pattern of data embeds the whole directory tree, while data/*.txt embeds the matching files and keeps their names. A pattern that matches no file is a build error, which catches a typo at compile time rather than in production, and a pattern that reaches outside the package directory is refused. Hidden files are excluded unless the pattern names them explicitly, a rule that surprises everyone once.

The embedded tree is an fs.FS, so it works with http.FileServer, template.ParseFS, and anything else that takes a filesystem. That is the reason to prefer embed.FS over a string even when there is one file: the standard library already knows how to read a filesystem, and the program does not need a second path for development files.

What it costs

The bytes are stored uncompressed in the binary, so a large asset directory makes a large executable. A program that serves big files should keep them outside and read them at run time; a program that needs a small template or a JSON schema should embed them and stop worrying about the working directory. The choice is visible in go tool nm and in the build size, and it is worth measuring before embedding a megabyte of fixtures into a command-line tool.

Exercises

  1. Embed a directory with a subdirectory and list it with fs.WalkDir. Do the names include the top directory?
  2. Serve the embedded tree with http.FileServer(http.FS(data)) and fetch a file with a test server. Which paths are valid?
  3. Embed a file with a typo in the pattern and read the build error. At which step does the toolchain notice?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What can //go:embed fill?

    Answer

    A string, a []byte or an embed.FS

    Those three are the supported variable types.

  2. Where must the directive be?

    Answer

    Immediately above the package-level variable it fills

    The variable is package level and the directive is adjacent.

  3. Why import embed when only a string is embedded?

    Answer

    The compiler looks for the package that provides the directive

    The import is a marker for the compiler.

  4. What happens when a pattern matches no file?

    Answer

    The build fails

    A typo is caught at compile time.

  5. What does an embedded directory give you?

    Answer

    An embed.FS that implements fs.FS

    fs.ReadDir, fs.ReadFile and http.FileServer all accept it.

  6. What does embedding cost?

    Answer

    The bytes are stored in the binary

    Size is the trade for not needing the file at run time.

  7. Can a pattern reach outside the package directory?

    Answer

    No, the toolchain refuses it

    Embedded files belong to the package that declares them.

  8. Are hidden files embedded by a directory pattern?

    Answer

    No, unless the pattern names them explicitly

    This is a documented and often surprising rule.

  9. What does go build -ldflags='-s -w' change?

    Answer

    It strips the symbol table and debug information, making the binary smaller

    The embedded bytes stay; the metadata goes.

  10. Which standard-library consumer works directly with an embedded tree?

    Answer

    http.FileServer

    It takes an fs.FS, which embed.FS provides.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev