Master Go’s IO, OS, and embed Packages: A Complete Guide to File Operations

For developers new to Go, file I/O can be confusing because several standard packages— io, os, embed, and even http —expose overlapping types such as Reader, Writer, and FS. This guide systematically maps those relationships and shows how to use them together.

1. The io Package

The io package defines two main groups of interfaces.

Basic stream interfaces : Reader, Writer,

Seeker</strong>, and <code>Closer</strong>. They represent reading, writing, seeking, and closing operations.</li>
<li><strong>Extended interfaces</strong>: <code>ReaderAt

, RuneReader, ByteReader, ReaderFrom, WriterAt, WriterTo, StringWriter, etc., which add random‑access or bulk‑copy capabilities.

Key source excerpts (simplified):

type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

type Seeker interface {
    Seek(offset int64, whence int) (int64, error)
}

type Closer interface {
    Close() error
}

Utility functions such as Copy, CopyBuffer, CopyN, ReadAll, ReadAtLeast, and ReadFull are also provided. For example, Copy(dst Writer, src Reader) copies data until src reaches EOF, returning the number of bytes written and the first error encountered.

2. The io/fs Sub‑package

The fs sub‑package introduces a hierarchical file‑system abstraction. Important interfaces include:

type File interface {
    Stat() (FileInfo, error)
    Read([]byte) (int, error)
    Close() error
}

type FileInfo interface {
    Name() string
    Size() int64
    Mode() FileMode
    ModTime() time.Time
    IsDir() bool
    Sys() any
}

type FS interface {
    Open(name string) (File, error)
}

type DirEntry interface {
    Name() string
    IsDir() bool
    Type() FileMode
    Info() (FileInfo, error)
}

3. The os Package

The os package implements the same concepts as io/fs but adds concrete types such as os.File. It re‑exports fs.FileInfo and fs.FileMode for compatibility.

Typical file‑reading code:

file, err := os.Open("example.txt")
if err != nil {
    fmt.Println("Error:", err)
    return
}
defer file.Close()

data := make([]byte, 100)
count, err := file.Read(data)
if err != nil {
    fmt.Println("Error:", err)
    return
}
fmt.Printf("Read %d bytes: %s
", count, data[:count])

Writing a file:

file, err := os.Create("example.txt")
if err != nil {
    fmt.Println("Error:", err)
    return
}
defer file.Close()

_, err = file.Write([]byte("Hello, world!
"))
if err != nil {
    fmt.Println("Error:", err)
    return
}
fmt.Println("Data has been written")

Directory traversal can be done with os.DirFS which returns an fs.FS implementation:

root := "/usr/local/go/bin"
fsys := os.DirFS(root) // fsys implements fs.FS

4. The net/http Package for Static Files

Using http.FileServer together with an fs.FS (or os.DirFS) makes it trivial to serve static assets:

root := "/local/xxx/static"
rootFS := os.DirFS(root)
staticHandler := http.FileServer(http.FS(rootFS))
http.Handle("/static/", http.StripPrefix("/static/", staticHandler))

5. The embed Package (Go 1.16+)

The embed package lets you bundle files into the binary at compile time. Files can be embedded as string, []byte, or embed.FS.

//go:embed hello.txt
var s string

//go:embed hello.txt
var b []byte

//go:embed static/*
var staticFiles embed.FS

Embedded files expose the same fs.FS methods ( Open, ReadDir, ReadFile) as the regular file‑system package.

Example: serve embedded static files via HTTP:

package main

import (
    "embed"
    "log"
    "net/http"
)

//go:embed static/*
var staticFiles embed.FS

func main() {
    fileServer := http.FileServer(http.FS(staticFiles))
    http.Handle("/static/", http.StripPrefix("/static/", fileServer))
    log.Println("Server started on http://localhost:8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

6. Summary

Go’s standard library provides a consistent set of interfaces for file I/O across multiple packages. Understanding the core io interfaces, the hierarchical io/fs abstraction, and how os, http, and embed build on top of them enables developers to read, write, serve, and embed files with confidence.