Files with os and io/fs
A file in Go is a reader and a writer with a name, and os has a one-call function for the two common cases: read the whole thing, write the whole thing. The io/fs package then describes any tree of files as an interface, so walking a directory does not care whether it is a disk, an embedded asset or a test fixture. Every program here works in a temporary directory it removes when it is done.
WriteFile and ReadFile
os.WriteFile creates or truncates the file, writes the bytes and closes it; the mode is used only when the file is created. os.ReadFile opens, reads to the end and closes. The pair is right for a configuration file or a small document and wrong for a file larger than memory. The directory comes from os.MkdirTemp, and the deferred RemoveAll is the cleanup every example owes the system.
package main
import (
"fmt"
"os"
"path/filepath"
)
func main() {
dir, err := os.MkdirTemp("", "files")
if err != nil {
panic(err)
}
defer os.RemoveAll(dir)
path := filepath.Join(dir, "notes.txt")
if err := os.WriteFile(path, []byte("first\nsecond\n"), 0o644); err != nil {
panic(err)
}
data, err := os.ReadFile(path)
fmt.Printf("read: %q\n", string(data))
fmt.Println("error:", err)
}
go build -o app main.go && ./app
read: "first\nsecond\n"
error: <nil>
The two newlines are in the string, which %q shows. A mode of 0o644 is read-write for the owner and read-only for everyone else, before the umask; the kernel applies the umask, so the file on disk may be 0600. A program that cares passes the mode it wants and accepts the mask.
Open, Stat and Close
os.Open returns a *os.File that is a reader, and Stat describes it. The deferred Close is not optional: a program that opens files in a loop without closing them runs out of descriptors. Stat returns the size before any read, which is how a program decides whether to read at all.
package main
import (
"fmt"
"io"
"os"
"path/filepath"
)
func main() {
dir, err := os.MkdirTemp("", "files")
if err != nil {
panic(err)
}
defer os.RemoveAll(dir)
path := filepath.Join(dir, "notes.txt")
if err := os.WriteFile(path, []byte("first\nsecond\n"), 0o644); err != nil {
panic(err)
}
f, err := os.Open(path)
if err != nil {
panic(err)
}
defer f.Close()
info, err := f.Stat()
if err != nil {
panic(err)
}
data, err := io.ReadAll(f)
if err != nil {
panic(err)
}
fmt.Println("name:", info.Name())
fmt.Println("size:", info.Size())
fmt.Println("bytes:", len(data))
fmt.Println("mode:", info.Mode().Perm())
}
go build -o app main.go && ./app
name: notes.txt
size: 13
bytes: 13
mode: -rw-r--r--
The size and the bytes read agree, and the mode came back as the umask left it. info.Mode() is a fs.FileMode with the type bits as well; Perm keeps the nine permission bits, which is what a program that copies a file needs.
A filesystem as an fs.FS
os.DirFS(dir) presents a directory as an fs.FS, and fs.WalkDir visits every entry with paths relative to that root. The callback gets the path, the directory entry and an error; returning the error stops the walk. The order is lexical, which is why the tree below is predictable.
package main
import (
"fmt"
"io/fs"
"os"
"path/filepath"
)
func main() {
dir, err := os.MkdirTemp("", "files")
if err != nil {
panic(err)
}
defer os.RemoveAll(dir)
data := filepath.Join(dir, "data")
if err := os.MkdirAll(filepath.Join(data, "sub"), 0o755); err != nil {
panic(err)
}
if err := os.WriteFile(filepath.Join(data, "a.txt"), []byte("a"), 0o644); err != nil {
panic(err)
}
if err := os.WriteFile(filepath.Join(data, "sub", "b.txt"), []byte("b"), 0o644); err != nil {
panic(err)
}
err = fs.WalkDir(os.DirFS(dir), "data", func(path string, d fs.DirEntry, err error) error {
if err != nil {
return err
}
fmt.Println(path, d.IsDir())
return nil
})
fmt.Println("walk error:", err)
}
go build -o app main.go && ./app
data true
data/a.txt false
data/sub true
data/sub/b.txt false
walk error: <nil>
The root is "data", the directory the program created inside the temporary one, so every path starts with it; the paths use forward slashes because they are fs paths and not OS paths, and a directory comes before its contents. Walking from the temporary root itself would start with ".", the one entry a walk reports that is not a real name. The same call walks an embed.FS with no change, which is the reason to prefer fs.FS over a path string in a function that reads a tree.
A file that is not there
A missing file is an error, not a panic, and the error wraps fs.ErrNotExist. A program tests it with errors.Is rather than by matching the text, because the operating system and the filesystem write the message differently. The path in the message is the absolute one the program passed.
package main
import (
"errors"
"fmt"
"io/fs"
"os"
"path/filepath"
)
func main() {
path := filepath.Join(os.TempDir(), "does-not-exist.txt")
_, err := os.ReadFile(path)
fmt.Println("error:", err)
fmt.Println("not exist:", errors.Is(err, fs.ErrNotExist))
}
go build -o app main.go && ./app
error: open /tmp/does-not-exist.txt: no such file or directory
not exist: true
The text names the call and the path, and errors.Is confirms the category. A program that creates a default file when one is missing tests this way; a program that reports a bad path to a user also tests this way, because the alternative is a string comparison that breaks on another system.
Paths, modes and cleanup
Paths are built with path/filepath, not with string concatenation, so the next lesson takes that apart. A temporary directory is created with MkdirTemp and removed with a deferred RemoveAll; a test that leaves one behind fills the disk of the runner after a thousand runs. os.Create is OpenFile with O_RDWR|O_CREATE|O_TRUNC and mode 0666, which is why a program that needs append uses OpenFile with O_APPEND.
Writing a file safely takes one more step than this lesson shows: write to a temporary name in the same directory, sync it, then rename it over the target. A rename is atomic on one filesystem, so a reader sees either the old file or the new one, and never a half-written one. The capstone projects use that shape for their store.
Exercises
- Write a file with mode 0o600 and read the mode back with Stat. What does the umask change, and what does it leave alone?
- Walk the temporary tree with filepath.WalkDir instead of fs.WalkDir. What is different in the paths, and why does the fs version use forward slashes?
- Replace the missing-file read with os.Open and compare the error. Which call names the operation, and which one only the path?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does os.ReadFile do?
Answer
Opens, reads to the end and closes the file
It is the one-call form for a whole file.
-
What does os.WriteFile do to an existing file?
Answer
Truncates and rewrites it
Appending needs os.OpenFile with O_APPEND.
-
When is the mode of WriteFile used?
Answer
Only when the file is created
An existing file keeps its mode.
-
Why defer f.Close after os.Open?
Answer
A leaked descriptor is a resource leak
A loop of opens without closes runs out of descriptors.
-
What does f.Stat report before the read?
Answer
The name, size and mode of the file
The size is known without reading.
-
What does os.DirFS(dir) return?
Answer
An fs.FS rooted at the directory
fs.WalkDir and fs.ReadFile accept it.
-
In which order does fs.WalkDir visit a tree?
Answer
Lexical, directory before its contents
The root comes first, then entries by name.
-
How is a missing file recognised?
Answer
errors.Is(err, fs.ErrNotExist)
The category survives different messages.
-
What is the safe way to replace a file?
Answer
Write a temporary file in the same directory and rename it
A rename is atomic on one filesystem.
-
What does os.MkdirTemp create?
Answer
A new directory with a unique name
RemoveAll in a defer cleans it up.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev