This page shows you how to download objects from your buckets in Cloud Storage. For a conceptual overview, see Uploads and downloads.
Prerequisites
Prerequisites can vary based on the tool used:
Console
In order to complete this guide using the Google Cloud console, you must have the proper IAM permissions. If the bucket you want to download from exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.
For a list of permissions required for specific actions, see IAM permissions for the Google Cloud console.
For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
Command line
In order to complete this guide using a command-line utility, you must have the proper IAM permissions. If the bucket you want to download from exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.
For a list of permissions required for specific actions, see IAM permissions for gsutil commands.
For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
Code samples
In order to complete this guide using the Cloud Storage client libraries, you must have the proper IAM permissions. If the bucket you want to download from exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions. Unless otherwise noted, client library requests are made through the JSON API.
For a list of permissions required for specific actions, see IAM permissions for JSON methods.
For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
REST APIs
JSON API
In order to complete this guide using the JSON API, you must have the proper IAM permissions. If the bucket you want to download from exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.
For a list of permissions required for specific actions, see IAM permissions for JSON methods.
For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
Download an object from a bucket
Complete the following instructions to download an object from a bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Browser page.
In the list of buckets, click on the name of the bucket that contains the object you want to download.
The Bucket details page opens, with the Objects tab selected.
Navigate to the object, which may be located in a folder.
Click the Download icon associated with the object.
Your browser settings control the download location for the object.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
Command line
Use the gsutil cp
command:
gsutil cp gs://BUCKET_NAME/OBJECT_NAME SAVE_TO_LOCATION
Where:
BUCKET_NAME
is the name of the bucket containing the object you are downloading. For example,my-bucket
.OBJECT_NAME
is the name of object you are downloading. For example,pets/dog.png
.SAVE_TO_LOCATION
is the local path where you are saving your object. For example,Desktop/Images
.
If successful, the response looks like the following example:
Operation completed over 1 objects/58.8 KiB.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
The following sample downloads an object to a file: The following sample downloads an object into memory:
For more information, see the
Cloud Storage C# API reference documentation.
The following sample downloads an object to a file: The following sample downloads an object into memory:
For more information, see the
Cloud Storage Go API reference documentation.
The following sample downloads an object to a file: The following sample downloads an object into memory:
For more information, see the
Cloud Storage Java API reference documentation.
The following sample downloads an object to a file: The following sample downloads an object into memory:
For more information, see the
Cloud Storage Node.js API reference documentation.
The following sample downloads an object to a file: The following sample downloads an object into memory:
For more information, see the
Cloud Storage PHP API reference documentation.
The following sample downloads an object to a file: The following sample downloads an object into memory:
For more information, see the
Cloud Storage Python API reference documentation.
The following sample downloads an object to a file: The following sample downloads an object into memory:
For more information, see the
Cloud Storage Ruby API reference documentation.
The following sample downloads an object to a file: The following sample downloads an object into memory:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Use
cURL
to call the JSON API with aGET
Object request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -o "SAVE_TO_LOCATION" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.SAVE_TO_LOCATION
is the path to the location where you want to save your object. For example,Desktop/dog.png
.BUCKET_NAME
is the name of the bucket containing the object you are downloading. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the object you are downloading. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Use
cURL
to call the XML API with aGET
Object request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -o "SAVE_TO_LOCATION" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.SAVE_TO_LOCATION
is the path to the location where you want to save your object. For example,Desktop/dog.png
.BUCKET_NAME
is the name of the bucket containing the object you are downloading. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the object you are downloading. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
To easily download all objects in a bucket or subdirectory, use the
gsutil cp
command.
Download a portion of an object
If your download gets interrupted, you can resume where you left off by requesting only the portion of the object that's left. Complete the following instructions to download a portion of an object.
Console
The Google Cloud console does not support downloading portions of an object. Use gsutil instead.
Command line
gsutil automatically attempts to resume interrupted downloads, except when
performing streaming transfers. If your download gets interrupted, a
partially downloaded temporary file becomes visible in the desintation
directory. Run the same cp
command to resume the download where it
left off.
When the download is complete, the original file is deleted and replaced
with the downloaded contents. Resumable transfers store state information in
files under ~/.gsutil
, named by the destination object or file.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Use the Range
header in your request to download a portion of
an object.
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Use
cURL
to call the JSON API with aGET
Object request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Range: bytes=FIRST_BYTE-LAST_BYTE" \ -o "SAVE_TO_LOCATION" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.FIRST_BYTE
is the first byte in the range of bytes you want to download. For example,1000
.LAST_BYTE
is the last byte in the range of bytes you want to download. For example,1999
.SAVE_TO_LOCATION
is the path to the location where you want to save your object. For example,Desktop/dog.png
.BUCKET_NAME
is the name of the bucket containing the object you are downloading. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the object you are downloading. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
XML API
Use the Range
header in your request to download a portion of
an object.
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Use
cURL
to call the XML API with aGET
Object request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Range: bytes=FIRST_BYTE-LAST_BYTE" \ -o "SAVE_TO_LOCATION" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.FIRST_BYTE
is the first byte in the range of bytes you want to download. For example,1000
.LAST_BYTE
is the last byte in the range of bytes you want to download. For example,1999
.SAVE_TO_LOCATION
is the path to the location where you want to save your object. For example,$HOME/Desktop/dog.png
.BUCKET_NAME
is the name of the bucket containing the object you are downloading. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the object you are downloading. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
What's next
- Read the conceptual overview for uploading and downloading.
- Learn how to perform streamed downloads.
- Transfer data from cloud providers or other online sources (for example, using URL lists).
- Transfer objects to your Compute Engine instance.
- Learn how you can bill Cloud Storage access charges to requesters.
- Learn how Cloud Storage can serve gzipped files in an uncompressed state.
Try it for yourself
If you're new to Google Cloud, create an account to evaluate how Cloud Storage performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Try Cloud Storage free