Use the restore command to restore Archive, Cold Archive, and Deep Cold Archive OSS objects - Object Storage Service

Use the ossutil restore command to restore Archive, Cold Archive, or Deep Cold Archive objects so they can be accessed. The command submits a restore job to OSS, which thaws the object and makes it readable for a configurable number of days.

Two ways to make archived objects accessible:

Temporary restore (this topic): Run ossutil restore to thaw an object for 1–365 days. The object returns to the frozen state when the period ends.
Permanent migration: Run ossutil cp to copy the object to a non-archive storage class. See Change the storage class of an object.

Prerequisites

Before you begin, make sure you have:

The oss:RestoreObject permission to restore a single object
The oss:RestoreObject and oss:ListObjects permissions to restore objects by directory or in bulk
ossutil 1.7.11 or later (the restore command is not available in earlier versions)

For permission setup, see Attach a custom policy to a RAM user.

For ossutil installation and binary naming rules, see ossutil command reference.

How it works

Restoration time varies by storage class:

Storage class	Real-time access	Restore time	Max restore duration
Archive	Supported (if enabled)	~1 minute	7 days
Cold Archive	Not supported	Hours (varies by tier)	365 days
Deep Cold Archive	Not supported	12–48 hours (varies by tier)	365 days

Restoration times are estimates and may vary based on object size and system load. For billing details, see Restore objects.

Command syntax

ossutil restore oss://bucketname[/prefix] [local_xml_file]
  [--encoding-type <value>]
  [--payer <value>]
  [--version-id <value>]
  [-r, --recursive]
  [-f, --force]
  [--object-file <value>]
  [--snapshot-path <value>]
  [--disable-ignore-error]
  [--retry-times <value>]
  [-j, --job <value>]

Parameter/Option	Description
`bucketname`	The bucket where the object is stored.
`prefix`	A prefix to match object names in the bucket, such as a directory path.
`local_xml_file`	A local XML file specifying restore parameters. Required for Cold Archive and Deep Cold Archive objects. Optional for Archive objects.
`--encoding-type`	The encoding method for the `prefix` value. Valid value: `url`. If not specified, the prefix is not encoded.
`--payer`	Set to `requester` to enable requester-pays mode, where the requester pays for traffic and request fees.
`--version-id`	The version ID of the object to restore. Applies only to versioning-enabled or versioning-suspended buckets.
`-r, --recursive`	Restores all objects whose names match the specified prefix. Without this option, only the specified object is restored.
`-f, --force`	Runs the command without a confirmation prompt.
`--object-file`	A local TXT or XML file listing object names to restore, one per line. If an error occurs for one object, ossutil records the error and continues restoring the remaining objects. Restored objects are not recorded in the report file.
`--snapshot-path`	Generates snapshots only for objects involved in this operation. Skips objects that already have snapshots. Must be used with `-r, --recursive` or `--object-file`.
`--disable-ignore-error`	Stops ignoring errors during batch restoration.
`--retry-times`	Number of retries after a command failure. Default: `10`. Valid values: 1–500.
`-j, --job`	Number of concurrent restore tasks. Default: `3`. Valid values: 1–10000.

Restore Archive objects

OSS takes 1 minute to restore an Archive object. The object cannot be read while restoration is in progress.

Restore duration behavior:

Default restore duration: 1 day
Running restore again on an already-restored object extends the duration by 1 day
Maximum restore duration: 7 days
After the period ends, the object returns to the frozen state

Optionally, create a config.xml file to specify the number of days to keep the object in the restored state:

<RestoreRequest>
    <Days>3</Days>
</RestoreRequest>

Restore a single Archive object

Restore exampleobject.txt in examplebucket and keep it in the restored state for 3 days:

ossutil restore oss://examplebucket/exampleobject.txt config.xml

To restore a specific version of the object:

ossutil restore oss://examplebucket/exampleobject.txt --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3**** config.xml

To list all versions of an object, see ls.

Restore multiple Archive objects

Restore objects in different directories using `--object-file`:

