//go:embed for Files and Templates

//go:embed tells the compiler to copy files into your package so they ship inside the binary.

You read them through string, []byte, or embed.FS without opening paths on the deployment host.

Summary

go:embed landed in Go 1.16 and replaced most bindata-style code generators for static assets.

The directive applies to variables in the same package, using glob patterns relative to the source file.

embed.FS implements io/fs.FS, so http.FileServer, fs.WalkDir, and template.ParseFS compose naturally.

Embedded data is read-only; mutate copies in memory if you need to change content at runtime.

Recipe

Quick-reference recipe card - copy-paste ready.

package assets
 
import "embed"
 
//go:embed migrations/*.sql
var Migrations embed.FS
 
//go:embed config/default.yaml
var DefaultConfig []byte

When to reach for this:

• Shipping SQL migrations or default YAML/JSON with a CLI or service.
• Bundling HTML templates and static UI for a single-binary deployment.
• Guaranteeing assets exist in tests without fixture path gymnastics.
• Building tools that must run offline without a config directory.

Working Example

example.com/app/
  main.go
  assets/
    migrations/
      001_init.sql
    templates/
      home.html

// main.go
package main
 
import (
    "embed"
    "html/template"
    "io/fs"
    "log"
    "net/http"
)
 
//go:embed assets/migrations/*.sql
var migrations embed.FS
 
//go:embed assets/templates/*.html
var templates embed.FS
 
func main() {
    sql, err := fs.ReadFile(migrations, "assets/migrations/001_init.sql")
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("migration bytes: %d", len(sql))
 
    tpl, err := template.ParseFS(templates, "assets/templates/*.html")
    if err != nil {
        log.Fatal(err)
    }
 
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        _ = tpl.ExecuteTemplate(w, "home.html", nil)
    })
    log.Fatal(http.ListenAndServe(":8080", nil))
}

What this demonstrates:

• Multiple //go:embed variables can live in one package.
• FS paths retain the directory prefix from the pattern (assets/migrations/...).
• template.ParseFS loads templates without disk paths at runtime.

Deep Dive

How It Works

1. The compiler scans //go:embed comments above package-level variables.
2. Matching files are read from the module source tree during compilation.
3. Bytes are stored in the compiled package metadata and linked into the final binary.
4. At runtime, embed.FS serves those bytes through io/fs APIs.
5. No init hook reads the filesystem on the target machine.

Pattern Rules

Serving Static Files

//go:embed static/*
var static embed.FS
 
sub, _ := fs.Sub(static, "static")
http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(sub))))

fs.Sub drops the embedded prefix so URLs map cleanly.

Go Notes

import _ "embed" // required when using //go:embed without referencing embed in code

If you only embed into []byte and never name embed.FS, the blank import satisfies the compiler.

Gotchas

• Wrong FS path - ReadFile uses the full embedded path including directories from the pattern. Fix: log fs.WalkDir once or match the pattern prefix exactly.
• Expecting hot reload - embedded content is fixed at build time. Fix: use build tags to swap embed vs disk in dev.
• Large binaries - embedding multi-megabyte assets bloats every deploy. Fix: host big media externally; embed only what must be local.
• Secrets in embed - files on the build machine get baked in. Fix: never embed production secrets; inject at runtime.
• Tests and working directory - embed ignores os.Chdir in tests because data is not read from disk at runtime. Fix: test through the embedded FS APIs.
• Template name mismatches - ExecuteTemplate uses the template's defined name, not always the file name. Fix: call tpl.DefinedTemplates() during development.

Alternatives

FAQs

Related

• Beyond the Spec: Embed, Build Modes, and Assembly - conceptual overview
• Advanced Language Features Basics - intro embed examples
• Build Constraints & Platform-Specific Files - per-platform embed sets
• Packages & Modules Basics - module layout for assets

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).