All Products
Document Center

Object Storage Service:Use ossfs to mount an OSS bucket to a local directory on a Linux system

Last Updated:May 15, 2024

ossfs allows you to mount an Object Storage Service (OSS) bucket to a local directory on a Linux system. This way, your application can access resources in the bucket in the same manner as local resources. The mount feature facilitates resource sharing.


The performance and functionality of ossfs are not as good as those of local file systems because data must be synchronized to the cloud over networks. If your application requires high I/O, we recommend that you use Cloud Storage Gateway (CSG). For more information, see What is CSG?

How it works

s3fs is a Filesystem in Userspace (FUSE) based file system that allows you to mount an Amazon S3 bucket to a local file system. ossfs is built based on s3fs and incorporates all s3fs features, including:

  • Support for most features described in Portable Operating System Interface (POSIX) standards, such as file and directory uploads and downloads, and user permissions.

  • Multipart upload and resumable upload for data uploading by default.

  • MD5 verification for data integrity checks.

Runtime environment

ossfs is a FUSE-based file system and works only on FUSE-compatible machines. ossfs provides installer packages for the following systems. To run ossfs in other environments, you need to use the source code to build the required program.

  • Linux

    • CentOS 7.0 or later

    • Ubuntu 14.04 or later

    • Anolis7 or later

  • FUSE

    • FUSE 2.8.4 or later


      You can check your FUSE version by running the following command:

      fusermount -V

      If fusermount version: 2.9.2 is returned, the version of FUSE meets the requirements.


ossfs maps a bucket to a local file system. The following limits apply to ossfs:

  • ossfs is not suitable for scenarios that require highly concurrent read and write operations.

    • Both read and write operations consume the disk capacity. In highly concurrent read/write scenarios, disk performance limits read and write operations.

    • Concurrent read and write requests compete for resources, which affects the bandwidth.

  • ossfs does not support hard links.

  • You cannot access unrestored Cold Archive objects, unrestored Deep Cold Archive objects, or unrestored Archive objects in a bucket for which real-time access of Archive objects is disabled.

  • If a bucket is mounted to multiple clients and data is simultaneously written to the mount points, ossfs does not guarantee consistency.

Use ossfs

The following commands are run as the ecs-user user. To run the commands as the root user, remove sudo from the commands.

Download ossfs

The following table provides download links to ossfs installer packages for commonly used Linux distributions. If you want to use ossfs on a different distribution, source code compiling is required. For more information about the URL of the source code and how to compile the source code, visit GitHub.

Linux distribution

Download link

Ubuntu 22.04 (x64)


Ubuntu 20.04 (x64)


Ubuntu 18.04 (x64)


Ubuntu 16.04 (x64)


Ubuntu 14.04 (x64)


CentOS 8.0 (x64)


CentOS 7.0 (x64)


Anolis8/Alibaba Cloud Linux 3


Anolis7/Alibaba Cloud Linux 2


Install and configure ossfs

  1. Install ossfs.

    • Ubuntu

      Run the following command to install ossfs in Ubuntu 16.04 (x64):

      sudo wget
      sudo apt-get update
      sudo apt-get install gdebi-core
      sudo gdebi ossfs_1.91.2_ubuntu16.04_amd64.deb
    • CentOS/Anolis

      Run the following command to install ossfs in CentOS 7.0 (x64):

      sudo wget
      sudo yum install ossfs_1.91.2_centos7.0_x86_64.rpm

      If your client uses Yellowdog Updater, Modified (YUM) to install the RPM package, dependencies may fail to be downloaded by using YUM when the client node network environment is not compatible. To resolve this issue, you can use YUM to download the dependencies over the normal network to a node that runs the same operating system version, and then copy the dependencies to the required node. For example, ossfs runs on FUSE 2.8.4 or later. Run the following command to download the latest version of FUSE from the YUM source to your local device:

      sudo yum install --downloadonly --downloaddir=./ fuse

      To download other dependencies, replace fuse with the name of the required package.

  2. Add the mime.types file if you want Content-Type and file name extension of the uploaded object match.

    If you do not add the mime.types file, OSS sets Content-Type of the uploaded object to application/octet-stream by default.

    The following examples show how to add the mime.types file.

    • Ubuntu

      Run the following command to add the mime.types file:

      sudo apt-get install mime-support
    • CentOS/Anolis

      Run the following command to add the mime.types file:

      sudo yum install mailcap
  3. Check the FUSE version.

    fusermount -V

    If fusermount version: 2.9.2 is returned, the version of FUSE meets the requirements.

