Skip to content
Tutorials Center
My learning

Topics

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.

Go
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.

Go Using embed.FS through fs.FS (with a stand-in)

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.

Go Embedding a file in the program itself

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
//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, []byte or embed.FS is a compile error.
  • embed.FS.ReadFile of a missing file returns an *fs.PathError wrapping fs.ErrNotExist.
  • Symbolic links, irregular files and .git directories cannot be embedded.

Usage notes

  • Read-only and immutable: string is immutable; the []byte variant gives you your own copy you may modify, while embed.FS data 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 use all:; 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.FS for os.DirFS behind the same fs.FS variable.
  • go list -json shows EmbedPatterns and EmbedFiles of a package.
  • The directive works only in files that import embed; build constraints decide which embeds apply on each platform.