Write the object names to a TXT file, one per line:

   exampleobject1.jpg
   dir1/exampleobject2.png
   dir2/exampleobject3.txt

Set the restore duration in config.xml:

   <RestoreRequest>
       <Days>3</Days>
   </RestoreRequest>

Run the restore command:

   ossutil restore oss://examplebucket --object-file localfile.txt --snapshot-path dir/ config.xml

Restore all objects in a directory using `-r`:

ossutil restore oss://examplebucket/dest -r config.xml

Expected output

A successful restore command outputs the elapsed time:

0.106852(s) elapsed

Restore Cold Archive objects

Important

Restoration time for Cold Archive objects varies with object size.

Before restoring Cold Archive objects, create a config.xml file with the restore duration and retrieval tier:

<RestoreRequest>
    <Days>3</Days>
    <JobParameters>
        <Tier>Bulk</Tier>
    </JobParameters>
</RestoreRequest>

Choose a retrieval tier based on urgency:

Tier	Restore time	When to use
Expedited	Within 1 hour	Urgent access needed
Standard	2–5 hours	Standard recovery timeline
Bulk	5–12 hours	Non-urgent

<Days> valid values: 1–365.

Restore a single Cold Archive object

Restore exampleobject.jpg in examplebucket using the tier and duration specified in config.xml:

ossutil restore oss://examplebucket/exampleobject.jpg config.xml

Restore multiple Cold Archive objects

Restore objects in different directories using `--object-file`:

Write the object names to a TXT file, one per line:

   exampleobject1.jpg
   dir1/exampleobject2.png
   dir2/exampleobject3.txt

Run the restore command:

   ossutil restore oss://examplebucket --object-file localfile.txt --snapshot-path dir/ config.xml

Restore all objects in a directory using `-r`:

ossutil restore oss://examplebucket/dest -r config.xml

Expected output

0.106852(s) elapsed

Restore Deep Cold Archive objects

Important

Restoration time for Deep Cold Archive objects varies with object size.

Before restoring Deep Cold Archive objects, create a config.xml file with the restore duration and retrieval tier:

<RestoreRequest>
    <Days>3</Days>
    <JobParameters>
        <Tier>Standard</Tier>
    </JobParameters>
</RestoreRequest>

Choose a retrieval tier:

Tier	Restore time	When to use
Expedited	Within 12 hours	Faster access needed
Standard	Within 48 hours	Standard recovery timeline

<Days> valid values: 1–365.

Restore a single Deep Cold Archive object

Restore exampleobject.jpg in examplebucket using the tier and duration specified in config.xml:

ossutil restore oss://examplebucket/exampleobject.jpg config.xml

Restore multiple Deep Cold Archive objects

Restore objects in different directories using `--object-file`:

Write the object names to a TXT file, one per line:

   exampleobject1.jpg
   dir1/exampleobject2.png
   dir2/exampleobject3.txt

Run the restore command:

   ossutil restore oss://examplebucket --object-file localfile.txt --snapshot-path dir/ config.xml

Restore all objects in a directory using `-r`:

ossutil restore oss://examplebucket/dest -r config.xml

Expected output

0.106852(s) elapsed

Verify restore status

After running the restore command, use the stat command to check whether the object is in the restored state:

ossutil stat oss://bucketname/objectname

For details, see stat.

Common options

To operate on a bucket in a different region or under a different Alibaba Cloud account, add the -e, -i, and -k options:

ossutil restore oss://testbucket/exampletest.png \
  -e oss-cn-shanghai.aliyuncs.com \
  -i yourAccessKeyID \
  -k yourAccessKeySecret

Option	Description
`-e`	The endpoint of the region where the bucket is located.
`-i`	The AccessKey ID of the target Alibaba Cloud account.
`-k`	The AccessKey secret of the target Alibaba Cloud account.

For all available options, see Common options.

What's next

To keep an object permanently accessible without restoring it each time, copy it to a non-archive storage class. See What do I do to make an object permanently in the restored state?
For restoration process details and billing, see Restore objects.