How to Mount S3 Bucket on Ubuntu with s3fs-fuse

How to Mount S3 Bucket on Ubuntu 22.04 with S3FS Fuse

by

This guide shows you how to mount an S3 bucket on Ubuntu 22.04 using s3fs-fuse. Once mounted, the S3 bucket appears as a regular directory on your filesystem — you can ls, cp, and interact with files as if they were local. This is useful when you need scripts or applications to access S3 files without rewriting them to use the AWS SDK.

Prerequisites

  • An EC2 instance or server running Ubuntu 22.04 — follow How to deploy EC2 Ubuntu 22.04 LTS on AWS if you need one
  • An S3 bucket in your AWS account
  • AWS credentials (Access Key ID and Secret Access Key) or an IAM role attached to your EC2 instance

Install s3fs-fuse

Step 1: Install the s3fs Package

sudo apt update && sudo apt install -y s3fs

Verify it installed:

s3fs --version

Configure AWS Credentials

s3fs needs AWS credentials to access your bucket. You have two options.

Option A: IAM Role (Recommended for EC2)

If you’re running on EC2, attach an IAM role with S3 access to your instance instead of storing credentials in a file. This is more secure — no keys to manage or rotate.

Your IAM role needs a policy with at least these permissions on your bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

When using an IAM role, you’ll add the -o iam_role=auto flag when mounting (shown in Step 3).

Option B: Credentials File

If you’re not on EC2 or can’t use IAM roles, store your credentials in a file. You’ll need an AWS access key pair.

echo "YOUR_ACCESS_KEY_ID:YOUR_SECRET_ACCESS_KEY" > ~/.passwd-s3fs
chmod 600 ~/.passwd-s3fs
  • chmod 600 — restricts the file to owner-only read/write. s3fs will refuse to use it without this permission.

Mount the S3 Bucket

Step 2: Create a Mount Point

sudo mkdir -p /mnt/s3-bucket

Step 3: Mount the Bucket

With a credentials file:

s3fs your-bucket-name /mnt/s3-bucket \
  -o passwd_file=~/.passwd-s3fs \
  -o url=https://s3.ap-southeast-1.amazonaws.com \
  -o allow_other

With an IAM role (EC2):

s3fs your-bucket-name /mnt/s3-bucket \
  -o iam_role=auto \
  -o url=https://s3.ap-southeast-1.amazonaws.com \
  -o allow_other

Replace your-bucket-name with your actual bucket name and ap-southeast-1 with the region where your bucket lives.

  • -o url=... — the S3 endpoint for your bucket’s region. Required for non-us-east-1 buckets.
  • -o allow_other — lets other users on the system access the mount. Requires user_allow_other in /etc/fuse.conf (see troubleshooting).

Step 4: Verify the Mount

Check that the bucket is mounted:

df -h /mnt/s3-bucket

List files in the bucket:

ls /mnt/s3-bucket

Test a write:

echo "test" > /mnt/s3-bucket/test.txt
cat /mnt/s3-bucket/test.txt

Persist the Mount After Reboot

The mount disappears on reboot unless you add it to /etc/fstab.

With a credentials file:

s3fs#your-bucket-name /mnt/s3-bucket fuse _netdev,allow_other,passwd_file=/home/ubuntu/.passwd-s3fs,url=https://s3.ap-southeast-1.amazonaws.com 0 0

With an IAM role:

s3fs#your-bucket-name /mnt/s3-bucket fuse _netdev,allow_other,iam_role=auto,url=https://s3.ap-southeast-1.amazonaws.com 0 0

Add the appropriate line to /etc/fstab. Replace /home/ubuntu with the full path to your credentials file (fstab requires absolute paths — ~ won’t work here).

Test the fstab entry without rebooting:

sudo mount -a

Unmount the Bucket

To unmount:

sudo umount /mnt/s3-bucket

If that fails with “device is busy”, use:

sudo fusermount -u /mnt/s3-bucket

Troubleshooting

“allow_other” Permission Error

If you get an error about allow_other, uncomment the user_allow_other line in /etc/fuse.conf:

sudo sed -i 's/#user_allow_other/user_allow_other/' /etc/fuse.conf

Transport Endpoint Is Not Connected

This usually means the s3fs process crashed. Unmount and remount:

sudo fusermount -u /mnt/s3-bucket
s3fs your-bucket-name /mnt/s3-bucket -o passwd_file=~/.passwd-s3fs -o url=https://s3.ap-southeast-1.amazonaws.com

Slow Performance

s3fs is not a high-performance filesystem — every file operation is an HTTP request to S3. For better read performance on frequently accessed files, enable local caching:

mkdir -p /tmp/s3fs-cache
s3fs your-bucket-name /mnt/s3-bucket \
  -o passwd_file=~/.passwd-s3fs \
  -o url=https://s3.ap-southeast-1.amazonaws.com \
  -o use_cache=/tmp/s3fs-cache

If you need frequent file access with better performance, consider mounting Amazon EFS instead — it’s a proper network filesystem designed for EC2.

Conclusion

Your S3 bucket is now mounted as a local directory. Files you write to the mount point are uploaded to S3, and files in the bucket are accessible locally. Add the fstab entry to keep it mounted across reboots.

If you’re using this for backups, check out How to Automate MySQL Database Backups on EC2 to Amazon S3 for a more automated approach. To move data between S3 buckets in different accounts, see How to Copy S3 Bucket Objects Across AWS Accounts.