Go Reference ยท Errors, I/O and Files
Go embed package and //go:embed directive
Reference for Go's embed package and //go:embed directive: embed a file as string, []byte or embed.FS, patterns, hidden files and common build errors.
The embed package lets a Go program carry files inside its own executable. You put a //go:embed comment directly above a package-level variable, and the compiler copies the named files into the binary. At run time the data is just there: no installation step, no missing-template errors and no path to get wrong.
A variable can receive one file as a string or []byte, or any number of files and directories as an embed.FS, a read-only file system that implements io/fs.FS. Typical uses are HTML templates, SQL migrations, static web assets, default configuration and test data.
import _ "embed" //go:embed banner.txt var banner string
Try it
The Go runner on this site compiles a single file, so there are no extra files next to main.go to embed. These examples show the directive's shape and how an embed.FS behaves by using the empty file system and an in-memory stand-in with the same fs.FS interface.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
//go:embed pattern ... var name string // one file, text var name []byte // one file, bytes var name embed.FS // files and directories
The directive must sit directly above the var (only blank lines and // comments may come between them), the variable must be at package level, and the file must import "embed" (use import _ "embed" if you only embed into string or []byte).
| Pattern rule | Description |
|---|---|
| Paths are relative | Relative to the directory of the Go source file; no leading /, no .., no . elements. |
| Patterns | path.Match syntax: *.html, static/*.css. No **. |
| Directories | static embeds the tree recursively, except names starting with . or _. |
all: prefix |
//go:embed all:static includes dotfiles and _ files too. |
| Multiple patterns | Separate with spaces; quote names containing spaces. |
| Modules | Files must be in the same module, and not inside a nested module. |
embed.FS methods: Open(name), ReadFile(name) and ReadDir(name). Names use forward slashes and are rooted at the directory of the source file, for example "templates/home.html".
Errors and edge cases:
- A pattern that matches nothing is a compile error ("pattern ...: no matching files found").
- Embedding into a type other than
string,[]byteorembed.FSis a compile error. embed.FS.ReadFileof a missing file returns an*fs.PathErrorwrappingfs.ErrNotExist.- Symbolic links, irregular files and
.gitdirectories cannot be embedded.
Usage notes
- Read-only and immutable:
stringis immutable; the[]bytevariant gives you your own copy you may modify, whileembed.FSdata is shared and cannot be changed. - Binary size grows by the size of the files. Embedded data is not compressed.
- Use
fs.Sub(assets, "static")to serve a subdirectory without its prefix:http.FileServerFS(sub)(Go 1.22). - Templates:
template.ParseFS(assets, "templates/*.html")parses embedded templates. - Directory embeds skip
_and.files unless you useall:; surprised "file not found" errors usually come from this. - Changes need a rebuild, which is the point: the version of the files always matches the binary. For development, you can swap
embed.FSforos.DirFSbehind the samefs.FSvariable. go list -jsonshowsEmbedPatternsandEmbedFilesof a package.- The directive works only in files that import
embed; build constraints decide which embeds apply on each platform.