afero

To use Afero in your Go project, install it using go get and import the package.

go get github.com/spf13/afero

import "github.com/spf13/afero"

To make your code testable and portable, avoid calling the os package directly. Instead, design your functions to accept the afero.Fs interface. You can then use Afero utility functions (which mirror os and ioutil) to interact with the filesystem.

import "github.com/spf13/afero"

// After: Decoupled, flexible, and testable
func ProcessConfiguration(fs afero.Fs, path string) error {
    // Use Afero utility functions which mirror os/ioutil
    data, err := afero.ReadFile(fs, path)
    // ... process the data
    return err
}

Use afero.NewHttpFs to wrap any Afero filesystem (including in-memory ones) so it can be used with Go's standard http.FileServer.

import (
    "net/http"
    "github.com/spf13/afero"
)

func main() {
    memFS := afero.NewMemMapFs()
    afero.WriteFile(memFS, "index.html", []byte("<h1>Hello from Memory!</h1>"), 0644)

    // Wrap the memory filesystem to make it compatible with http.FileServer.
    httpFS := afero.NewHttpFs(memFS)

    http.Handle("/", http.FileServer(httpFS.Dir("/")))
    http.ListenAndServe(":8080", nil)
}

Use BasePathFs to restrict an application's filesystem access to a specific subdirectory (chroot). This prevents directory traversal attacks by making the target subdirectory appear as the root (/) to the application.

osFs := afero.NewOsFs()

// Create a filesystem rooted at /home/user/public
// The application cannot access anything above this directory.
jailedFs := afero.NewBasePathFs(osFs, "/home/user/public")

// To the application, this is reading "/"
// In reality, it's reading "/home/user/public/"
dirInfo, err := afero.ReadDir(jailedFs, "/")

// Attempts to access parent directories fail
_, err = jailedFs.Open("../secrets.txt") // Returns an error

You can treat ZIP archives as standard afero.Fs instances using the zipfs package. This allows you to read or traverse archive contents using standard Afero methods without needing to extract the files to a temporary directory first.

import (
    "archive/zip"
    "github.com/spf13/afero/zipfs"
)

// Open any .zip — from disk, an HTTP response body, or memory
zipFile, _ := zip.OpenReader("bundle.zip")
defer zipFile.Close()

// Treat the archive as a filesystem — no extraction needed
archiveFS := zipfs.New(&zipFile.Reader)

// The same code that works with OsFs or MemMapFs works here unchanged
content, err := afero.ReadFile(archiveFS, "docs/readme.md")
entries, err := afero.ReadDir(archiveFS, "configs/")

Layer a fast in-memory cache over a slow backend (like SFTP or GCS) using CacheOnReadFs. The first read fetches from the base and populates the cache; subsequent reads are served instantly from the cache layer.

import "time"

// Assume 'remoteFs' is a slow backend (e.g., SFTP or GCS)
var remoteFs afero.Fs 

// 'cacheFs' is a fast in-memory backend
cacheFs := afero.NewMemMapFs()

// Create the caching layer. Cache items for 5 minutes upon first read.
cachedFs := afero.NewCacheOnReadFs(remoteFs, cacheFs, 5*time.Minute)

// The first read is slow (fetches from remote, then caches)
data1, _ := afero.ReadFile(cachedFs, "data.json")

// The second read is instant (serves from memory cache)
data2, _ := afero.ReadFile(cachedFs, "data.json")

Use CopyOnWriteFs to create a sandbox where writes are captured in an in-memory overlay, leaving the base filesystem (e.g., the real OS) untouched. This is ideal for integration tests or isolating untrusted code.

// 1. The base layer is the real OS, made read-only for safety.
baseFs := afero.NewReadOnlyFs(afero.NewOsFs())

// 2. The overlay layer is a temporary in-memory filesystem for changes.
overlayFs := afero.NewMemMapFs()

// 3. Combine them. Reads fall through to the base; writes only hit the overlay.
sandboxFs := afero.NewCopyOnWriteFs(baseFs, overlayFs)

// The application can now "modify" /etc/hosts, but the changes are isolated in memory.
afero.WriteFile(sandboxFs, "/etc/hosts", []byte("127.0.0.1 sandboxed-app"), 0644)

// The real /etc/hosts on disk is untouched.

You can use Go's native //go:embed directive and convert the resulting embed.FS into an Afero filesystem using afero.FromIOFS.

import (
    "embed"
    "github.com/spf13/afero"
)

//go:embed assets/*
var assetsFS embed.FS

func main() {
    // Convert embedded files to Afero filesystem
    fs := afero.FromIOFS(assetsFS)
    
    // Use like any other Afero filesystem
    content, _ := afero.ReadFile(fs, "assets/config.json")
}

Afero is fully compatible with Go 1.16+'s io/fs package. To satisfy a fs.FS interface (which is read-only), wrap your afero.Fs instance using afero.NewIOFS.

import "io/fs"

// Create an Afero filesystem (writable)
var myAferoFs afero.Fs = afero.NewMemMapFs()

// Convert it to a standard library fs.FS (read-only view)
var myIoFs fs.FS = afero.NewIOFS(myAferoFs)

The Afero ecosystem includes several third-party backends for cloud and specialized storage.

Production-ready recommendations:

• Amazon S3: fclairamb/afero-s3 (built on official AWS SDK)
• MinIO: cpyun/afero-minio (S3-compatible with deduplication)

Other notable backends:

• Google Drive: fclairamb/afero-gdrive (Streaming support; no write-seeking/POSIX)
• Dropbox: fclairamb/afero-dropbox (Streaming support; no write-seeking/POSIX)
• Git Repositories: tobiash/go-gitfs (Read-only view of git references)
• Docker Containers: unmango/aferox (Access container filesystems)
• GitHub API: unmango/aferox (Browse repos, releases, and assets)