s3fs

FUSE-based filesystem that mounts S3-compatible buckets as local directories. Supports AWS S3, MinIO, Ceph, and any S3-compatible storage.

For Kubernetes, see k8s-csi-s3 instead.

Install

# NixOS
environment.systemPackages = [ pkgs.s3fs ];
 
# Debian/Ubuntu
apt install s3fs
 
# macOS (via Homebrew)
brew install --cask macfuse && brew install s3fs

Credentials

# ~/.passwd-s3fs
ACCESS_KEY_ID:SECRET_ACCESS_KEY
chmod 600 ~/.passwd-s3fs

Or per-bucket in /etc/passwd-s3fs.

Mount

# Basic mount
s3fs my-bucket /mnt/s3 -o passwd_file=~/.passwd-s3fs
 
# Custom endpoint (MinIO etc.)
s3fs my-bucket /mnt/s3 \
  -o passwd_file=~/.passwd-s3fs \
  -o url=https://minio.example.com \
  -o use_path_request_style
 
# With options
s3fs my-bucket /mnt/s3 \
  -o passwd_file=~/.passwd-s3fs \
  -o allow_other \
  -o umask=0022 \
  -o uid=1000 \
  -o gid=1000
 
# Unmount
fusermount -u /mnt/s3

/etc/fstab entry

my-bucket /mnt/s3 fuse.s3fs _netdev,allow_other,use_path_request_style,url=https://minio.example.com,passwd_file=/etc/passwd-s3fs 0 0

Key options

Option	Description
url=	Custom endpoint URL
use_path_request_style	Use path-style URLs (needed for MinIO)
allow_other	Allow other users to access the mount
uid= / gid=	File ownership
umask=	File permissions mask
stat_cache_expire=	Seconds to cache stat results
parallel_count=	Parallel upload threads (default 5)
multipart_size=	Multipart chunk size in MB (default 10)
dbglevel=info	Enable debug logging

Caveats

• Not a real POSIX filesystem: no hard links, append writes are expensive (re-upload), no atomic rename
• Performance is limited by S3 latency and FUSE overhead
• Best for read-heavy or write-once workloads