s3fs-fuse: Mount an S3 Bucket as a Local Filesystem on Linux, macOS, and FreeBSD

What s3fs-fuse Does and Who It Is For

s3fs-fuse is a FUSE-based filesystem driver. It mounts an S3 bucket to a local directory and presents the bucket's objects as files and folders. Programs that open, read, and write files through the standard filesystem API work against the S3 bucket without modification. This makes it useful for legacy applications and scripts that are not designed to use the S3 API directly, and for tooling that needs to operate on S3-stored files using utilities like grep, find, or rsync.

The tool supports Amazon S3 and a range of S3-compatible object stores. The README lists specific compatibility with non-Amazon implementations in the project wiki. s3fs-fuse preserves the native S3 object format for files, meaning objects written through the FUSE mount remain accessible to other tools like the AWS CLI when accessed directly through the S3 API. This native format preservation distinguishes it from alternatives like s3ql, which use a proprietary object layout.

The FUSE mechanism works at the OS level. The s3fs-fuse process handles filesystem operations by translating them into S3 API calls transparently. The user-space implementation means no kernel modules need to be loaded beyond the base FUSE module, which simplifies deployment in containerised environments.

POSIX Features and Their Object-Store Limits

s3fs-fuse supports a large subset of POSIX operations: reading and writing files, directory creation, symlinks, file modes, uid/gid ownership, and extended attributes. It also supports random writes and appends, renames via server-side copy, optional server-side encryption, and data integrity checks via MD5 hashes.

The implementation stores metadata in S3 object headers. In-memory metadata caching and local disk data caching are included to reduce API call volume. The README documents support for large files via multi-part upload, which breaks large uploads into segments that S3 reassembles. This makes it practical for files that exceed the 5 GB single-PUT limit.

Authentication supports both AWS signature v2 and v4. The tool accepts credentials from three sources: the standard AWS credentials file at `${HOME}/.aws/credentials`, a custom password file at `${HOME}/.passwd-s3fs` or `/etc/passwd-s3fs`, and the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables. User-specified regions are supported, including Amazon GovCloud, and path-style requests can be enabled for S3-compatible stores that require them.

Installing s3fs-fuse and Mounting a Bucket

Most Linux distributions provide pre-built packages. On Ubuntu or Debian:

sudo apt install s3fs

On macOS via Homebrew:

brew install --cask macfuse
brew install gromgit/fuse/s3fs-mac

Store credentials in a password file and restrict permissions:

echo ACCESS_KEY_ID:SECRET_ACCESS_KEY > ${HOME}/.passwd-s3fs
chmod 600 ${HOME}/.passwd-s3fs

Mount a bucket:

s3fs mybucket /path/to/mountpoint -o passwd_file=${HOME}/.passwd-s3fs

To mount automatically at boot, add a line to /etc/fstab:

mybucket /path/to/mountpoint fuse.s3fs _netdev,allow_other 0 0

For S3-compatible stores, add the URL and path-style request option:

s3fs mybucket /path/to/mountpoint -o passwd_file=${HOME}/.passwd-s3fs -o url=https://url.to.s3/ -o use_path_request_style

Debug output is available by adding `-o dbglevel=info -f -o curldbg` to the mount command.

The Six Documented Limitations

The README states clearly that S3 cannot offer the same performance or semantics as a local filesystem, and lists six specific constraints that users must understand before deploying s3fs-fuse in production.

First, random writes or appends to an existing file require rewriting the entire object. s3fs-fuse optimises this with multi-part upload copy, but the underlying cost of downloading and reuploading the full object remains for large files. This makes s3fs-fuse a poor fit for databases or any application that performs frequent small writes to large files.

Second, metadata operations like listing directories have poor performance because of network latency; every directory listing is a separate S3 API call. Deep directory trees or directories with many objects will be noticeably slower than a local filesystem.

Third, non-AWS providers may have eventual consistency, meaning reads can return stale data after a write. AWS offers read-after-write consistency since December 2020, but this behaviour is provider-specific and should not be assumed for third-party S3-compatible stores.

