All Products
Search

This Product

    Object Storage Service:Install ossutil

    Document Center

    Object Storage Service:Install ossutil

    Last Updated:Dec 17, 2025

    ossutil is a command-line tool for managing objects in Object Storage Service (OSS). Use it for operations such as uploading, downloading, and batch-deleting objects. ossutil supports the following OSs: Windows, Linux, and macOS. Download and install the ossutil version that suits your operating system.

    New version available

    We recommend that you install and use ossutil 2.0. For more information, see Install ossutil.

    Key features of ossutil 2.0:

    • New command categorization: Commands are categorized into API-level commands, such as ossutil api put-bucket-acl, and high-level commands, such as ossutil config.

    • Optimized configuration mechanism: The initial configuration process is simplified. You need only to specify the AccessKey ID, AccessKey secret, and region ID to complete the basic configurations after you install ossutil. You can also specify multiple configuration files by using the --profile parameter, which enhances configuration flexibility.

    • More filter parameters: Various filter conditions based on path, file size, last modified time, and object metadata are provided for batch processing commands, such as ls, cp, and rm, which greatly improves the accuracy and efficiency of operations.

    • Flexible output formats: The --output-format and --output-query parameters are provided. The --output-format parameter sets the output format of output files to JSON, YAML, or XML to better meet different data processing requirements. The --output-query option lets you filter output files to obtain the required information.

    • Enhanced security: To improve security, ossutil 2.0 supports specifying sensitive parameters via environment variables. This prevents exposing credentials in the command line and reduces the risk of leakage. In addition, the --dry-run option allows users to verify command behavior before the commands are run. This option helps prevent unintended operations.

    Versions

    • Latest version: 1.7.19

    • Earlier versions: For more information about the source code and release records of ossutil versions, visit GitHub.

    Download links

    Download link

    SHA-256 checksum

    Linux x86 32bit

    f8a4a7e1df8529b06a3f3cca194a1c99163cb3b8ab3b5d64228c207c3ae63b86

    Linux x86 64bit

    dcc512e4a893e16bbee63bc769339d8e56b21744fd83c8212a9d8baf28767343

    Linux ARM 32bit

    ffe8b479e5fd3c0e146a14cd32e8ef5736d23f6c8de157944288ee09db2d7b1d

    Linux ARM 64bit

    f612c2a88d4d28363e254168d521fac5df632f2547ba84eaebacf6497dc04d57

    macOS 64bit

    9cf82a53fe24d8b5cc3dfb441787e0ea19c24dd7a1246653d5f1a28b7923d6fe

    macOS ARM 64bit

    10ece4d328c5d2440833adc5f4167168e9b2a4c5d364f673b0c45bcc4fd02ec5

    Windows x86 32bit

    772469ef02b91e893f7211acf732c2c07cd93214552ed7cf84157d3d9b9fb799

    Windows x86 64bit

    8e9176aedc87d230ccd97dc7236b16564f2a068609ed301acdc73dc27faf7e77

    Download and install ossutil

    Linux

    1. Run the following command to download and install ossutil: 

      sudo -v ; curl https://gosspublic.alicdn.com/ossutil/install.sh | sudo bash
      Note

      • The ossutil package must be decompressed before it can be installed. Make sure that you have installed an appropriate decompression tool, such as unzip or 7z.

      • By default, ossutil is installed in the /usr/bin/ directory.

    2. Configure ossutil.

      1. Run the following command to configure ossutil: 

        ossutil config

      2. Configure the path of the configuration file as prompted. 

         Please enter the config file name,the file name can include path(default /home/user/.ossutilconfig, carriage return will use the default file. 
 If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

        By default, ossutil saves the configuration file as /home/user/.ossutilconfig. If you specify a different path for the configuration file, add the -c option to specify the configuration file each time you run an ossutil command. For example, if you save the configuration file as /home/config, add the -c option in the following format when you run the ls command:

        ossutil ls oss://examplebucket -c /home/config

      3. Follow the on-screen instructions to specify the display language of ossutil. Enter CH or EN. By default, ossutil is displayed in the language that is used by the OS. The configuration takes effect after you run the config command.

      4. Follow the on-screen instructions to configure the display language of ossutil.

        Enter CH or EN. By default, ossutil is displayed in the language that is used by the operating system. The configuration takes effect after you run the config command.

      5. Follow the on-screen instructions to configure the following parameters: endpoint, accessKeyID, accessKeySecret, and stsToken. The stsToken parameter is only required when using temporary credentials from Security Token Service (STS).

        The following table describes the parameters.

        Parameter

        Required

        Description

        endpoint

        Yes

        Enter the endpoint for your bucket's region. For example, the public endpoint for the Singapore region is https://oss-ap-southeast-1.aliyuncs.com.

        To access OSS from other Alibaba Cloud services in the same region, use the internal endpoint, such as https://oss-ap-southeast-1-internal.aliyuncs.com.

        For a list of regions and endpoints, see Regions and endpoints.

        Important

        Due to a policy change to improve compliance and security, starting March 20, 2025, new OSS users must use a custom domain name (CNAME) to perform data API operations on OSS buckets located in Chinese mainland regions. Default public endpoints are restricted for these operations. Refer to the official announcement for a complete list of the affected operations. If you access your data via HTTPS, you must bind a valid SSL Certificate to your custom domain. This is mandatory for OSS Console access, as the console enforces HTTPS.

        accessKeyID

        Yes

        Provide the AccessKey pair (AccessKey ID and secret) of the RAM user. For information about how to obtain an AccessKey pair, see Create an AccessKey pair for a RAM user.

        Create an AccessKey pair by using ROS

        You can quickly create an AccessKey pair for a RAM user that has full OSS access permissions by using a Resource Orchestration Service (ROS) script. To do so, go to the wizard for template-based stack creation, select I confirm that Alibaba Cloud ROS may create RAM resources in the Security Confirmation section, and click Create.

        1.png

        After the AccessKey pair is created, copy the AccessKey pair on the Outputs tab.

        1.png

        accessKeySecret

        Yes

        stsToken

        No

        This parameter is required only when you use temporary access credentials to access an OSS bucket. If you do not use temporary access credentials to access an OSS bucket, leave this parameter empty. For information about how to generate an STS token, see AssumeRole.

    3. Run the following command to check whether ossutil is installed: 

      ossutil

      If the command displays a list of available ossutil commands, the installation is successful.

    Windows

    1. Install ossutil.

      1. Click the link to the installation package for Windows to download the package.

      2. Decompress the installation package. Then, run the ossutil.bat file.

    2. Configure ossutil.

      1. Run the following command to configure ossutil: 

        ossutil config

      2. Configure the path of the configuration file. 

        Please enter the config file name,the file name can include path(default C:\\Users\user\.ossutilconfig, carriage return will use the default file. 
If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

        By default, ossutil saves the configuration file as C:\\Users\user\.ossutilconfig. If you specify the path of the configuration file, add the -c option to specify the configuration file each time you run an ossutil command. For example, if you save the configuration file as c:\ossutil\config, add the -c option in the following format when you run the ls command:

        ossutil ls oss://examplebucket -c c:\ossutil\config

      3. Follow the on-screen instructions to specify the display language of ossutil. Enter EN. By default, ossutil is displayed in the language that is used by the OS. The configuration takes effect after you run the config command.

      4. Follow the on-screen instructions to configure the following parameters: endpoint, accessKeyID, accessKeySecret, and stsToken. The stsToken parameter is only required when using temporary credentials from Security Token Service (STS).

        The following table describes the parameters.

        Parameter

        Required

        Description

        endpoint

        Yes

        Enter the endpoint for your bucket's region. For example, the public endpoint for the Singapore region is https://oss-ap-southeast-1.aliyuncs.com.

        To access OSS from other Alibaba Cloud services in the same region, use the internal endpoint, such as https://oss-ap-southeast-1-internal.aliyuncs.com.

        For a list of regions and endpoints, see Regions and endpoints.

        Important

        Due to a policy change to improve compliance and security, starting March 20, 2025, new OSS users must use a custom domain name (CNAME) to perform data API operations on OSS buckets located in Chinese mainland regions. Default public endpoints are restricted for these operations. Refer to the official announcement for a complete list of the affected operations. If you access your data via HTTPS, you must bind a valid SSL Certificate to your custom domain. This is mandatory for OSS Console access, as the console enforces HTTPS.

        accessKeyID

        Yes

        Provide the AccessKey pair (AccessKey ID and secret) of the RAM user. For information about how to obtain an AccessKey pair, see Create an AccessKey pair for a RAM user.

        Create an AccessKey pair by using ROS

        You can quickly create an AccessKey pair for a RAM user that has full OSS access permissions by using a Resource Orchestration Service (ROS) script. To do so, go to the wizard for template-based stack creation, select I confirm that Alibaba Cloud ROS may create RAM resources in the Security Confirmation section, and click Create.

        1.png

        After the AccessKey pair is created, copy the AccessKey pair on the Outputs tab.

        1.png

        accessKeySecret

        Yes

        stsToken

        No

        This parameter is required only when you use temporary access credentials to access an OSS bucket. If you do not use temporary access credentials to access an OSS bucket, leave this parameter empty. For information about how to generate an STS token, see AssumeRole.

    3. Run the following command to check whether ossutil is installed: 

      ossutil

      If the command displays a list of available ossutil commands, the installation is successful.

    macOS

    1. Run the following command to download and install ossutil: 

      sudo -v ; curl https://gosspublic.alicdn.com/ossutil/install.sh | sudo bash
      Note

      By default, ossutil is installed in the /usr/local/bin directory.

    2. Configure ossutil.

      1. Run the following command to configure ossutil: 

        ossutil config

      2. Configure the path of the configuration file. 

        Please enter the config file name,the file name can include path(default /Users/user/.ossutilconfig, carriage return will use the default file. 
If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

        By default, ossutil saves the configuration file as /Users/user/.ossutilconfig.

        If you specify a different configuration file, you must add the -c option to specify the configuration file every time you run an ossutil command. For example, if you save the configuration file as /home/config, add the -c option in the following format when you run the ls command:

        ossutil ls oss://examplebucket -c /home/config

      3. Follow the on-screen instructions to specify the display language of ossutil. Enter CH or EN. By default, ossutil is displayed in the language that is used by the OS. The configuration takes effect after you run the config command.

      4. Follow the on-screen instructions to configure the following parameters: endpoint, accessKeyID, accessKeySecret, and stsToken. The stsToken parameter is only required when using temporary credentials from Security Token Service (STS).

        The following table describes the parameters.

        Parameter

        Required

        Description

        endpoint

        Yes

        Enter the endpoint for your bucket's region. For example, the public endpoint for the Singapore region is https://oss-ap-southeast-1.aliyuncs.com.

        To access OSS from other Alibaba Cloud services in the same region, use the internal endpoint, such as https://oss-ap-southeast-1-internal.aliyuncs.com.

        For a list of regions and endpoints, see Regions and endpoints.

        Important

        Due to a policy change to improve compliance and security, starting March 20, 2025, new OSS users must use a custom domain name (CNAME) to perform data API operations on OSS buckets located in Chinese mainland regions. Default public endpoints are restricted for these operations. Refer to the official announcement for a complete list of the affected operations. If you access your data via HTTPS, you must bind a valid SSL Certificate to your custom domain. This is mandatory for OSS Console access, as the console enforces HTTPS.

        accessKeyID

        Yes

        Provide the AccessKey pair (AccessKey ID and secret) of the RAM user. For information about how to obtain an AccessKey pair, see Create an AccessKey pair for a RAM user.

        Create an AccessKey pair by using ROS

        You can quickly create an AccessKey pair for a RAM user that has full OSS access permissions by using a Resource Orchestration Service (ROS) script. To do so, go to the wizard for template-based stack creation, select I confirm that Alibaba Cloud ROS may create RAM resources in the Security Confirmation section, and click Create.

        1.png

        After the AccessKey pair is created, copy the AccessKey pair on the Outputs tab.

        1.png

        accessKeySecret

        Yes

        stsToken

        No

        This parameter is required only when you use temporary access credentials to access an OSS bucket. If you do not use temporary access credentials to access an OSS bucket, leave this parameter empty. For information about how to generate an STS token, see AssumeRole.

    3. Run the following command to check whether ossutil is installed: 

      ossutil

      If the command displays a list of available ossutil commands, the installation is successful.

    References

    After ossutil is installed, use it to upload objects, download objects, copy objects, delete objects, and perform other operations. For more information, see cp (upload objects), cp (download objects), cp (copy objects), and rm (delete objects).