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
- Embed a directory with a subdirectory and list it with fs.WalkDir. Do the names include the top directory?
- Serve the embedded tree with http.FileServer(http.FS(data)) and fetch a file with a test server. Which paths are valid?
- 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.
-
What can //go:embed fill?
Answer
A string, a []byte or an embed.FS
Those three are the supported variable types.
-
Where must the directive be?
Answer
Immediately above the package-level variable it fills
The variable is package level and the directive is adjacent.
-
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.
-
What happens when a pattern matches no file?
Answer
The build fails
A typo is caught at compile time.
-
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.
-
What does embedding cost?
Answer
The bytes are stored in the binary
Size is the trade for not needing the file at run time.
-
Can a pattern reach outside the package directory?
Answer
No, the toolchain refuses it
Embedded files belong to the package that declares them.
-
Are hidden files embedded by a directory pattern?
Answer
No, unless the pattern names them explicitly
This is a documented and often surprising rule.
-
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.
-
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