Fourth, there are no atomic renames of files or directories. The rename operation in s3fs-fuse copies the object via server-side copy and then deletes the original, which is not atomic from the S3 API perspective. Fifth, there is no coordination between multiple clients mounting the same bucket simultaneously. Concurrent writes from two machines can silently overwrite each other with no error.

Sixth, inotify detects only local modifications, not changes made by other clients or direct S3 API calls. Applications that poll the filesystem for changes via inotify will not see writes from other processes or machines.

s3fs-fuse Compared to goofys

The README links to goofys as a directly comparable tool with a different trade-off. goofys is described in the README as offering better performance and less POSIX compatibility than s3fs-fuse. This means goofys sacrifices some POSIX compliance to reduce the number of API calls per operation, which results in faster throughput for workloads that do not need strict POSIX behaviour.

The practical implication: s3fs-fuse is better suited to applications that depend on POSIX semantics such as symlinks, extended attributes, or uid/gid ownership. goofys is better suited to applications that primarily need fast sequential read and write performance and can tolerate the omissions in POSIX coverage.

The README also lists three other related tools. s3ql is described as similar to s3fs but uses its own proprietary object format, which means files written via s3ql cannot be read directly by other S3 clients. s3backer takes a different architectural approach entirely: it mounts the entire S3 bucket as a single block device file, which is suitable for full disk image backups but not general-purpose file access. YAS3FS is described as similar to s3fs but uses Amazon SNS notifications to coordinate cache invalidation across multiple clients mounting the same bucket, addressing the multi-client consistency problem that s3fs-fuse leaves unsolved.

For Kubernetes workloads, the README references a CSI driver for S3 (csi-s3) as a separate project. For containerised use without Kubernetes, a Docker image containing s3fs (docker-s3fs-client) is also listed. The s3fs-fuse project itself uses the native S3 object format throughout, ensuring that files written via the FUSE mount are readable by any other S3-compatible client without conversion.

Platform Coverage, Release History, and License

s3fs-fuse runs on Linux, macOS (10.12 and newer), and FreeBSD. Windows has a separate installation documented in COMPILATION.md. Package manager support is broad. On Amazon Linux, the package installs via EPEL: `sudo amazon-linux-extras install epel` then `sudo yum install s3fs-fuse`. Arch Linux, Debian 9 and newer, Ubuntu 16.04 and newer, Fedora 27 and newer, Gentoo, RHEL and CentOS 7 and newer via EPEL, SUSE 12 and openSUSE 42.1 and newer, and FreeBSD all have packages. macOS is also available via MacPorts in addition to Homebrew. The snap package works on platforms with snap support via `sudo snap install hexyl`, and the Scoop package manager supports Windows.

Building from source requires the standard autotools toolchain; the repository root contains configure.ac, Makefile.am, and autogen.sh. The release page at github.com/s3fs-fuse/s3fs-fuse/releases provides pre-built binaries for platforms without a package.

The most recent release is v1.97, published on 2025-12-08. The repository's last push was on 2026-09-24, showing continued maintenance activity after the last release.

The project is licensed under the GNU GPL version 2. Any software that distributes s3fs-fuse must comply with GPL-2.0 terms, including providing source code. The README credits the original author as Randy Rizun, with the copyright dating to 2010.

Editorial conclusion

s3fs-fuse is a practical choice when you have existing tooling that reads and writes files via POSIX paths and you need it to work against S3 without code changes. The critical limitation is that S3 is not a filesystem: directory listings are slow, appends rewrite the entire object, atomic renames do not exist, and there is no coordination between multiple clients mounting the same bucket. For any workload where these gaps matter, a purpose-built tool is a better fit. If your workload is primarily sequential reads and writes of large individual files, s3fs-fuse's multi-part upload support and in-memory metadata caching make it workable.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. s3fs-fuse/s3fs-fuse on GitHub