This topic describes how to call the put operation to upload a local file to Object Storage Service (OSS).

Sample code

The following code provides an example on how to upload a local file named examplefile.txt to a bucket named examplebucket. After the local file is uploaded, the name of the object stored in OSS is exampleobject.txt.

const OSS = require('ali-oss')
const path = require("path")

const client = new OSS({
  // Set yourregion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourregion to oss-cn-hangzhou. 
  region: 'yourregion',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the bucket name. 
  bucket: 'examplebucket',

const headers = {
  // Specify the caching behavior of the web page when the object is downloaded. 
  // 'Cache-Control': 'no-cache', 
  // Specify the name of the object when the object is downloaded. 
  // 'Content-Disposition': 'oss_download.txt', 
  // Specify the content encoding format of the object when the object is downloaded. 
  // 'Content-Encoding': 'UTF-8', 
  // Specify the expiration time. 
  // 'Expires': 'Wed, 08 Jul 2022 16:57:01 GMT', 
  // Specify the storage class of the object. 
  // 'x-oss-storage-class': 'Standard', 
  // Specify the access control list (ACL) of the object. 
  // 'x-oss-object-acl': 'private', 
  // Set tags for the object. You can set multiple tags at a time. 
  // 'x-oss-tagging': 'Tag1=1&Tag2=2', 
  // Specify whether the CopyObject operation overwrites the object with the same name. In this example, this parameter is set to true, which indicates that the object with the same name cannot be overwritten. 
  // 'x-oss-forbid-overwrite': 'true', 

async function put () {
  try {
    // Specify the full paths of the object and the local file. The full path of the OSS object cannot contain the bucket name. 
    // If the path of the local file is not specified, the local file is uploaded from the path of the project to which the sample program belongs. 
    const result = await client.put('exampleobject.txt', path.normalize('D:\\localpath\\examplefile.txt'));
    // const result = await client.put('exampleobject.txt', path.normalize('D:\\localpath\\examplefile.txt'), { headers });   
  } catch (e) {



  • For more information about the complete sample code of simple upload, visit GitHub.
  • For more information about the API operation that is called to perform simple upload, see PutObject.