{"article":{"slug":"how-go-embed-works-from-source-files-to-binary","title":"How //go:embed Works: From Source Files to Binary","subtitle":null,"summary":"A guest post by Ainsley Clark on Internals for Interns that explains what the //go:embed directive is, how to use embed.FS, how the go command, compiler and linker carry embedded files into the binary, how the runtime reads them, and the tradeoffs involved.","content_type":"tutorial","language":"en","canonical_url":"https://internals-for-interns.com/posts/how-go-embed-works/","author":{"name":"Ainsley Clark","url":null,"person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"Internals for Interns","url":null,"listing_slug":null,"listing":null},"topics":[{"name":"programming","slug":"programming","url":"https://listedarticles.com/topics/programming"},{"name":"compilers","slug":"compilers","url":"https://listedarticles.com/topics/compilers"},{"name":"software-engineering","slug":"software-engineering","url":"https://listedarticles.com/topics/software-engineering"}],"about_listings":[],"cover_image_url":null,"license":"all-rights-reserved","word_count":5517,"reading_minutes":24,"published_at":"2026-11-02T08:00:00.000Z","added_at":"2026-11-04T14:09:15.162Z","updated_at":"2026-11-04T14:09:15.162Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":true},"profile_url":"https://listedarticles.com/articles/how-go-embed-works-from-source-files-to-binary","markdown_url":"https://listedarticles.com/articles/how-go-embed-works-from-source-files-to-binary.md","example":false,"citation":"Ainsley Clark, Internals for Interns. \"How //go:embed Works: From Source Files to Binary.\" 2 Nov 2026. https://internals-for-interns.com/posts/how-go-embed-works/ (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://internals-for-interns.com/posts/how-go-embed-works/"},"body_markdown":"# How //go:embed Works: From Source Files to Binary\n\nBy Ainsley Clark (guest post), November 2, 2026\n\n> I’m unreasonably excited about this feature. I feel like I always have some big ol’ JSON or\n> template or something chilling in a constant making the file looking more unruly than it actually\n> is, but don’t want to ship the file with the binary or bring in some sort of 3rd party tool like\n> packr into the mix.\n>\n> [u/RyanTheKing](https://reddit.com/r/golang/comments/kfm4ly/embed_files_in_go_using_new_embed_package_in_go/gg9eonu/)\n\nSo let’s have a look into `//go:embed`, to see how to use it, but also see how it works under the\nhood; so you’re able to make more informed decisions when shipping static assets alongside your\nprograms.\n\n## Contents\n\n- [The directive: What it is](#the-directive-what-it-is)\n- [The variable: How to use it](#the-variable-how-to-use-it)\n- [The binary: How it’s built](#the-binary-how-its-built)\n- [The runtime: How it’s read](#the-runtime-how-its-read)\n- [The tradeoffs: What you take on](#the-tradeoffs-what-you-take-on)\n\n---\n\n## The directive: What it is\n\nSo how do we use it? Here’s a simple example to whet your appetite:\n\n```\n//go:embed version.txt\nvar version string\n```\n\n- We have what looks like a go comment, but it’s actually a Go directive, sometimes called\n  pragmas (if you’re working with the compiler). You may have seen these before as `go:generate` or\n  `go:build`.\n- After writing `//go:embed` we specify the relative file path to where the file is located.\n- In the next line, we specify the variable name we want to use. Which is where the go compiler\n  will read the file contents and bake all of that lovely data into the binary before your\n  program runs.\n- The variable is just a pointer to the file contents; the magic happens in the build.\n\nBefore we get into any of that, it’s worth remembering the problem this was built to solve.\n\n### We’ve all seen this?\n\nI’m sure we’ve all seen something like this before:\n\n```\n$ docker run myapp\n2026/09/09 open ./static/app.css: no such file or directory\n```\n\nHow annoying is this to debug? It’s usually not difficult or cumbersome, but fiddly and\ntime-consuming. You usually have to debug some weird absolute/relative path fiasco or go into some\nglob patterns. This is exactly why an embed feature was needed, it makes static assets incredibly\neasy to ship.\n\n### What it is not\n\nWe’ve talked about what `//go:embed` is, but let’s just touch on what it isn’t for a moment.\n\n- Don’t think that it’s a way to compress your files; a megabyte is a megabyte. Go doesn’t care or\n  manipulate your data in any way.\n- It’s also not a build pipeline, as mentioned above. Go doesn’t minify, transpile or fingerprint\n  anything; it just copies bytes.\n- It’s also not dynamic, it’s run at compile time, not run time. The bytes are locked in when you\n  run `go build`. So if you tweak a template and expect it to update, it won’t. There’s no hot\n  reload anywhere.\n- And it’s not a media server, please don’t be going embedding your favourite Netflix films.\n  Coincidentally, there’s actually a 2GB limit (I tried, believe me). But seriously, use object\n  storage or something else for storing large files.\n\n---\n\n## The variable: How to use it\n\nSo now we’ve seen what it is, let’s remind ourselves how to use it on a high level. If you’re\nfamiliar with the concepts of how to use it, feel free to skip\nthis [section](#the-binary-how-its-built)\n.\n\nThere are three data types we can use with `//go:embed`; a string, a byte slice and a read-only\nfile system. Here are all three of them in one program:\n\n```\nimport \"embed\" // Or import _ \"embed\"\n\n//go:embed version.txt\nvar version string\n\n//go:embed schema.sql\nvar schema []byte\n\n//go:embed assets/*\nvar assets embed.FS\n\nfunc main() {\n\tfmt.Println(version) // v1.4.2\n\tdb.Exec(string(schema))\n\n\tcss, _ := assets.ReadFile(\"assets/index.css\")\n\tfmt.Println(string(css)) // body { margin: 0 }\n}\n```\n\nWe first need to import the `embed` package. The import isn’t blank here because we’re naming\n`embed.FS` below, so we need the package itself. A blank import (`import _ \"embed\"`) is for when\nyou’re only embedding into strings and byte slices. Either way, it sends a signal to the compiler\nthat we need to embed data, and you’ll see exactly how that works later on.\n\nThen it’s one directive per variable, one type each:\n\n- **A string**, our `version.txt` from the last section. Good for anything you’re going to read as\n  text; a version number, a template, a licence.\n- **A byte slice**, here an SQL schema. But we could really use it with anything, a config file,\n  TLS cert, font, image, and much more. Use bytes when it makes sense for how the data is used in\n  your program.\n- **An `embed.FS`**, a whole folder. This is the part that sets Go apart from most languages, and\n  it’s great for web assets, templates, migrations and whatever else you fancy.\n\nAnd then we just use them. They’re variables. No `os.Open`, no path fiddling, no “did I ship the\nmigrations folder?”. The contents are already there, just like any other variable in your program.\nNote that a file inside an `FS` keeps the path it was embedded with, which is why we’re asking for\n`assets/index.css` rather than just `index.css`.\n\n### embed.FS\n\nThe `FS` type has a bit more going on with it, so it’s worth a proper look.\nYou can see the methods below: `Open`, `ReadDir` and `ReadFile`.\n\n```\n// An FS is a read-only collection of files.\ntype FS struct {}\n\nfunc (f FS) Open(name string) (fs.File, error) // Satisfies fs.FS\nfunc (f FS) ReadDir(name string) ([]fs.DirEntry, error)\nfunc (f FS) ReadFile(name string) ([]byte, error)\n```\n\nThe most important thing to note is that it satisfies the `fs.FS` interface, which means we can use\nit in many different ways. It makes it easy to plug and play across packages, such as\n`http.FileServer` to serve it as a static site or `template.ParseFS` to parse HTML templates.\n\n```\n// An FS provides access to a hierarchical file system.\ntype FS interface {\n\tOpen(name string) (File, error)\n}\n```\n\n### Working example\n\nBefore we dive any deeper, let’s give ourselves a folder to work with. This is the example we’ll\nbe coming back to all the way down to the linker, so it’s worth a proper look.\n\nWe’re serving a normal website. An `index.html` at the root, and some `css` and `js` in a folder\ncalled `assets`. No more, no less.\n\n```\n.\n├── main.go\n├── index.html (<h1>Hello</h1>)\n└── assets\n    ├── index.css\n    └── index.js\n```\n\nTo embed that into the program, we create a string variable for the contents of `index.html`, and an\n`embed.FS` for the contents of the `assets` folder, and then just print them. In a production\nenvironment you’d serve these through a handler, but we’ve kept it simple for now.\n\n```\npackage main\n\nimport (\n\t\"embed\"\n\t\"fmt\"\n)\n\n//go:embed index.html\nvar indexHTML string\n\n//go:embed assets/*\nvar static embed.FS\n\nfunc main() {\n\tfmt.Println(indexHTML) // <h1>Hello</h1>\n\tcss, _ := static.ReadFile(\"assets/index.css\")\n\tfmt.Println(string(css)) // body { background: red; }\n}\n```\n\nThe `assets/*` pattern gets us every file in that folder; naming the directory on its own\n(`//go:embed assets`) takes the whole tree instead. The difference isn’t only depth: naming the\ndirectory skips every file beginning with `.` or `_` anywhere beneath it, where the `/*` glob still\npulls those in at the top level. Write `all:assets` when you want the whole tree, dotfiles and all.\nThere are more gotchas in the [pkg.go.dev/embed](https://pkg.go.dev/embed)\ndocs.\n\n---\n\n## The binary: How it’s built\n\nNow that we know what `//go:embed` is, we’ve seen how it works. Let’s dive a little bit deeper to\nsee how it’s constructed under the hood. If I were to show you a bunch of code from the Go\ncompiler out of context in the next section, I’ll probably have you lost; like it did me for a few\ndays researching into how Go is built (TLDR; it’s challenging but worth it).\n\nEverything below was read against **Go 1.27.1**, and every file and line number links to that tag\non GitHub, so the lines quoted here stay put even after the toolchain moves on.\n\n### Compiler basics\n\nSo before we go anywhere near how go is built, let’s zoom all the way out. When you type `go build`,\nsix steps run in order and out the other end comes a binary. This is the path that matters for\n`//go:embed`; it isn’t everything the toolchain does, just the part your files travel through.\n\nI’m aware that there’s a whole heap of stuff that we’re not going into here such as SSA,\ninlining, escape analysis, etc… But none of it really touches the embed packages, because your\ndata never becomes instructions; they are just bytes after all.\n\nThe first thing worth knowing is that there isn’t one program doing all of this. There are several,\neach responsible for its own thing, and `go build` is the one that runs the other two.\n\n![Overview](https://internals-for-interns.com/images/posts/go-embed-1-overview.svg)\n\n*go build: six steps, three programs*\n\nSo what are we looking at here?\n\n1. **Packages**: The `go` command starts by reading your `.go` files and working out what package\n   each one is in.\n2. **Lexer**: The lexer chops that text up into tokens, and while it’s in there it reads the\n   comments looking for pragmas, which is where your `//go:embed` lines get spotted.\n3. **Patterns**: Turns each `//go:embed` pattern into a list of real files on the disk and hands that\n   list to the compiler.\n4. **Parser**: Will then arrange those tokens into a syntax tree (`AST`) that describes the structure\n   of your code.\n5. **Compiler**: Then checks the tree and turns it into machine code. What comes out is one object\n   archive per package, which is code that can’t run on its own yet.\n6. **Linker**: Is what ties everything together, along with the Go runtime, into the binary you\n   build.\n\nNotice the three different sections, that’s the bit that tripped me up for the longest, `go`\nruns once for the whole build, `compile` runs once *per package*, and `link` runs once at the\nend. It’s an important nuance to understand.\n\nCheck out [go.dev/src/cmd/compile/README](https://go.dev/src/cmd/compile/README)\nfor more information.\n\n### Packages (`go build`)\n\nSo now, onto the juicy bits. Let’s start with how Go looks at your project. When you run `go build` it needs to know what files and packages exist, so it knows what to parse and build.\n\nA package directory goes in, and a `*build.Package` comes out. So it walks your project, finds every\n`.go` file and then works out which package each one belongs to. For every file, it notes down where\nit lives, what it imports, and any directives (such as `//go:embed`) that it carries.\n\n![Packages](https://internals-for-interns.com/images/posts/go-embed-2-packages.svg)\n\n*Packages: walking the package directory*\n\nYou can see our `assets/` folder and `index.html` being skipped, because they aren’t Go files and\nthis pass only cares about Go. `main.go` makes it through the condition into `matchFile`, and\nout the other side comes a `Package` which details its name, its Go files, and the position of\nevery `//go:embed` pattern in it.\n\n```\nfunc (ctxt *Context) Import(path string, srcDir string, mode ImportMode) (*Package, error) {\n\tfor _, d := range ctxt.readDir(p.Dir) {          // walk the package dir\n\t\tname := d.Name()\n\t\tif filepath.Ext(name) != \".go\" {             // main.go, index.html, assets/…\n\t\t\tcontinue\n\t\t}\n\t\tinfo, _ := ctxt.matchFile(p.Dir, name, ...)  // reads header, scans comments, gets embed\n\t\tp.GoFiles = append(p.GoFiles, name)\t\t\t // [\"main.go\"]\n\t\tp.Name = info.parsed.Name.Name               // main\n\t\n\t\tfor _, emb := range info.embeds {\n\t\t\t// {\"index.html\": [main.go:10], \"assets/*\": [main.go:13]}\n\t\t\tembedPos[emb.pattern] = append(embedPos[emb.pattern], emb.pos)\n\t\t}\n\t}\n}\n```\n\n**Reference**: [`src/go/build/build.go`](https://github.com/golang/go/blob/go1.27.1/src/go/build/build.go)\n(`(*Context).Import`, simplified)\n\nOur `//go:embed index.html` and `//go:embed assets/*` have been spotted and recorded along with\ntheir file names and token positions.\n\nBut how did it spot the comment originally? This is where the lexer comes into play.\n\n### Lexer (`go build`)\n\nThe lexer (or scanner, or tokeniser, whatever you fancy) is the first thing that actually reads your\ncode as *Go*, rather than as a blob of bytes. It scans the file one character at a time and chops it\nup into little tokens, which are the pieces of code that mean something on their own. Such as\n`func`, `var`, `=`, a string literal, or a comment.\n\nThis is the stage that makes `//go:embed` actually possible. In Go, a comment is a real token\n(`token.COMMENT`).\n\n![Lexer](https://internals-for-interns.com/images/posts/go-embed-3-lexer.svg)\n\n*Lexer: one character at a time, into tokens*\n\nCharacters go in and tokens come out. The whole `//go:embed index.html` line becomes a single\n`COMMENT` token, and the two words of `var indexHTML string` become a `VAR` and two `IDENT`s.\n\nThe `go` command’s scan is deliberately inexpensive as it stops at the end of the import block,\nbecause that’s normally all it needs. Unless, however it saw `import \"embed\"` on the way past,\nin which case it reads on to the end of the file, picking out every\ncomment starting `//go:embed`:\n\n```\nif hasEmbed {\n    r.readRest() // keep going: read the rest of the file after all\n    sc.Init(file, r.buf, nil, scanner.ScanComments) // get comments as tokens\n\t\n    for {\n        pos, tok, lit := sc.Scan()\n        if tok == token.COMMENT && strings.HasPrefix(lit, \"//go:embed\") {\n            // in:  `//go:embed index.html`\n            // out: {pattern: \"index.html\", pos: ...}\n            embs, _ := parseGoEmbed(fset, pos, lit)\n            info.embeds = append(info.embeds, embs...)\n        }\n    }\n}\n```\n\n**Reference**: [`src/go/build/read.go#L374-L392`](https://github.com/golang/go/blob/go1.27.1/src/go/build/read.go#L374-L392)\n(`readGoInfo`, simplified)\n\nThat `hasEmbed` flag is the real reason `import _ \"embed\"` is mandatory even when you never type the\npackage name. If you don’t import the package, we’ll never go into this code block.\n\nWhat comes out is a list of the patterns it found, and where each one was written:\n\n```\n[]fileEmbed{\n    {pattern: \"index.html\", pos: main.go:10:12},\n    {pattern: \"assets/*\",   pos: main.go:13:12},\n}\n```\n\nWe now have patterns to file names and line numbers, but there are no files? This is where resolving\nembed patterns comes in.\n\n### Patterns (`go build`)\n\nWithin the `go command` we have a fairly important function called `resolveEmbed` which resolves\npatterns into actual files and trees. File patterns go in, and real file paths come out.\n\n![Patterns](https://internals-for-interns.com/images/posts/go-embed-4-patterns.svg)\n\n*Patterns: resolveEmbed turns patterns into files*\n\nThe glob is where it gets interesting. Our `index.html` was only ever going to match itself, but\n`assets/*` fans out to `assets/index.css` and `assets/index.js`, neither of which we named anywhere.\nThat’s the first time anything in this whole process has actually gone and looked at your disk.\n\nSo these patterns get expanded, globbing it against the disk and walking any directory it\nmatches, into a list of actual file names. You can see this in action below:\n\n```\nfunc resolveEmbed(pkgdir string, patterns []string) (files []string, pmap map[string][]string, err error) {\n    pmap = make(map[string][]string)\n    have := make(map[string]bool) // every file, once\n\n    // patterns = []string{\"index.html\", \"assets/*\"}\n    for _, pattern := range patterns {\n        matches, _ := fsys.Glob(pkgdir + \"/\" + pattern)\n\n        var list []string\n        for _, match := range matches {\n            if fsys.IsDir(match) {\n                fsys.WalkDir(match, func(path string, ...) { list = append(list, path) })\n            } else {\n                list = append(list, match)\n            }\n        }\n\n        pmap[pattern] = list // what this pattern matched\n        for _, f := range list {\n            have[f] = true   // ...and the running set of all of them\n        }\n    }\n\n    for f := range have {\n        files = append(files, f)\n    }\n\n    return files, pmap, nil\n}\n```\n\n**Reference**: [`src/cmd/go/internal/load/pkg.go#L2165`](https://github.com/golang/go/blob/go1.27.1/src/cmd/go/internal/load/pkg.go#L2165)\n(`resolveEmbed`, simplified)\n\nOutput will now be:\n\n```\n// pmap:\nmap[string][]string{\n     \"assets/*\":   {\"assets/index.css\", \"assets/index.js\"},\n     \"index.html\": {\"index.html\"},\n}\n\n// files:\n[]string{\"assets/index.css\", \"assets/index.js\", \"index.html\"}\n```\n\nThose two return values become the two data points that the compiler needs:\n\n- `Patterns` answers “what did this pattern match?” and keeps the duplicates, because that’s the tree\n  your `embed.FS` gets, and two different patterns can easily match the same file.\n- `Files` answers “where do I read those bytes?” and cannot have duplicates, because the compiler\n  should open each file exactly once.\n\nThe `go` command marshals them into JSON, writes it to a file called `embedcfg` in the build’s\ntemporary work directory, and passes that path to the compiler as `-embedcfg`, once per package.\n\nWhy a file, why not just hand it over directly? Because `go build` and the compiler are two separate\nprocesses, as we saw in that first diagram, so it gets written down instead.\n\nFor our example project, the generated `embedcfg` looks like:\n\n```\n{\n\t\"Patterns\": {\n\t\t\"assets/*\": [\n\t\t\t\"assets/index.css\",\n\t\t\t\"assets/index.js\"\n\t\t],\n\t\t\"index.html\": [\n\t\t\t\"index.html\"\n\t\t]\n\t},\n\t\"Files\": {\n\t\t\"assets/index.css\": \"/home/user/project/assets/index.css\",\n\t\t\"assets/index.js\": \"/home/user/project/assets/index.js\",\n\t\t\"index.html\": \"/home/user/project/index.html\"\n\t}\n}\n```\n\n**Reference**: [`work/exec.go#L893-L906`](https://github.com/golang/go/blob/go1.27.1/src/cmd/go/internal/work/exec.go#L893-L906)\nbuilds and marshals it, [`work/gc.go#L148-L152`](https://github.com/golang/go/blob/go1.27.1/src/cmd/go/internal/work/gc.go#L148-L152)\nwrites it and passes `-embedcfg` (simplified)\n\n(Tip: `go list -json=EmbedPatterns,EmbedFiles .` surfaces these exact matched patterns and files\nstraight from the package metadata, any time you want to look.)\n\n### Parser (`cmd/compile`)\n\nWe’re in a different program now. Tokens go in, along with the path to that `embedcfg`, and what\ncomes out is a tree with your directive attached to the right node.\n\nThe parser is where the real magic happens in the Go compiler. It takes those tokens and little\nbits of Go code and works out their structure. A bit like breaking a sentence down into a\nsubject, verb and object.\n\nThe result is a *syntax* tree; you may have heard of the term `AST` before, which is short for\n`abstract syntax tree`. It’s the building blocks of our program. Every piece of your code (a\nfunction, a variable, an if statement) becomes a *node* within that tree.\n\nDirectives such as `//go:embed` get attached to the node, which is how Go knows which variable to\nput your embedded file in.\n\nThe below example is captured from the two lines from our example above:\n\n```\n//go:embed index.html\nvar indexHTML string\n```\n\n![Parser](https://internals-for-interns.com/images/posts/go-embed-5-parser.svg)\n\n*Parser: the directive and the variable are one node*\n\n- **`GenDecl`**: Is the declaration as a whole, it’s short for a `generic declaration node`\n  which represents an import, constant, type or variable declaration. In our example, it’s  \n  both the comment, and the variable.\n- **`Doc`**: Is the comment, held as a `*ast.CommentGroup`. Our `//go:embed index.html` is in\n  there, kept word for word in `Text`.\n- **`Specs`**: Is what that declaration actually declares which is an `*ast.ValueSpec` holding the\n  name `indexHTML` and the type `string`, our variable.\n\nBoth the `Doc` and `Specs` come under `GenDecl`. The comment and the variable aren’t two things that\nhappen to be near each other in a file; they’re two branches of one node. That’s how the compiler\nknows the contents of `index.html` go into `indexHTML`, and not into whatever is declared next.\n\nWhich looks like this. The dump is `go/ast`, which is what `ast.Print` gives you and what most\ntooling reads. The compiler’s own parser is `cmd/compile/internal/syntax` and holds the same shape\nunder different names, which is why `checkEmbed` in the next section takes a `*syntax.VarDecl`:\n\n```\n1: *ast.GenDecl {\n.  Doc: *ast.CommentGroup {\n.  .  List: []*ast.Comment (len = 1) {\n.  .  .  0: *ast.Comment {\n.  .  .  .  Slash: main.go:8:1\n.  .  .  .  Text: \"//go:embed index.html\"\n.  .  .  }\n.  .  }\n.  }\n.  TokPos: main.go:9:1\n.  Tok: var\n.  Specs: []ast.Spec (len = 1) {\n.  .  0: *ast.ValueSpec {\n.  .  .  Names: []*ast.Ident (len = 1) {\n.  .  .  .  0: *ast.Ident {\n.  .  .  .  .  NamePos: main.go:9:5\n.  .  .  .  .  Name: \"indexHTML\"\n.  .  .  .  }\n.  .  .  }\n.  .  .  Type: *ast.Ident {\n.  .  .  .  NamePos: main.go:9:15\n.  .  .  .  Name: \"string\"\n.  .  .  }\n.  .  }\n.  }\n}\n```\n\nClever stuff, right? This was the aha moment for me. The comment and variable are one declaration\nin Go’s eyes.\n\n### Compiler (`cmd/compile`)\n\nNow onto the nuts and bolts, the compiler. A tree goes in, and what comes out is an *object archive*,\none per package, which is your code compiled but not yet runnable on its own. This is also the stage\nwhere your data is actually allocated.\n\nEverything so far has been bookkeeping; finding files, expanding patterns and writing lists, but not\none byte of your `index.html` has actually been allocated into your program. However, in this step,\nit does.\n\nThe compiler lays your variable out in memory and fills it with the file’s contents, as static data,\nthat’s there before your program runs a single line of your app’s code.\n\nAlthough its first job isn’t your files at all, it’s the rules. Remember, the `go` command spotted\nyour directive and wrote the pattern down, but it never checked anything about it, which is\nmentioned in the comments:\n\n```\n// The compiler will enforce the mapping of comments to\n// declared variables. We just need to know the patterns.\n```\n\n**Reference**: [`src/go/build/read.go#L369-L373`](https://github.com/golang/go/blob/go1.27.1/src/go/build/read.go#L369-L373)\n(`readGoInfo`)\n\nNow it checks what you’ve written is actually valid. Nearly every `//go:embed` error message you’ve\nprobably seen comes from this switch statement:\n\n```\nfunc checkEmbed(decl *syntax.VarDecl, haveEmbed, withinFunc bool) error {\n\tswitch {\n\tcase !haveEmbed: // The file never imported \"embed\".\n\t\treturn errors.New(`go:embed only allowed in Go files that import \"embed\"`)\n\tcase len(decl.NameList) > 1: // var a, b string\n\t\treturn errors.New(\"go:embed cannot apply to multiple vars\")\n\tcase decl.Values != nil: // var s string = \"hello\"\n\t\treturn errors.New(\"go:embed cannot apply to var with initializer\")\n\tcase withinFunc: // Declared inside a func body.\n\t\treturn errors.New(\"go:embed cannot apply to var inside func\")\n\t}\n\treturn nil\n}\n```\n\n**Reference**: [`src/cmd/compile/internal/noder/noder.go#L462-L481`](https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/noder/noder.go#L462-L481)\n(`checkEmbed`, simplified)\n\nBut how is the data read?\n\n![Compiler](https://internals-for-interns.com/images/posts/go-embed-6-compiler.svg)\n\n*Compiler: WriteEmbed lays `<h1>Hello</h1>` out as 14 bytes of read-only data*\n\n```\n// WriteEmbed, for our `var indexHTML string`.\ncase embedString, embedBytes:\n\tfile := files[0]                        // \"index.html\", from the embedcfg JSON\n\tpath := base.Flag.Cfg.Embed.Files[file] // \"/home/user/project/index.html\"\n\tfsym, size, _ := fileStringSym(v.Pos(), path, ...) // read it, name the bytes\n\n\tsym, off := v.Linksym(), 0                 // indexHTML itself\n\toff = objw.SymPtr(sym, off, fsym, 0)       // field 1: pointer to those bytes\n\toff = objw.Uintptr(sym, off, uint64(size)) // field 2: length\n\tif kind == embedBytes {\n\t\tobjw.Uintptr(sym, off, uint64(size))   // field 3: cap, because a slice has one\n\t}\ncase embed.FS:\n\t// See source files below...\n```\n\n**Reference**: [`src/cmd/compile/internal/staticdata/embed.go#L101-L134`](https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/staticdata/embed.go#L101-L134)\n(`WriteEmbed`, simplified)\n\nHere we can see `WriteEmbed` switching on the variable’s data type. It then goes on to call a\nfunction called `fileStringSym`, which opens your file and returns a symbol for its contents, as\nwell as the size.\n\nOkay, but what’s a symbol? Forget `[]byte` for a second. A symbol is a box with a name on it, what\nit’s called, how big it is, and where it lives in the binary. That’s what the linker actually needs\nto do its job, and it’s why `fileStringSym` hands one back rather than the bytes themselves.\nThis is where your asset has stopped being a path and has actually become data.\n\nThe rest is ordinary compilation. The tree gets turned into machine code\n(`cmd/compile/internal/ssagen`), and out comes one *object archive* per package, which is code that\ncan’t run yet, which is where the linker comes into play.\n\n### Linker (`cmd/link`)\n\nAlthough the linker has little to do with `//go:embed`, it plays a crucial part in the\nbuild process. It’s a separate program, located under `cmd/link`. Many `.a` files go in, and one\nexecutable comes out. All of the object archives that we mentioned above, now are joined together.\nIt fills in all the gaps so every piece can find the others.\n\nWhich is where the Go runtime is injected. The runtime is built-in code that manages memory,\ngoroutines and all of the stuff that makes Go, Go.\n\n![Linker](https://internals-for-interns.com/images/posts/go-embed-7-linker.svg)\n\n*Linker: object archives and the runtime become one binary*\n\nThere’s `main.a` still carrying our 14 bytes, along with `fmt.a`, `embed.a`, every other package you\npulled in, and `runtime.a`. On the right is what they become, one binary, and our `<h1>Hello</h1>`\nsitting in the `rodata` section, which is where read-only data lives.\n\n### Binary\n\nNow run it (`./myapp`) and voilà! We have your finished program; maybe we should take a\nbreather…\n\n### Build Summary\n\nI know that was a lot to take in, so let’s go back to where we started and walk it once more, now\nthat all the names mean something. I always find this easier to read as pseudocode, so here we go.\nIt isn’t real or runnable; it just connects all the dots:\n\n```\nimport (\n\t\"go/build\"                        \t// 1. Packages: what's in this package?\n\t\t\t\t\t\t\t\t\t\t// 2. Lexer:    text -> tokens\n\t\"cmd/go/internal/load\"            \t// 3. Patterns: \"assets/*\" -> real paths on disk\n\t\"cmd/compile/internal/syntax\"     \t// 4. Parser:   tokens -> syntax tree\n\t\"cmd/compile/internal/staticdata\" \t// 5. Compiler: file bytes -> read-only data\n\t\"cmd/link/internal/ld\"            \t// 6. Linker:   object files -> the binary\n)\n\nfunc goBuild(dir string) Binary {\n\tpkg := build.ImportDir(dir) // files, imports, embed patterns\n\t\n\tvar objs []Object\n\tfor _, p := range pkg.Deps {\n\t\tembeds := load.ResolveEmbed(p.Dir, p.EmbedPatterns) // \"assets/*\" -> [assets/index.css, ...]\n\t\ttree := syntax.Parse(p.GoFiles)                     // code + directives -> tree\n\t\n\t\tfor _, v := range tree.EmbedVars {\n\t\t\tdata := os.ReadFile(embeds[v.Pattern]) // the compiler opens your file\n\t\t\tstaticdata.WriteEmbed(v, data)         // and bakes the bytes in\n\t\t}\n\t\tobjs = append(objs, compile(tree)) // tree -> object file\n\t}\n\t\n\treturn ld.Link(objs, runtime) // -> the binary you ship\n}\n```\n\nThree separate processes, and they don’t run the same number of times, `go` runs once for the whole\nbuild, `compile` runs *once per package* and `link` runs once at the end. That’s why `embedcfg` is\nwritten per package, immediately before each `compile` invocation.\n\nAnd you don’t have to take my word for any of it. `go build -x` prints the real command lines and the\ntemporary directory, so you can watch `embedcfg` being written and passed along, and\n`ls $(go env GOROOT)/pkg/tool/$(go env GOOS)_$(go env GOARCH)/` shows you that `compile` and `link`\nreally are separate binaries sitting on your disk. Every **Reference** link above points at the exact\nlines in Go 1.27.1 if you’d like to read the real thing.\n\n---\n\n## The runtime: How it’s read\n\nSo the bytes are in the binary. The last question is what happens when your program actually\nopens them, because that depends on which of the three types you picked.\n\nFor a `string` or a `[]byte`, there’s almost nothing to tell, and that’s rather the point. The\ncompiler wrote a pointer and a length, and the pointer aims at bytes sitting in the `rodata` section\nwe just watched the linker build. Reading the variable is an ordinary variable read.\n\nAn `embed.FS` is more involved, and it’s the more interesting half. Remember it’s a single pointer to\na hidden list, and here’s what’s on the end of it:\n\n```\n// An FS is a read-only collection of files.\ntype FS struct {\n\tfiles *[]file\n}\n\n// A file is a single file in the FS.\ntype file struct {\n\tname string\n\tdata string\n\thash [16]byte // truncated SHA256 hash\n}\n```\n\n**Reference**: [`src/embed/embed.go#L151-L212`](https://github.com/golang/go/blob/go1.27.1/src/embed/embed.go#L151-L212)\n(`FS` and `file`, simplified)\n\nEach file’s contents are a `string`, pointing into the same read-only data our `indexHTML` did,\nso a 40MB asset isn’t sitting in your heap waiting for you.\n\nAsking for a file is a search, not a syscall. The list is sorted, so\n[`lookup`](https://github.com/golang/go/blob/go1.27.1/src/embed/embed.go#L243)\ndoes a binary search\nover it, and [`readDir`](https://github.com/golang/go/blob/go1.27.1/src/embed/embed.go#L272)\ndoes two\nof them to find where a directory starts and ends, then hands back that stretch of the slice. There’s\nno disk involved at any point, which is why `ModTime` on an embedded file is the zero time. There’s\nnothing there to have been modified.\n\nThere’s one detail worth the whole section, though, and it’s the difference between the two ways of\ngetting at your bytes. `Open` hands you back an `openFile` that reads straight out of that string,\ncopying only as much as fits the buffer you gave it. `ReadFile` ends looking a bit like this:\n\n```\nreturn []byte(ofile.f.data), nil\n```\n\n**Reference**: [`src/embed/embed.go#L322-L332`](https://github.com/golang/go/blob/go1.27.1/src/embed/embed.go#L322-L332)\n(`ReadFile`)\n\nThat conversion is a copy, and a fresh one on every call. So the 40MB asset that wasn’t sitting in\nyour heap a moment ago lands there the moment you call `ReadFile` on it. `Open` doesn’t; it fills\nyour buffer a chunk at a time, which is the path `http.FileServer` and `io.Copy` take. Neither\ntouches the disk, but only one of them allocates the file.\n\n---\n\n## The tradeoffs: What you take on\n\nYou’ve seen how it works and how it’s used, so let’s talk about what it costs you, because embedding\nisn’t free.\n\n### Rebuild to change a byte\n\nRemember what `WriteEmbed` did with those bytes. They’re read-only data in the object file now, which\nmeans your file isn’t really a file any more. So change one line of CSS, and you have to rebuild.\n\nThis can be a bit painful because nobody wants a full build on every save. The fix is the last\nin this section, so hold onto that.\n\n### No secrets\n\nAnd here’s the one that catches people out. Embedded bytes are just data in the binary, which means\nthey’re readable:\n\n```\n$ strings myapp | grep -i api_key\nAPI_KEY=sk_live_4eC39HqLyjWDarjtT1zdp7dc\n```\n\nAnyone with your binary has your file. So no `.env`, no private keys, no credentials. It might seem\nobvious, but it’s an easy one to forget when you’re embedding a whole config directory.\n\n### What the compiler catches\n\nNow for the good news. Remember `checkEmbed`, that big switch statement? Bad patterns, no matching\nfiles, the wrong type, a variable inside a function; all of them are build failures. But the\ncompiler knows the file exists. It doesn’t know it’s the file you *meant*. That’s where the\nstandard library has a package that can help you out.\n\n### Testing what you embedded\n\n`testing/fstest` is the handy little package of the standard library that doesn’t get enough\nattention, which is a shame, as it works perfectly alongside `embed`. `fstest.TestFS` takes your FS\nand a list of paths you expect to find within it, and then does two jobs at once:\n\n- Asserts every path you named is really there.\n- Cross-checks the file system against itself, walking the whole thing to confirm that `Open`,\n  `ReadDir` and `ReadFile` all agree with each other.\n\nThe trick is what you list. It shouldn’t be a whole inventory of the `FS`, just a handful of the\nfiles your code actually opens:\n\n```\nfunc TestAssetsArePresent(t *testing.T) {\n\t// Extras are ignored, so adding a file needs no test change.\n\terr := fstest.TestFS(static,\n\t\t\"assets/index.css\",\n\t\t\"assets/index.js\",\n\t)\n\tif err != nil {\n\t\tt.Fatalf(\"files are not found: %v\", err)\n\t}\n}\n```\n\nOnly name what you’d notice missing; the template your handler executes, the migration directory,\nthe default config. Everything else is just noise that makes the test brittle.\n\n### Depend on fs.FS\n\nAnd this is the one thing I’d really like you to take away, and the answer to the rebuild problem we\nstarted this section with.\n\n```\n// Take the interface, not the implementation.\nfunc NewServer(assets fs.FS) *Server {\n\treturn &Server{assets: assets}\n}\n\nfunc TestIndexHandlesAnEmptyTemplate(t *testing.T) {\n\tsrv := NewServer(fstest.MapFS{\n\t\t\"templates/index.html\": &fstest.MapFile{Data: []byte(\"\")},\n\t})\n\n\t// No files on disk, no embed, no build.\n\tif err := srv.Render(io.Discard, \"index.html\"); err == nil {\n\t\tt.Fatal(\"expected an error for an empty template\")\n\t}\n}\n```\n\nTake `fs.FS` in your constructors, not `embed.FS`. Your server doesn’t care where the files came\nfrom; it cares that it can open them. Which means a test can hand you an `fstest.MapFS` instead,\nwith the files declared inline as a map.\n\nAnd now you can ask the questions a good unit test should ask. What if this file is empty? What if\nit’s corrupt, or 40 megabytes? You can answer all of that without touching the disk or waiting on a\nbuild. It’s also how you sidestep the rebuild-to-change-a-byte problem in development: the same\nconstructor takes `os.DirFS(\"./assets\")` while you’re working and your `embed.FS` in production, and\nnothing else in your program needs to know which one it got.\n\n---\n\n## Wrapping up\n\nSo that’s the whole journey, from a comment in your source to bytes in the `rodata` section of a\nbinary you can copy anywhere.\n\n`//go:embed` is one of those quiet features about Go that makes it so easy to reason about. It’s\na kind of feature that you didn’t know you needed until it came along. It makes for a great\nexperience when you’re building a package that needs to ship some data with it.\n\nI would really encourage you to have a look at the Go source code, although it can look scary at\nfirst (I spent some time dazed and confused looking at it). But it really makes you a better\nengineer for knowing how these constructs work.\n\nPlease reach out to me at [hello@ainsley.dev](mailto:hello@ainsley.dev)\nif you have any questions!\nI hope you’ve enjoyed reading this post as much as I have writing it.\n\n---\n\n### Source code\n\nA reminder for each section, its program, package and line numbers are below:\n\n| Section | Program | Package | Evidence |\n| --- | --- | --- | --- |\n| Packages | `go` | `go/build` | [`read.go:314`](https://github.com/golang/go/blob/go1.27.1/src/go/build/read.go#L314) (imports-only parse) |\n| Lexer | `go` | `go/build` | [`read.go:379-385`](https://github.com/golang/go/blob/go1.27.1/src/go/build/read.go#L379-L385) (the embed scan) |\n| Patterns | `go` | `cmd/go/internal/load` | [`pkg.go:2165`](https://github.com/golang/go/blob/go1.27.1/src/cmd/go/internal/load/pkg.go#L2165) `resolveEmbed`; JSON written by [`work/gc.go:148-152`](https://github.com/golang/go/blob/go1.27.1/src/cmd/go/internal/work/gc.go#L148-L152) |\n| Parser | `compile` | `cmd/compile/internal/syntax` | [`parser.go`](https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/syntax/parser.go) ; the directive is attached by `noder` |\n| Compiler | `compile` | `cmd/compile/internal/noder` | [`noder.go:462`](https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/noder/noder.go#L462) `checkEmbed`; then `ssagen`, `staticdata`, `gc` |\n| Linker | `link` | `cmd/link/internal/ld` |  |\n| Binary | - | - |  |\n\n## Further reading\n\n**Embed**\n\n- [Draft design: Go command support for embedded static assets](https://go.googlesource.com/proposal/+/master/design/draft-embed.md)\n  , Russ Cox & Brad Fitzpatrick, July 2020\n- [The original proposal (#41191)](https://github.com/golang/go/issues/41191)\n- [The `io/fs` proposal (#41190)](https://github.com/golang/go/issues/41190)\n  , the companion that makes `embed.FS` compose with everything\n- [`embed` package documentation](https://pkg.go.dev/embed)\n- [CL 243942](https://go-review.googlesource.com/c/go/+/243942)\n  , `embed`: implement `FS`\n\n**Go command**\n\n- [CL 243941](https://go-review.googlesource.com/c/go/+/243941)\n  , `go/build`: recognise and report `//go:embed` lines\n- [CL 243945](https://go-review.googlesource.com/c/go/+/243945)\n  , `cmd/go`: add `//go:embed` support\n- [`go/build/read.go#L314`](https://github.com/golang/go/blob/go1.27.1/src/go/build/read.go#L314)\n  , the imports-only parse the `go` command starts with\n\n**Compiler**\n\n- [Go compiler README](https://go.dev/src/cmd/compile/README)\n- [`cmd/compile/internal/syntax/parser.go`](https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/syntax/parser.go)\n  , the compiler’s own parser, with the directive attached by `noder`\n- [CL 243944](https://go-review.googlesource.com/c/go/+/243944)\n  , `cmd/compile`: add `//go:embed` support\n- [`staticdata/embed.go`, where the bytes are written](https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/staticdata/embed.go)\n\n**Linker**\n\n- [Go linker documentation](https://pkg.go.dev/cmd/link)\n- [Go linker source code](https://go.dev/src/cmd/link/)\n\n**Runtime**\n\n- [`src/embed/embed.go`](https://github.com/golang/go/blob/go1.27.1/src/embed/embed.go)\n  , the whole `embed.FS` implementation, and a genuinely short read\n- [`testing/fstest`](https://pkg.go.dev/testing/fstest)\n  , `TestFS` and `MapFS`\n- [Go runtime package documentation](https://pkg.go.dev/runtime)\n- [Go runtime internals](https://go.dev/src/runtime/HACKING)\n\n**Other languages**\n\n- **D**, `import(\"file.txt\")`, an expression, documented since D 1.0 ([spec](https://dlang.org/spec/expression.html)\n  )\n- **Zig**, `@embedFile`, in the docs since 0.1.1 ([ziglang/zig#14637](https://github.com/ziglang/zig/issues/14637)\n  )\n\n**Community**\n\n- [Embed files in Go using the new `embed` package](https://reddit.com/r/golang/comments/kfm4ly/embed_files_in_go_using_new_embed_package_in_go/)\n  , the thread the quote at the top comes from\n- [Go 1.16 release notes on Hacker News](https://news.ycombinator.com/item?id=26158090)\n- [JetBrains, How to use `go:embed` in Go](https://blog.jetbrains.com/go/2021/06/09/how-to-use-go-embed-in-go-1-16/)\n","body_html":"<h1 id=\"how-go-embed-works-from-source-files-to-binary\">How //go:embed Works: From Source Files to Binary</h1>\n<p>By Ainsley Clark (guest post), November 2, 2026</p>\n<blockquote><p>I’m unreasonably excited about this feature. I feel like I always have some big ol’ JSON or\ntemplate or something chilling in a constant making the file looking more unruly than it actually\nis, but don’t want to ship the file with the binary or bring in some sort of 3rd party tool like\npackr into the mix.</p>\n<p><a href=\"https://reddit.com/r/golang/comments/kfm4ly/embed_files_in_go_using_new_embed_package_in_go/gg9eonu/\" rel=\"nofollow ugc noopener\">u/RyanTheKing</a></p></blockquote>\n<p>So let’s have a look into <code>//go:embed</code>, to see how to use it, but also see how it works under the\nhood; so you’re able to make more informed decisions when shipping static assets alongside your\nprograms.</p>\n<h2 id=\"contents\">Contents</h2>\n<ul><li><a href=\"#the-directive-what-it-is\">The directive: What it is</a></li><li><a href=\"#the-variable-how-to-use-it\">The variable: How to use it</a></li><li><a href=\"#the-binary-how-its-built\">The binary: How it’s built</a></li><li><a href=\"#the-runtime-how-its-read\">The runtime: How it’s read</a></li><li><a href=\"#the-tradeoffs-what-you-take-on\">The tradeoffs: What you take on</a></li></ul>\n<hr />\n<h2 id=\"the-directive-what-it-is\">The directive: What it is</h2>\n<p>So how do we use it? Here’s a simple example to whet your appetite:</p>\n<pre><code>//go:embed version.txt\nvar version string</code></pre>\n<ul><li><p>We have what looks like a go comment, but it’s actually a Go directive, sometimes called</p><p>pragmas (if you’re working with the compiler). You may have seen these before as <code>go:generate</code> or\n<code>go:build</code>.</p></li><li>After writing <code>//go:embed</code> we specify the relative file path to where the file is located.</li><li><p>In the next line, we specify the variable name we want to use. Which is where the go compiler</p><p>will read the file contents and bake all of that lovely data into the binary before your\nprogram runs.</p></li><li>The variable is just a pointer to the file contents; the magic happens in the build.</li></ul>\n<p>Before we get into any of that, it’s worth remembering the problem this was built to solve.</p>\n<h3 id=\"we-ve-all-seen-this\">We’ve all seen this?</h3>\n<p>I’m sure we’ve all seen something like this before:</p>\n<pre><code>$ docker run myapp\n2026/09/09 open ./static/app.css: no such file or directory</code></pre>\n<p>How annoying is this to debug? It’s usually not difficult or cumbersome, but fiddly and\ntime-consuming. You usually have to debug some weird absolute/relative path fiasco or go into some\nglob patterns. This is exactly why an embed feature was needed, it makes static assets incredibly\neasy to ship.</p>\n<h3 id=\"what-it-is-not\">What it is not</h3>\n<p>We’ve talked about what <code>//go:embed</code> is, but let’s just touch on what it isn’t for a moment.</p>\n<ul><li><p>Don’t think that it’s a way to compress your files; a megabyte is a megabyte. Go doesn’t care or</p><p>manipulate your data in any way.</p></li><li><p>It’s also not a build pipeline, as mentioned above. Go doesn’t minify, transpile or fingerprint</p><p>anything; it just copies bytes.</p></li><li><p>It’s also not dynamic, it’s run at compile time, not run time. The bytes are locked in when you</p><p>run <code>go build</code>. So if you tweak a template and expect it to update, it won’t. There’s no hot\nreload anywhere.</p></li><li><p>And it’s not a media server, please don’t be going embedding your favourite Netflix films.</p><p>Coincidentally, there’s actually a 2GB limit (I tried, believe me). But seriously, use object\nstorage or something else for storing large files.</p></li></ul>\n<hr />\n<h2 id=\"the-variable-how-to-use-it\">The variable: How to use it</h2>\n<p>So now we’ve seen what it is, let’s remind ourselves how to use it on a high level. If you’re\nfamiliar with the concepts of how to use it, feel free to skip\nthis <a href=\"#the-binary-how-its-built\">section</a>\n.</p>\n<p>There are three data types we can use with <code>//go:embed</code>; a string, a byte slice and a read-only\nfile system. Here are all three of them in one program:</p>\n<pre><code>import &quot;embed&quot; // Or import _ &quot;embed&quot;\n\n//go:embed version.txt\nvar version string\n\n//go:embed schema.sql\nvar schema []byte\n\n//go:embed assets/*\nvar assets embed.FS\n\nfunc main() {\n    fmt.Println(version) // v1.4.2\n    db.Exec(string(schema))\n\n    css, _ := assets.ReadFile(&quot;assets/index.css&quot;)\n    fmt.Println(string(css)) // body { margin: 0 }\n}</code></pre>\n<p>We first need to import the <code>embed</code> package. The import isn’t blank here because we’re naming\n<code>embed.FS</code> below, so we need the package itself. A blank import (<code>import _ &quot;embed&quot;</code>) is for when\nyou’re only embedding into strings and byte slices. Either way, it sends a signal to the compiler\nthat we need to embed data, and you’ll see exactly how that works later on.</p>\n<p>Then it’s one directive per variable, one type each:</p>\n<ul><li><p><strong>A string</strong>, our <code>version.txt</code> from the last section. Good for anything you’re going to read as</p><p>text; a version number, a template, a licence.</p></li><li><p><strong>A byte slice</strong>, here an SQL schema. But we could really use it with anything, a config file,</p><p>TLS cert, font, image, and much more. Use bytes when it makes sense for how the data is used in\nyour program.</p></li><li><p><strong>An <code>embed.FS</code></strong>, a whole folder. This is the part that sets Go apart from most languages, and</p><p>it’s great for web assets, templates, migrations and whatever else you fancy.</p></li></ul>\n<p>And then we just use them. They’re variables. No <code>os.Open</code>, no path fiddling, no “did I ship the\nmigrations folder?”. The contents are already there, just like any other variable in your program.\nNote that a file inside an <code>FS</code> keeps the path it was embedded with, which is why we’re asking for\n<code>assets/index.css</code> rather than just <code>index.css</code>.</p>\n<h3 id=\"embed-fs\">embed.FS</h3>\n<p>The <code>FS</code> type has a bit more going on with it, so it’s worth a proper look.\nYou can see the methods below: <code>Open</code>, <code>ReadDir</code> and <code>ReadFile</code>.</p>\n<pre><code>// An FS is a read-only collection of files.\ntype FS struct {}\n\nfunc (f FS) Open(name string) (fs.File, error) // Satisfies fs.FS\nfunc (f FS) ReadDir(name string) ([]fs.DirEntry, error)\nfunc (f FS) ReadFile(name string) ([]byte, error)</code></pre>\n<p>The most important thing to note is that it satisfies the <code>fs.FS</code> interface, which means we can use\nit in many different ways. It makes it easy to plug and play across packages, such as\n<code>http.FileServer</code> to serve it as a static site or <code>template.ParseFS</code> to parse HTML templates.</p>\n<pre><code>// An FS provides access to a hierarchical file system.\ntype FS interface {\n    Open(name string) (File, error)\n}</code></pre>\n<h3 id=\"working-example\">Working example</h3>\n<p>Before we dive any deeper, let’s give ourselves a folder to work with. This is the example we’ll\nbe coming back to all the way down to the linker, so it’s worth a proper look.</p>\n<p>We’re serving a normal website. An <code>index.html</code> at the root, and some <code>css</code> and <code>js</code> in a folder\ncalled <code>assets</code>. No more, no less.</p>\n<pre><code>.\n├── main.go\n├── index.html (&lt;h1&gt;Hello&lt;/h1&gt;)\n└── assets\n    ├── index.css\n    └── index.js</code></pre>\n<p>To embed that into the program, we create a string variable for the contents of <code>index.html</code>, and an\n<code>embed.FS</code> for the contents of the <code>assets</code> folder, and then just print them. In a production\nenvironment you’d serve these through a handler, but we’ve kept it simple for now.</p>\n<pre><code>package main\n\nimport (\n    &quot;embed&quot;\n    &quot;fmt&quot;\n)\n\n//go:embed index.html\nvar indexHTML string\n\n//go:embed assets/*\nvar static embed.FS\n\nfunc main() {\n    fmt.Println(indexHTML) // &lt;h1&gt;Hello&lt;/h1&gt;\n    css, _ := static.ReadFile(&quot;assets/index.css&quot;)\n    fmt.Println(string(css)) // body { background: red; }\n}</code></pre>\n<p>The <code>assets/*</code> pattern gets us every file in that folder; naming the directory on its own\n(<code>//go:embed assets</code>) takes the whole tree instead. The difference isn’t only depth: naming the\ndirectory skips every file beginning with <code>.</code> or <code>_</code> anywhere beneath it, where the <code>/*</code> glob still\npulls those in at the top level. Write <code>all:assets</code> when you want the whole tree, dotfiles and all.\nThere are more gotchas in the <a href=\"https://pkg.go.dev/embed\" rel=\"nofollow ugc noopener\">pkg.go.dev/embed</a>\ndocs.</p>\n<hr />\n<h2 id=\"the-binary-how-it-s-built\">The binary: How it’s built</h2>\n<p>Now that we know what <code>//go:embed</code> is, we’ve seen how it works. Let’s dive a little bit deeper to\nsee how it’s constructed under the hood. If I were to show you a bunch of code from the Go\ncompiler out of context in the next section, I’ll probably have you lost; like it did me for a few\ndays researching into how Go is built (TLDR; it’s challenging but worth it).</p>\n<p>Everything below was read against <strong>Go 1.27.1</strong>, and every file and line number links to that tag\non GitHub, so the lines quoted here stay put even after the toolchain moves on.</p>\n<h3 id=\"compiler-basics\">Compiler basics</h3>\n<p>So before we go anywhere near how go is built, let’s zoom all the way out. When you type <code>go build</code>,\nsix steps run in order and out the other end comes a binary. This is the path that matters for\n<code>//go:embed</code>; it isn’t everything the toolchain does, just the part your files travel through.</p>\n<p>I’m aware that there’s a whole heap of stuff that we’re not going into here such as SSA,\ninlining, escape analysis, etc… But none of it really touches the embed packages, because your\ndata never becomes instructions; they are just bytes after all.</p>\n<p>The first thing worth knowing is that there isn’t one program doing all of this. There are several,\neach responsible for its own thing, and <code>go build</code> is the one that runs the other two.</p>\n<figure><img src=\"https://internals-for-interns.com/images/posts/go-embed-1-overview.svg\" alt=\"Overview\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<p><em>go build: six steps, three programs</em></p>\n<p>So what are we looking at here?</p>\n<ol><li><p><strong>Packages</strong>: The <code>go</code> command starts by reading your <code>.go</code> files and working out what package</p><p> each one is in.</p></li><li><p><strong>Lexer</strong>: The lexer chops that text up into tokens, and while it’s in there it reads the</p><p> comments looking for pragmas, which is where your <code>//go:embed</code> lines get spotted.</p></li><li><p><strong>Patterns</strong>: Turns each <code>//go:embed</code> pattern into a list of real files on the disk and hands that</p><p> list to the compiler.</p></li><li><p><strong>Parser</strong>: Will then arrange those tokens into a syntax tree (<code>AST</code>) that describes the structure</p><p> of your code.</p></li><li><p><strong>Compiler</strong>: Then checks the tree and turns it into machine code. What comes out is one object</p><p> archive per package, which is code that can’t run on its own yet.</p></li><li><p><strong>Linker</strong>: Is what ties everything together, along with the Go runtime, into the binary you</p><p> build.</p></li></ol>\n<p>Notice the three different sections, that’s the bit that tripped me up for the longest, <code>go</code>\nruns once for the whole build, <code>compile</code> runs once <em>per package</em>, and <code>link</code> runs once at the\nend. It’s an important nuance to understand.</p>\n<p>Check out <a href=\"https://go.dev/src/cmd/compile/README\" rel=\"nofollow ugc noopener\">go.dev/src/cmd/compile/README</a>\nfor more information.</p>\n<h3 id=\"packages-go-build\">Packages (<code>go build</code>)</h3>\n<p>So now, onto the juicy bits. Let’s start with how Go looks at your project. When you run <code>go build</code> it needs to know what files and packages exist, so it knows what to parse and build.</p>\n<p>A package directory goes in, and a <code>*build.Package</code> comes out. So it walks your project, finds every\n<code>.go</code> file and then works out which package each one belongs to. For every file, it notes down where\nit lives, what it imports, and any directives (such as <code>//go:embed</code>) that it carries.</p>\n<figure><img src=\"https://internals-for-interns.com/images/posts/go-embed-2-packages.svg\" alt=\"Packages\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<p><em>Packages: walking the package directory</em></p>\n<p>You can see our <code>assets/</code> folder and <code>index.html</code> being skipped, because they aren’t Go files and\nthis pass only cares about Go. <code>main.go</code> makes it through the condition into <code>matchFile</code>, and\nout the other side comes a <code>Package</code> which details its name, its Go files, and the position of\nevery <code>//go:embed</code> pattern in it.</p>\n<pre><code>func (ctxt *Context) Import(path string, srcDir string, mode ImportMode) (*Package, error) {\n    for _, d := range ctxt.readDir(p.Dir) {          // walk the package dir\n        name := d.Name()\n        if filepath.Ext(name) != &quot;.go&quot; {             // main.go, index.html, assets/…\n            continue\n        }\n        info, _ := ctxt.matchFile(p.Dir, name, ...)  // reads header, scans comments, gets embed\n        p.GoFiles = append(p.GoFiles, name)             // [&quot;main.go&quot;]\n        p.Name = info.parsed.Name.Name               // main\n    \n        for _, emb := range info.embeds {\n            // {&quot;index.html&quot;: [main.go:10], &quot;assets/*&quot;: [main.go:13]}\n            embedPos[emb.pattern] = append(embedPos[emb.pattern], emb.pos)\n        }\n    }\n}</code></pre>\n<p><strong>Reference</strong>: <a href=\"https://github.com/golang/go/blob/go1.27.1/src/go/build/build.go\" rel=\"nofollow ugc noopener\"><code>src/go/build/build.go</code></a>\n(<code>(*Context).Import</code>, simplified)</p>\n<p>Our <code>//go:embed index.html</code> and <code>//go:embed assets/*</code> have been spotted and recorded along with\ntheir file names and token positions.</p>\n<p>But how did it spot the comment originally? This is where the lexer comes into play.</p>\n<h3 id=\"lexer-go-build\">Lexer (<code>go build</code>)</h3>\n<p>The lexer (or scanner, or tokeniser, whatever you fancy) is the first thing that actually reads your\ncode as <em>Go</em>, rather than as a blob of bytes. It scans the file one character at a time and chops it\nup into little tokens, which are the pieces of code that mean something on their own. Such as\n<code>func</code>, <code>var</code>, <code>=</code>, a string literal, or a comment.</p>\n<p>This is the stage that makes <code>//go:embed</code> actually possible. In Go, a comment is a real token\n(<code>token.COMMENT</code>).</p>\n<figure><img src=\"https://internals-for-interns.com/images/posts/go-embed-3-lexer.svg\" alt=\"Lexer\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<p><em>Lexer: one character at a time, into tokens</em></p>\n<p>Characters go in and tokens come out. The whole <code>//go:embed index.html</code> line becomes a single\n<code>COMMENT</code> token, and the two words of <code>var indexHTML string</code> become a <code>VAR</code> and two <code>IDENT</code>s.</p>\n<p>The <code>go</code> command’s scan is deliberately inexpensive as it stops at the end of the import block,\nbecause that’s normally all it needs. Unless, however it saw <code>import &quot;embed&quot;</code> on the way past,\nin which case it reads on to the end of the file, picking out every\ncomment starting <code>//go:embed</code>:</p>\n<pre><code>if hasEmbed {\n    r.readRest() // keep going: read the rest of the file after all\n    sc.Init(file, r.buf, nil, scanner.ScanComments) // get comments as tokens\n    \n    for {\n        pos, tok, lit := sc.Scan()\n        if tok == token.COMMENT &amp;&amp; strings.HasPrefix(lit, &quot;//go:embed&quot;) {\n            // in:  `//go:embed index.html`\n            // out: {pattern: &quot;index.html&quot;, pos: ...}\n            embs, _ := parseGoEmbed(fset, pos, lit)\n            info.embeds = append(info.embeds, embs...)\n        }\n    }\n}</code></pre>\n<p><strong>Reference</strong>: <a href=\"https://github.com/golang/go/blob/go1.27.1/src/go/build/read.go#L374-L392\" rel=\"nofollow ugc noopener\"><code>src/go/build/read.go#L374-L392</code></a>\n(<code>readGoInfo</code>, simplified)</p>\n<p>That <code>hasEmbed</code> flag is the real reason <code>import _ &quot;embed&quot;</code> is mandatory even when you never type the\npackage name. If you don’t import the package, we’ll never go into this code block.</p>\n<p>What comes out is a list of the patterns it found, and where each one was written:</p>\n<pre><code>[]fileEmbed{\n    {pattern: &quot;index.html&quot;, pos: main.go:10:12},\n    {pattern: &quot;assets/*&quot;,   pos: main.go:13:12},\n}</code></pre>\n<p>We now have patterns to file names and line numbers, but there are no files? This is where resolving\nembed patterns comes in.</p>\n<h3 id=\"patterns-go-build\">Patterns (<code>go build</code>)</h3>\n<p>Within the <code>go command</code> we have a fairly important function called <code>resolveEmbed</code> which resolves\npatterns into actual files and trees. File patterns go in, and real file paths come out.</p>\n<figure><img src=\"https://internals-for-interns.com/images/posts/go-embed-4-patterns.svg\" alt=\"Patterns\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<p><em>Patterns: resolveEmbed turns patterns into files</em></p>\n<p>The glob is where it gets interesting. Our <code>index.html</code> was only ever going to match itself, but\n<code>assets/*</code> fans out to <code>assets/index.css</code> and <code>assets/index.js</code>, neither of which we named anywhere.\nThat’s the first time anything in this whole process has actually gone and looked at your disk.</p>\n<p>So these patterns get expanded, globbing it against the disk and walking any directory it\nmatches, into a list of actual file names. You can see this in action below:</p>\n<pre><code>func resolveEmbed(pkgdir string, patterns []string) (files []string, pmap map[string][]string, err error) {\n    pmap = make(map[string][]string)\n    have := make(map[string]bool) // every file, once\n\n    // patterns = []string{&quot;index.html&quot;, &quot;assets/*&quot;}\n    for _, pattern := range patterns {\n        matches, _ := fsys.Glob(pkgdir + &quot;/&quot; + pattern)\n\n        var list []string\n        for _, match := range matches {\n            if fsys.IsDir(match) {\n                fsys.WalkDir(match, func(path string, ...) { list = append(list, path) })\n            } else {\n                list = append(list, match)\n            }\n        }\n\n        pmap[pattern] = list // what this pattern matched\n        for _, f := range list {\n            have[f] = true   // ...and the running set of all of them\n        }\n    }\n\n    for f := range have {\n        files = append(files, f)\n    }\n\n    return files, pmap, nil\n}</code></pre>\n<p><strong>Reference</strong>: <a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/go/internal/load/pkg.go#L2165\" rel=\"nofollow ugc noopener\"><code>src/cmd/go/internal/load/pkg.go#L2165</code></a>\n(<code>resolveEmbed</code>, simplified)</p>\n<p>Output will now be:</p>\n<pre><code>// pmap:\nmap[string][]string{\n     &quot;assets/*&quot;:   {&quot;assets/index.css&quot;, &quot;assets/index.js&quot;},\n     &quot;index.html&quot;: {&quot;index.html&quot;},\n}\n\n// files:\n[]string{&quot;assets/index.css&quot;, &quot;assets/index.js&quot;, &quot;index.html&quot;}</code></pre>\n<p>Those two return values become the two data points that the compiler needs:</p>\n<ul><li><p><code>Patterns</code> answers “what did this pattern match?” and keeps the duplicates, because that’s the tree</p><p>your <code>embed.FS</code> gets, and two different patterns can easily match the same file.</p></li><li><p><code>Files</code> answers “where do I read those bytes?” and cannot have duplicates, because the compiler</p><p>should open each file exactly once.</p></li></ul>\n<p>The <code>go</code> command marshals them into JSON, writes it to a file called <code>embedcfg</code> in the build’s\ntemporary work directory, and passes that path to the compiler as <code>-embedcfg</code>, once per package.</p>\n<p>Why a file, why not just hand it over directly? Because <code>go build</code> and the compiler are two separate\nprocesses, as we saw in that first diagram, so it gets written down instead.</p>\n<p>For our example project, the generated <code>embedcfg</code> looks like:</p>\n<pre><code>{\n    &quot;Patterns&quot;: {\n        &quot;assets/*&quot;: [\n            &quot;assets/index.css&quot;,\n            &quot;assets/index.js&quot;\n        ],\n        &quot;index.html&quot;: [\n            &quot;index.html&quot;\n        ]\n    },\n    &quot;Files&quot;: {\n        &quot;assets/index.css&quot;: &quot;/home/user/project/assets/index.css&quot;,\n        &quot;assets/index.js&quot;: &quot;/home/user/project/assets/index.js&quot;,\n        &quot;index.html&quot;: &quot;/home/user/project/index.html&quot;\n    }\n}</code></pre>\n<p><strong>Reference</strong>: <a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/go/internal/work/exec.go#L893-L906\" rel=\"nofollow ugc noopener\"><code>work/exec.go#L893-L906</code></a>\nbuilds and marshals it, <a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/go/internal/work/gc.go#L148-L152\" rel=\"nofollow ugc noopener\"><code>work/gc.go#L148-L152</code></a>\nwrites it and passes <code>-embedcfg</code> (simplified)</p>\n<p>(Tip: <code>go list -json=EmbedPatterns,EmbedFiles .</code> surfaces these exact matched patterns and files\nstraight from the package metadata, any time you want to look.)</p>\n<h3 id=\"parser-cmd-compile\">Parser (<code>cmd/compile</code>)</h3>\n<p>We’re in a different program now. Tokens go in, along with the path to that <code>embedcfg</code>, and what\ncomes out is a tree with your directive attached to the right node.</p>\n<p>The parser is where the real magic happens in the Go compiler. It takes those tokens and little\nbits of Go code and works out their structure. A bit like breaking a sentence down into a\nsubject, verb and object.</p>\n<p>The result is a <em>syntax</em> tree; you may have heard of the term <code>AST</code> before, which is short for\n<code>abstract syntax tree</code>. It’s the building blocks of our program. Every piece of your code (a\nfunction, a variable, an if statement) becomes a <em>node</em> within that tree.</p>\n<p>Directives such as <code>//go:embed</code> get attached to the node, which is how Go knows which variable to\nput your embedded file in.</p>\n<p>The below example is captured from the two lines from our example above:</p>\n<pre><code>//go:embed index.html\nvar indexHTML string</code></pre>\n<figure><img src=\"https://internals-for-interns.com/images/posts/go-embed-5-parser.svg\" alt=\"Parser\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<p><em>Parser: the directive and the variable are one node</em></p>\n<ul><li><p><strong><code>GenDecl</code></strong>: Is the declaration as a whole, it’s short for a <code>generic declaration node</code></p><p>which represents an import, constant, type or variable declaration. In our example, it’s<br />\nboth the comment, and the variable.</p></li><li><p><strong><code>Doc</code></strong>: Is the comment, held as a <code>*ast.CommentGroup</code>. Our <code>//go:embed index.html</code> is in</p><p>there, kept word for word in <code>Text</code>.</p></li><li><p><strong><code>Specs</code></strong>: Is what that declaration actually declares which is an <code>*ast.ValueSpec</code> holding the</p><p>name <code>indexHTML</code> and the type <code>string</code>, our variable.</p></li></ul>\n<p>Both the <code>Doc</code> and <code>Specs</code> come under <code>GenDecl</code>. The comment and the variable aren’t two things that\nhappen to be near each other in a file; they’re two branches of one node. That’s how the compiler\nknows the contents of <code>index.html</code> go into <code>indexHTML</code>, and not into whatever is declared next.</p>\n<p>Which looks like this. The dump is <code>go/ast</code>, which is what <code>ast.Print</code> gives you and what most\ntooling reads. The compiler’s own parser is <code>cmd/compile/internal/syntax</code> and holds the same shape\nunder different names, which is why <code>checkEmbed</code> in the next section takes a <code>*syntax.VarDecl</code>:</p>\n<pre><code>1: *ast.GenDecl {\n.  Doc: *ast.CommentGroup {\n.  .  List: []*ast.Comment (len = 1) {\n.  .  .  0: *ast.Comment {\n.  .  .  .  Slash: main.go:8:1\n.  .  .  .  Text: &quot;//go:embed index.html&quot;\n.  .  .  }\n.  .  }\n.  }\n.  TokPos: main.go:9:1\n.  Tok: var\n.  Specs: []ast.Spec (len = 1) {\n.  .  0: *ast.ValueSpec {\n.  .  .  Names: []*ast.Ident (len = 1) {\n.  .  .  .  0: *ast.Ident {\n.  .  .  .  .  NamePos: main.go:9:5\n.  .  .  .  .  Name: &quot;indexHTML&quot;\n.  .  .  .  }\n.  .  .  }\n.  .  .  Type: *ast.Ident {\n.  .  .  .  NamePos: main.go:9:15\n.  .  .  .  Name: &quot;string&quot;\n.  .  .  }\n.  .  }\n.  }\n}</code></pre>\n<p>Clever stuff, right? This was the aha moment for me. The comment and variable are one declaration\nin Go’s eyes.</p>\n<h3 id=\"compiler-cmd-compile\">Compiler (<code>cmd/compile</code>)</h3>\n<p>Now onto the nuts and bolts, the compiler. A tree goes in, and what comes out is an <em>object archive</em>,\none per package, which is your code compiled but not yet runnable on its own. This is also the stage\nwhere your data is actually allocated.</p>\n<p>Everything so far has been bookkeeping; finding files, expanding patterns and writing lists, but not\none byte of your <code>index.html</code> has actually been allocated into your program. However, in this step,\nit does.</p>\n<p>The compiler lays your variable out in memory and fills it with the file’s contents, as static data,\nthat’s there before your program runs a single line of your app’s code.</p>\n<p>Although its first job isn’t your files at all, it’s the rules. Remember, the <code>go</code> command spotted\nyour directive and wrote the pattern down, but it never checked anything about it, which is\nmentioned in the comments:</p>\n<pre><code>// The compiler will enforce the mapping of comments to\n// declared variables. We just need to know the patterns.</code></pre>\n<p><strong>Reference</strong>: <a href=\"https://github.com/golang/go/blob/go1.27.1/src/go/build/read.go#L369-L373\" rel=\"nofollow ugc noopener\"><code>src/go/build/read.go#L369-L373</code></a>\n(<code>readGoInfo</code>)</p>\n<p>Now it checks what you’ve written is actually valid. Nearly every <code>//go:embed</code> error message you’ve\nprobably seen comes from this switch statement:</p>\n<pre><code>func checkEmbed(decl *syntax.VarDecl, haveEmbed, withinFunc bool) error {\n    switch {\n    case !haveEmbed: // The file never imported &quot;embed&quot;.\n        return errors.New(`go:embed only allowed in Go files that import &quot;embed&quot;`)\n    case len(decl.NameList) &gt; 1: // var a, b string\n        return errors.New(&quot;go:embed cannot apply to multiple vars&quot;)\n    case decl.Values != nil: // var s string = &quot;hello&quot;\n        return errors.New(&quot;go:embed cannot apply to var with initializer&quot;)\n    case withinFunc: // Declared inside a func body.\n        return errors.New(&quot;go:embed cannot apply to var inside func&quot;)\n    }\n    return nil\n}</code></pre>\n<p><strong>Reference</strong>: <a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/noder/noder.go#L462-L481\" rel=\"nofollow ugc noopener\"><code>src/cmd/compile/internal/noder/noder.go#L462-L481</code></a>\n(<code>checkEmbed</code>, simplified)</p>\n<p>But how is the data read?</p>\n<figure><img src=\"https://internals-for-interns.com/images/posts/go-embed-6-compiler.svg\" alt=\"Compiler\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<p><em>Compiler: WriteEmbed lays <code>&lt;h1&gt;Hello&lt;/h1&gt;</code> out as 14 bytes of read-only data</em></p>\n<pre><code>// WriteEmbed, for our `var indexHTML string`.\ncase embedString, embedBytes:\n    file := files[0]                        // &quot;index.html&quot;, from the embedcfg JSON\n    path := base.Flag.Cfg.Embed.Files[file] // &quot;/home/user/project/index.html&quot;\n    fsym, size, _ := fileStringSym(v.Pos(), path, ...) // read it, name the bytes\n\n    sym, off := v.Linksym(), 0                 // indexHTML itself\n    off = objw.SymPtr(sym, off, fsym, 0)       // field 1: pointer to those bytes\n    off = objw.Uintptr(sym, off, uint64(size)) // field 2: length\n    if kind == embedBytes {\n        objw.Uintptr(sym, off, uint64(size))   // field 3: cap, because a slice has one\n    }\ncase embed.FS:\n    // See source files below...</code></pre>\n<p><strong>Reference</strong>: <a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/staticdata/embed.go#L101-L134\" rel=\"nofollow ugc noopener\"><code>src/cmd/compile/internal/staticdata/embed.go#L101-L134</code></a>\n(<code>WriteEmbed</code>, simplified)</p>\n<p>Here we can see <code>WriteEmbed</code> switching on the variable’s data type. It then goes on to call a\nfunction called <code>fileStringSym</code>, which opens your file and returns a symbol for its contents, as\nwell as the size.</p>\n<p>Okay, but what’s a symbol? Forget <code>[]byte</code> for a second. A symbol is a box with a name on it, what\nit’s called, how big it is, and where it lives in the binary. That’s what the linker actually needs\nto do its job, and it’s why <code>fileStringSym</code> hands one back rather than the bytes themselves.\nThis is where your asset has stopped being a path and has actually become data.</p>\n<p>The rest is ordinary compilation. The tree gets turned into machine code\n(<code>cmd/compile/internal/ssagen</code>), and out comes one <em>object archive</em> per package, which is code that\ncan’t run yet, which is where the linker comes into play.</p>\n<h3 id=\"linker-cmd-link\">Linker (<code>cmd/link</code>)</h3>\n<p>Although the linker has little to do with <code>//go:embed</code>, it plays a crucial part in the\nbuild process. It’s a separate program, located under <code>cmd/link</code>. Many <code>.a</code> files go in, and one\nexecutable comes out. All of the object archives that we mentioned above, now are joined together.\nIt fills in all the gaps so every piece can find the others.</p>\n<p>Which is where the Go runtime is injected. The runtime is built-in code that manages memory,\ngoroutines and all of the stuff that makes Go, Go.</p>\n<figure><img src=\"https://internals-for-interns.com/images/posts/go-embed-7-linker.svg\" alt=\"Linker\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<p><em>Linker: object archives and the runtime become one binary</em></p>\n<p>There’s <code>main.a</code> still carrying our 14 bytes, along with <code>fmt.a</code>, <code>embed.a</code>, every other package you\npulled in, and <code>runtime.a</code>. On the right is what they become, one binary, and our <code>&lt;h1&gt;Hello&lt;/h1&gt;</code>\nsitting in the <code>rodata</code> section, which is where read-only data lives.</p>\n<h3 id=\"binary\">Binary</h3>\n<p>Now run it (<code>./myapp</code>) and voilà! We have your finished program; maybe we should take a\nbreather…</p>\n<h3 id=\"build-summary\">Build Summary</h3>\n<p>I know that was a lot to take in, so let’s go back to where we started and walk it once more, now\nthat all the names mean something. I always find this easier to read as pseudocode, so here we go.\nIt isn’t real or runnable; it just connects all the dots:</p>\n<pre><code>import (\n    &quot;go/build&quot;                            // 1. Packages: what&#39;s in this package?\n                                        // 2. Lexer:    text -&gt; tokens\n    &quot;cmd/go/internal/load&quot;                // 3. Patterns: &quot;assets/*&quot; -&gt; real paths on disk\n    &quot;cmd/compile/internal/syntax&quot;         // 4. Parser:   tokens -&gt; syntax tree\n    &quot;cmd/compile/internal/staticdata&quot;     // 5. Compiler: file bytes -&gt; read-only data\n    &quot;cmd/link/internal/ld&quot;                // 6. Linker:   object files -&gt; the binary\n)\n\nfunc goBuild(dir string) Binary {\n    pkg := build.ImportDir(dir) // files, imports, embed patterns\n    \n    var objs []Object\n    for _, p := range pkg.Deps {\n        embeds := load.ResolveEmbed(p.Dir, p.EmbedPatterns) // &quot;assets/*&quot; -&gt; [assets/index.css, ...]\n        tree := syntax.Parse(p.GoFiles)                     // code + directives -&gt; tree\n    \n        for _, v := range tree.EmbedVars {\n            data := os.ReadFile(embeds[v.Pattern]) // the compiler opens your file\n            staticdata.WriteEmbed(v, data)         // and bakes the bytes in\n        }\n        objs = append(objs, compile(tree)) // tree -&gt; object file\n    }\n    \n    return ld.Link(objs, runtime) // -&gt; the binary you ship\n}</code></pre>\n<p>Three separate processes, and they don’t run the same number of times, <code>go</code> runs once for the whole\nbuild, <code>compile</code> runs <em>once per package</em> and <code>link</code> runs once at the end. That’s why <code>embedcfg</code> is\nwritten per package, immediately before each <code>compile</code> invocation.</p>\n<p>And you don’t have to take my word for any of it. <code>go build -x</code> prints the real command lines and the\ntemporary directory, so you can watch <code>embedcfg</code> being written and passed along, and\n<code>ls $(go env GOROOT)/pkg/tool/$(go env GOOS)_$(go env GOARCH)/</code> shows you that <code>compile</code> and <code>link</code>\nreally are separate binaries sitting on your disk. Every <strong>Reference</strong> link above points at the exact\nlines in Go 1.27.1 if you’d like to read the real thing.</p>\n<hr />\n<h2 id=\"the-runtime-how-it-s-read\">The runtime: How it’s read</h2>\n<p>So the bytes are in the binary. The last question is what happens when your program actually\nopens them, because that depends on which of the three types you picked.</p>\n<p>For a <code>string</code> or a <code>[]byte</code>, there’s almost nothing to tell, and that’s rather the point. The\ncompiler wrote a pointer and a length, and the pointer aims at bytes sitting in the <code>rodata</code> section\nwe just watched the linker build. Reading the variable is an ordinary variable read.</p>\n<p>An <code>embed.FS</code> is more involved, and it’s the more interesting half. Remember it’s a single pointer to\na hidden list, and here’s what’s on the end of it:</p>\n<pre><code>// An FS is a read-only collection of files.\ntype FS struct {\n    files *[]file\n}\n\n// A file is a single file in the FS.\ntype file struct {\n    name string\n    data string\n    hash [16]byte // truncated SHA256 hash\n}</code></pre>\n<p><strong>Reference</strong>: <a href=\"https://github.com/golang/go/blob/go1.27.1/src/embed/embed.go#L151-L212\" rel=\"nofollow ugc noopener\"><code>src/embed/embed.go#L151-L212</code></a>\n(<code>FS</code> and <code>file</code>, simplified)</p>\n<p>Each file’s contents are a <code>string</code>, pointing into the same read-only data our <code>indexHTML</code> did,\nso a 40MB asset isn’t sitting in your heap waiting for you.</p>\n<p>Asking for a file is a search, not a syscall. The list is sorted, so\n<a href=\"https://github.com/golang/go/blob/go1.27.1/src/embed/embed.go#L243\" rel=\"nofollow ugc noopener\"><code>lookup</code></a>\ndoes a binary search\nover it, and <a href=\"https://github.com/golang/go/blob/go1.27.1/src/embed/embed.go#L272\" rel=\"nofollow ugc noopener\"><code>readDir</code></a>\ndoes two\nof them to find where a directory starts and ends, then hands back that stretch of the slice. There’s\nno disk involved at any point, which is why <code>ModTime</code> on an embedded file is the zero time. There’s\nnothing there to have been modified.</p>\n<p>There’s one detail worth the whole section, though, and it’s the difference between the two ways of\ngetting at your bytes. <code>Open</code> hands you back an <code>openFile</code> that reads straight out of that string,\ncopying only as much as fits the buffer you gave it. <code>ReadFile</code> ends looking a bit like this:</p>\n<pre><code>return []byte(ofile.f.data), nil</code></pre>\n<p><strong>Reference</strong>: <a href=\"https://github.com/golang/go/blob/go1.27.1/src/embed/embed.go#L322-L332\" rel=\"nofollow ugc noopener\"><code>src/embed/embed.go#L322-L332</code></a>\n(<code>ReadFile</code>)</p>\n<p>That conversion is a copy, and a fresh one on every call. So the 40MB asset that wasn’t sitting in\nyour heap a moment ago lands there the moment you call <code>ReadFile</code> on it. <code>Open</code> doesn’t; it fills\nyour buffer a chunk at a time, which is the path <code>http.FileServer</code> and <code>io.Copy</code> take. Neither\ntouches the disk, but only one of them allocates the file.</p>\n<hr />\n<h2 id=\"the-tradeoffs-what-you-take-on\">The tradeoffs: What you take on</h2>\n<p>You’ve seen how it works and how it’s used, so let’s talk about what it costs you, because embedding\nisn’t free.</p>\n<h3 id=\"rebuild-to-change-a-byte\">Rebuild to change a byte</h3>\n<p>Remember what <code>WriteEmbed</code> did with those bytes. They’re read-only data in the object file now, which\nmeans your file isn’t really a file any more. So change one line of CSS, and you have to rebuild.</p>\n<p>This can be a bit painful because nobody wants a full build on every save. The fix is the last\nin this section, so hold onto that.</p>\n<h3 id=\"no-secrets\">No secrets</h3>\n<p>And here’s the one that catches people out. Embedded bytes are just data in the binary, which means\nthey’re readable:</p>\n<pre><code>$ strings myapp | grep -i api_key\nAPI_KEY=sk_live_4eC39HqLyjWDarjtT1zdp7dc</code></pre>\n<p>Anyone with your binary has your file. So no <code>.env</code>, no private keys, no credentials. It might seem\nobvious, but it’s an easy one to forget when you’re embedding a whole config directory.</p>\n<h3 id=\"what-the-compiler-catches\">What the compiler catches</h3>\n<p>Now for the good news. Remember <code>checkEmbed</code>, that big switch statement? Bad patterns, no matching\nfiles, the wrong type, a variable inside a function; all of them are build failures. But the\ncompiler knows the file exists. It doesn’t know it’s the file you <em>meant</em>. That’s where the\nstandard library has a package that can help you out.</p>\n<h3 id=\"testing-what-you-embedded\">Testing what you embedded</h3>\n<p><code>testing/fstest</code> is the handy little package of the standard library that doesn’t get enough\nattention, which is a shame, as it works perfectly alongside <code>embed</code>. <code>fstest.TestFS</code> takes your FS\nand a list of paths you expect to find within it, and then does two jobs at once:</p>\n<ul><li>Asserts every path you named is really there.</li><li><p>Cross-checks the file system against itself, walking the whole thing to confirm that <code>Open</code>,</p><p><code>ReadDir</code> and <code>ReadFile</code> all agree with each other.</p></li></ul>\n<p>The trick is what you list. It shouldn’t be a whole inventory of the <code>FS</code>, just a handful of the\nfiles your code actually opens:</p>\n<pre><code>func TestAssetsArePresent(t *testing.T) {\n    // Extras are ignored, so adding a file needs no test change.\n    err := fstest.TestFS(static,\n        &quot;assets/index.css&quot;,\n        &quot;assets/index.js&quot;,\n    )\n    if err != nil {\n        t.Fatalf(&quot;files are not found: %v&quot;, err)\n    }\n}</code></pre>\n<p>Only name what you’d notice missing; the template your handler executes, the migration directory,\nthe default config. Everything else is just noise that makes the test brittle.</p>\n<h3 id=\"depend-on-fs-fs\">Depend on fs.FS</h3>\n<p>And this is the one thing I’d really like you to take away, and the answer to the rebuild problem we\nstarted this section with.</p>\n<pre><code>// Take the interface, not the implementation.\nfunc NewServer(assets fs.FS) *Server {\n    return &amp;Server{assets: assets}\n}\n\nfunc TestIndexHandlesAnEmptyTemplate(t *testing.T) {\n    srv := NewServer(fstest.MapFS{\n        &quot;templates/index.html&quot;: &amp;fstest.MapFile{Data: []byte(&quot;&quot;)},\n    })\n\n    // No files on disk, no embed, no build.\n    if err := srv.Render(io.Discard, &quot;index.html&quot;); err == nil {\n        t.Fatal(&quot;expected an error for an empty template&quot;)\n    }\n}</code></pre>\n<p>Take <code>fs.FS</code> in your constructors, not <code>embed.FS</code>. Your server doesn’t care where the files came\nfrom; it cares that it can open them. Which means a test can hand you an <code>fstest.MapFS</code> instead,\nwith the files declared inline as a map.</p>\n<p>And now you can ask the questions a good unit test should ask. What if this file is empty? What if\nit’s corrupt, or 40 megabytes? You can answer all of that without touching the disk or waiting on a\nbuild. It’s also how you sidestep the rebuild-to-change-a-byte problem in development: the same\nconstructor takes <code>os.DirFS(&quot;./assets&quot;)</code> while you’re working and your <code>embed.FS</code> in production, and\nnothing else in your program needs to know which one it got.</p>\n<hr />\n<h2 id=\"wrapping-up\">Wrapping up</h2>\n<p>So that’s the whole journey, from a comment in your source to bytes in the <code>rodata</code> section of a\nbinary you can copy anywhere.</p>\n<p><code>//go:embed</code> is one of those quiet features about Go that makes it so easy to reason about. It’s\na kind of feature that you didn’t know you needed until it came along. It makes for a great\nexperience when you’re building a package that needs to ship some data with it.</p>\n<p>I would really encourage you to have a look at the Go source code, although it can look scary at\nfirst (I spent some time dazed and confused looking at it). But it really makes you a better\nengineer for knowing how these constructs work.</p>\n<p>Please reach out to me at <a href=\"mailto:hello@ainsley.dev\">hello@ainsley.dev</a>\nif you have any questions!\nI hope you’ve enjoyed reading this post as much as I have writing it.</p>\n<hr />\n<h3 id=\"source-code\">Source code</h3>\n<p>A reminder for each section, its program, package and line numbers are below:</p>\n<div class=\"table-wrap\"><table><thead><tr><th>Section</th><th>Program</th><th>Package</th><th>Evidence</th></tr></thead><tbody><tr><td>Packages</td><td><code>go</code></td><td><code>go/build</code></td><td><a href=\"https://github.com/golang/go/blob/go1.27.1/src/go/build/read.go#L314\" rel=\"nofollow ugc noopener\"><code>read.go:314</code></a> (imports-only parse)</td></tr><tr><td>Lexer</td><td><code>go</code></td><td><code>go/build</code></td><td><a href=\"https://github.com/golang/go/blob/go1.27.1/src/go/build/read.go#L379-L385\" rel=\"nofollow ugc noopener\"><code>read.go:379-385</code></a> (the embed scan)</td></tr><tr><td>Patterns</td><td><code>go</code></td><td><code>cmd/go/internal/load</code></td><td><a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/go/internal/load/pkg.go#L2165\" rel=\"nofollow ugc noopener\"><code>pkg.go:2165</code></a> <code>resolveEmbed</code>; JSON written by <a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/go/internal/work/gc.go#L148-L152\" rel=\"nofollow ugc noopener\"><code>work/gc.go:148-152</code></a></td></tr><tr><td>Parser</td><td><code>compile</code></td><td><code>cmd/compile/internal/syntax</code></td><td><a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/syntax/parser.go\" rel=\"nofollow ugc noopener\"><code>parser.go</code></a> ; the directive is attached by <code>noder</code></td></tr><tr><td>Compiler</td><td><code>compile</code></td><td><code>cmd/compile/internal/noder</code></td><td><a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/noder/noder.go#L462\" rel=\"nofollow ugc noopener\"><code>noder.go:462</code></a> <code>checkEmbed</code>; then <code>ssagen</code>, <code>staticdata</code>, <code>gc</code></td></tr><tr><td>Linker</td><td><code>link</code></td><td><code>cmd/link/internal/ld</code></td><td></td></tr><tr><td>Binary</td><td>-</td><td>-</td><td></td></tr></tbody></table></div>\n<h2 id=\"further-reading\">Further reading</h2>\n<p><strong>Embed</strong></p>\n<ul><li><p><a href=\"https://go.googlesource.com/proposal/+/master/design/draft-embed.md\" rel=\"nofollow ugc noopener\">Draft design: Go command support for embedded static assets</a></p><p>, Russ Cox &amp; Brad Fitzpatrick, July 2020</p></li><li><a href=\"https://github.com/golang/go/issues/41191\" rel=\"nofollow ugc noopener\">The original proposal (#41191)</a></li><li><p><a href=\"https://github.com/golang/go/issues/41190\" rel=\"nofollow ugc noopener\">The <code>io/fs</code> proposal (#41190)</a></p><p>, the companion that makes <code>embed.FS</code> compose with everything</p></li><li><a href=\"https://pkg.go.dev/embed\" rel=\"nofollow ugc noopener\"><code>embed</code> package documentation</a></li><li><p><a href=\"https://go-review.googlesource.com/c/go/+/243942\" rel=\"nofollow ugc noopener\">CL 243942</a></p><p>, <code>embed</code>: implement <code>FS</code></p></li></ul>\n<p><strong>Go command</strong></p>\n<ul><li><p><a href=\"https://go-review.googlesource.com/c/go/+/243941\" rel=\"nofollow ugc noopener\">CL 243941</a></p><p>, <code>go/build</code>: recognise and report <code>//go:embed</code> lines</p></li><li><p><a href=\"https://go-review.googlesource.com/c/go/+/243945\" rel=\"nofollow ugc noopener\">CL 243945</a></p><p>, <code>cmd/go</code>: add <code>//go:embed</code> support</p></li><li><p><a href=\"https://github.com/golang/go/blob/go1.27.1/src/go/build/read.go#L314\" rel=\"nofollow ugc noopener\"><code>go/build/read.go#L314</code></a></p><p>, the imports-only parse the <code>go</code> command starts with</p></li></ul>\n<p><strong>Compiler</strong></p>\n<ul><li><a href=\"https://go.dev/src/cmd/compile/README\" rel=\"nofollow ugc noopener\">Go compiler README</a></li><li><p><a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/syntax/parser.go\" rel=\"nofollow ugc noopener\"><code>cmd/compile/internal/syntax/parser.go</code></a></p><p>, the compiler’s own parser, with the directive attached by <code>noder</code></p></li><li><p><a href=\"https://go-review.googlesource.com/c/go/+/243944\" rel=\"nofollow ugc noopener\">CL 243944</a></p><p>, <code>cmd/compile</code>: add <code>//go:embed</code> support</p></li><li><a href=\"https://github.com/golang/go/blob/go1.27.1/src/cmd/compile/internal/staticdata/embed.go\" rel=\"nofollow ugc noopener\"><code>staticdata/embed.go</code>, where the bytes are written</a></li></ul>\n<p><strong>Linker</strong></p>\n<ul><li><a href=\"https://pkg.go.dev/cmd/link\" rel=\"nofollow ugc noopener\">Go linker documentation</a></li><li><a href=\"https://go.dev/src/cmd/link/\" rel=\"nofollow ugc noopener\">Go linker source code</a></li></ul>\n<p><strong>Runtime</strong></p>\n<ul><li><p><a href=\"https://github.com/golang/go/blob/go1.27.1/src/embed/embed.go\" rel=\"nofollow ugc noopener\"><code>src/embed/embed.go</code></a></p><p>, the whole <code>embed.FS</code> implementation, and a genuinely short read</p></li><li><p><a href=\"https://pkg.go.dev/testing/fstest\" rel=\"nofollow ugc noopener\"><code>testing/fstest</code></a></p><p>, <code>TestFS</code> and <code>MapFS</code></p></li><li><a href=\"https://pkg.go.dev/runtime\" rel=\"nofollow ugc noopener\">Go runtime package documentation</a></li><li><a href=\"https://go.dev/src/runtime/HACKING\" rel=\"nofollow ugc noopener\">Go runtime internals</a></li></ul>\n<p><strong>Other languages</strong></p>\n<ul><li><p>*<em>D*</em>, <code>import(&quot;file.txt&quot;)</code>, an expression, documented since D 1.0 (<a href=\"https://dlang.org/spec/expression.html\" rel=\"nofollow ugc noopener\">spec</a></p><p>)</p></li><li><p><strong>Zig</strong>, <code>@embedFile</code>, in the docs since 0.1.1 (<a href=\"https://github.com/ziglang/zig/issues/14637\" rel=\"nofollow ugc noopener\">ziglang/zig#14637</a></p><p>)</p></li></ul>\n<p><strong>Community</strong></p>\n<ul><li><p><a href=\"https://reddit.com/r/golang/comments/kfm4ly/embed_files_in_go_using_new_embed_package_in_go/\" rel=\"nofollow ugc noopener\">Embed files in Go using the new <code>embed</code> package</a></p><p>, the thread the quote at the top comes from</p></li><li><a href=\"https://news.ycombinator.com/item?id=26158090\" rel=\"nofollow ugc noopener\">Go 1.16 release notes on Hacker News</a></li><li><a href=\"https://blog.jetbrains.com/go/2021/06/09/how-to-use-go-embed-in-go-1-16/\" rel=\"nofollow ugc noopener\">JetBrains, How to use <code>go:embed</code> in Go</a></li></ul>","headings":[{"level":1,"text":"How //go:embed Works: From Source Files to Binary","id":"how-go-embed-works-from-source-files-to-binary"},{"level":2,"text":"Contents","id":"contents"},{"level":2,"text":"The directive: What it is","id":"the-directive-what-it-is"},{"level":3,"text":"We’ve all seen this?","id":"we-ve-all-seen-this"},{"level":3,"text":"What it is not","id":"what-it-is-not"},{"level":2,"text":"The variable: How to use it","id":"the-variable-how-to-use-it"},{"level":3,"text":"embed.FS","id":"embed-fs"},{"level":3,"text":"Working example","id":"working-example"},{"level":2,"text":"The binary: How it’s built","id":"the-binary-how-it-s-built"},{"level":3,"text":"Compiler basics","id":"compiler-basics"},{"level":3,"text":"Packages (go build)","id":"packages-go-build"},{"level":3,"text":"Lexer (go build)","id":"lexer-go-build"},{"level":3,"text":"Patterns (go build)","id":"patterns-go-build"},{"level":3,"text":"Parser (cmd/compile)","id":"parser-cmd-compile"},{"level":3,"text":"Compiler (cmd/compile)","id":"compiler-cmd-compile"},{"level":3,"text":"Linker (cmd/link)","id":"linker-cmd-link"},{"level":3,"text":"Binary","id":"binary"},{"level":3,"text":"Build Summary","id":"build-summary"},{"level":2,"text":"The runtime: How it’s read","id":"the-runtime-how-it-s-read"},{"level":2,"text":"The tradeoffs: What you take on","id":"the-tradeoffs-what-you-take-on"},{"level":3,"text":"Rebuild to change a byte","id":"rebuild-to-change-a-byte"},{"level":3,"text":"No secrets","id":"no-secrets"},{"level":3,"text":"What the compiler catches","id":"what-the-compiler-catches"},{"level":3,"text":"Testing what you embedded","id":"testing-what-you-embedded"},{"level":3,"text":"Depend on fs.FS","id":"depend-on-fs-fs"},{"level":2,"text":"Wrapping up","id":"wrapping-up"},{"level":3,"text":"Source code","id":"source-code"},{"level":2,"text":"Further reading","id":"further-reading"}]}}