Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Errors, I/O and Files

Go io/fs package

Reference for Go io/fs: the fs.FS interface, ReadFile, ReadDir, Stat, Glob, Sub, WalkDir, os.DirFS, fstest.MapFS, fs.ErrNotExist and file modes.

The io/fs package (Go 1.16) defines a read-only view of a file system as a tiny interface: fs.FS has one method, Open(name string) (fs.File, error). Anything that can open named files can implement it: the real disk (os.DirFS), files embedded in the binary (embed.FS), a zip archive (zip.Reader), a test fixture (fstest.MapFS) or your own remote storage.

Code written against fs.FS is easy to test and works with any of them. Helper functions such as fs.ReadFile, fs.ReadDir, fs.Stat, fs.Glob, fs.Sub and fs.WalkDir give you convenient operations on top of the minimal interface, and use faster optional methods when the file system provides them.

Go
var fsys fs.FS = os.DirFS("/srv/site")
page, err := fs.ReadFile(fsys, "index.html")

Try it

Go One function, memory and disk

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Errors, paths and WalkDir

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

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

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

func ReadFile(fsys FS, name string) ([]byte, error)
func ReadDir(fsys FS, name string) ([]DirEntry, error)
func Stat(fsys FS, name string) (FileInfo, error)
func Glob(fsys FS, pattern string) ([]string, error)
func Sub(fsys FS, dir string) (FS, error)
func WalkDir(fsys FS, root string, fn WalkDirFunc) error
func ValidPath(name string) bool
func FormatFileInfo(info FileInfo) string
Type or value Purpose
fs.DirEntry A directory listing entry: Name, IsDir, Type, Info.
fs.FileInfo Name, size, mode, modification time, IsDir, Sys.
fs.FileMode Type and permission bits; ModeDir, ModeSymlink, ModePerm and so on.
fs.ReadDirFS, ReadFileFS, StatFS, GlobFS, SubFS Optional interfaces a file system may implement for speed.
fs.ErrNotExist, ErrExist, ErrPermission, ErrInvalid, ErrClosed Sentinel errors; use errors.Is.
fs.PathError Operation, path and underlying error.
fs.SkipDir, fs.SkipAll Return values for WalkDir callbacks.

Errors: invalid names make Open return a *fs.PathError wrapping fs.ErrInvalid; missing files wrap fs.ErrNotExist.

Usage notes

  • Names are always slash-separated, never start with /, never contain . or .. elements and are never empty. The root of any file system is ".". Check with fs.ValidPath. This holds on Windows too.
  • os.DirFS("dir") does not sandbox symlinks: a link inside the directory can still point outside it. Go 1.24's os.Root and its FS() method give real confinement.
  • Read-only by design. There is no Write in fs.FS; for writing, use os (or the os.Root methods).
  • Accept fs.FS in your functions (parse templates, load config, serve static files) so tests can pass an fstest.MapFS and production can pass embed.FS or os.DirFS.
  • fstest.TestFS(fsys, "expected/files") checks that your own implementation obeys the rules.
  • http.FileServerFS, template.ParseFS and zip.Reader all work with fs.FS, which is the payoff of the abstraction.
  • fs.Glob uses path.Match rules: * never crosses /, and there is no **.
  • fs.WalkDir vs filepath.WalkDir: the former takes a file system and works with slash paths; the latter walks the real disk using OS paths.
  • Since Go 1.23, os.CopyFS(dir, fsys) copies an fs.FS to disk.