Mount a bucket and access data in the bucket

  1. Select the bucket that you want to mount to the local file system.

    • We recommend that you do not mount an Infrequent Access (IA) bucket or a bucket for which real-time access of Archive objects is enabled. This is because object upload to such a bucket from the local directory may initiate two upload requests. The first request creates a 0-byte object and the second request uploads actual data to create the object in the bucket.

      You are charged a 30-day storage fee of 64 KB for the 0-byte object based on the IA or Archive storage class. This causes additional storage costs.

  2. Configure account information that is used to access your bucket.

    Write the following information to the /etc/passwd-ossfs file: the bucket name and the AccessKey pair (AccessKey ID and AccessKey secret) of the RAM user that has access permissions on the bucket. Then, set the permissions of the file to 640.

    sudo sh -c 'echo <BucketName>:<yourAccessKeyId>:<yourAccessKeySecret> > /etc/passwd-ossfs'
    ### Run the following command if you use a root user role:###
    # echo <BucketName>:<yourAccessKeyId>:<yourAccessKeySecret> > /etc/passwd-ossfs
    sudo chmod 640 /etc/passwd-ossfs

    Replace BucketName, yourAccessKeyId, and yourAccessKeySecret with your actual bucket name, AccessKey ID, and AccessKey secret. Example:

    sudo sh -c 'echo bucket-test:LTAIbZcdVCmQ****:MOk8x0y9hxQ31coh7A5e2MZEUz**** > /etc/passwd-ossfs'
    sudo chmod 640 /etc/passwd-ossfs
  3. Mount the bucket to the specified directory.

    sudo ossfs <BucketName> <mountfolder> -o url=<Endpoint>

    Run the following command to mount a bucket named bucket-test in the China (Hangzhou) region to the /tmp/ossfs directory:

    sudo mkdir /tmp/ossfs
    sudo ossfs bucket-test /tmp/ossfs -o url=

    If you use ossfs on an Elastic Compute Service (ECS) instance and the bucket that you want to mount resides in the same region as the ECS instance, you can use the internal endpoint of OSS for the region. For example, you can change the endpoint of OSS to in this example to reduce traffic costs. For more information about the internal endpoints of OSS, see Regions and endpoints.

  4. Read objects in the bucket from the local file system.

    1. Query the list of objects in the bucket.

      sudo ls -lh /tmp/ossfs



      Metadata-related operations, such as list directory, involve remote access to OSS and have a specific level of latency.

    2. Copy objects.

      sudo cp /tmp/ossfs/bird.jpeg /root

      The preceding command copies the bird.jpeg object to the /root directory.

    3. Upload an object to the bucket.

      sudo cp /root/forest.jpeg /tmp/ossfs

      The preceding command adds the forest.jpeg file to the local directory to which the bucket is mounted.



      If the upload is interrupted and never resumed, the uploaded portion of the object is stored in the bucket as parts. To prevent additional storage fees, we recommend that you use one of the following methods to delete these parts that you no longer need:

  5. If you no longer want to mount the bucket, you can unmount the bucket.

    sudo fusermount -u /tmp/ossfs


  • For more information about ossfs mount configurations, see Advanced configurations.

  • For more information about options in ossfs commands, see Common options.

  • For a list of commonly asked questions about ossfs, see FAQ.