Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Errors, I/O and Files

Go filepath.WalkDir() function

Reference for Go filepath.WalkDir and fs.WalkDir: recurse through directories, skip subtrees with SkipDir, stop early with SkipAll, and handle errors.

filepath.WalkDir visits every file and directory under a root, calling your function for each one. The visit order is lexical (sorted by name) and parents are visited before their children, so output is deterministic. The callback receives a fs.DirEntry, which already knows whether the entry is a directory, so the walk does not need an extra stat call per file.

WalkDir replaces the older filepath.Walk, which is slower for the same reason. The same function exists in io/fs as fs.WalkDir(fsys, root, fn) for any file-system abstraction, including embed.FS and os.DirFS.

Go
err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
	if err != nil {
		return err
	}
	fmt.Println(path)
	return nil
})

Try it

Go Listing a tree and skipping a directory

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 Collecting, summing and stopping early

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
func WalkDir(root string, fn fs.WalkDirFunc) error
func fs.WalkDir(fsys fs.FS, root string, fn fs.WalkDirFunc) error

type WalkDirFunc func(path string, d fs.DirEntry, err error) error
Name Description
root Directory (or file) to start from. It is passed to fn first, exactly as given.
path Root joined with the entry name, for example root/sub/b.txt.
d The entry: Name(), IsDir(), Type(), Info(). May be nil if the root could not be read.
err Non-nil when reading the entry or directory failed.

Return value of the callback controls the walk:

Callback returns Effect
nil Continue.
filepath.SkipDir On a directory: skip its contents. On a file: skip the remaining files in the containing directory.
filepath.SkipAll (Go 1.20) Stop the whole walk; WalkDir returns nil.
any other error Stop the walk and return that error.

Usage notes

  • Check err first. If the root does not exist, fn is called once with d == nil and that error; touching d would panic.
  • Symbolic links are not followed. A link to a directory is reported as a non-directory entry. Resolve it yourself if you need to recurse.
  • d.Info() costs a system call (lstat) and can fail if the file vanished; avoid it when d.Name(), d.IsDir() or d.Type() is enough.
  • The tree may change during a walk. Files created or deleted concurrently may or may not be seen.
  • Returning an error from a directory read (for example permission denied) lets you decide: return nil or filepath.SkipDir to carry on, anything else to abort.
  • Order: entries are read and sorted per directory, so a walk is reproducible; large directories are held in memory while sorted.
  • Use fs.WalkDir with fs.FS to walk embedded files or test fixtures; paths there always use forward slashes.
  • Do not modify the tree you are walking unless you understand the effect on later visits. Collect paths first, then change them.
  • filepath.Walk still works, but gives you a full fs.FileInfo (one lstat per entry) and is slower.