Downloading objects

This page shows you how to download objects from your buckets in Cloud Storage. For an overview of objects, read the Key Terms.

Console

  1. Open the Cloud Storage browser in the Google Cloud Console.
    Open the Cloud Storage browser

  2. 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.

  3. Navigate to the object, which may be located in a folder.

  4. Click the more actions menu () associated with the object.

  5. Select Download.

See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.

gsutil

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

C++

For more information, see the Cloud Storage C++ API reference documentation. 

namespace gcs = google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  gcs::ObjectReadStream stream = client.ReadObject(bucket_name, object_name);

  int count = 0;
  std::string line;
  while (std::getline(stream, line, '\n')) {
    ++count;
  }

  std::cout << "The object has " << count << " lines\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation. 

private void DownloadObject(string bucketName, string objectName,
    string localPath = null)
{
    var storage = StorageClient.Create();
    localPath = localPath ?? Path.GetFileName(objectName);
    using (var outputFile = File.OpenWrite(localPath))
    {
        storage.DownloadObject(bucketName, objectName, outputFile);
    }
    Console.WriteLine($"downloaded {objectName} to {localPath}.");
}

Go

For more information, see the Cloud Storage Go API reference documentation. 

import (
	"context"
	"fmt"
	"io"
	"io/ioutil"
	"time"

	"cloud.google.com/go/storage"
)

// downloadFile downloads an object.
func downloadFile(w io.Writer, bucket, object string) ([]byte, error) {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	rc, err := client.Bucket(bucket).Object(object).NewReader(ctx)
	if err != nil {
		return nil, fmt.Errorf("Object(%q).NewReader: %v", object, err)
	}
	defer rc.Close()

	data, err := ioutil.ReadAll(rc)
	if err != nil {
		return nil, fmt.Errorf("ioutil.ReadAll: %v", err)
	}
	fmt.Fprintf(w, "Blob %v downloaded.\n", object)
	return data, nil
}

Java

For more information, see the Cloud Storage Java API reference documentation. 

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.nio.file.Path;

public class DownloadObject {
  public static void downloadObject(
      String projectId, String bucketName, String objectName, Path destFilePath) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The path to which the file should be downloaded
    // Path destFilePath = Paths.get("/local/path/to/file.txt");

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    Blob blob = storage.get(BlobId.of(bucketName, objectName));
    blob.downloadTo(destFilePath);

    System.out.println(
        "Downloaded object "
            + objectName
            + " from bucket name "
            + bucketName
            + " to "
            + destFilePath);
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const srcFilename = 'Remote file to download, e.g. file.txt';
// const destFilename = 'Local destination for file, e.g. ./local/path/to/file.txt';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function downloadFile() {
  const options = {
    // The path to which the file should be downloaded, e.g. "./file.txt"
    destination: destFilename,
  };

  // Downloads the file
  await storage.bucket(bucketName).file(srcFilename).download(options);

  console.log(
    `gs://${bucketName}/${srcFilename} downloaded to ${destFilename}.`
  );
}

downloadFile().catch(console.error);

PHP

For more information, see the Cloud Storage PHP API reference documentation. 

use Google\Cloud\Storage\StorageClient;

/**
 * Download an object from Cloud Storage and save it as a local file.
 *
 * @param string $bucketName the name of your Google Cloud bucket.
 * @param string $objectName the name of your Google Cloud object.
 * @param string $destination the local destination to save the encrypted object.
 *
 * @return void
 */
function download_object($bucketName, $objectName, $destination)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->downloadToFile($destination);
    printf('Downloaded gs://%s/%s to %s' . PHP_EOL,
        $bucketName, $objectName, basename($destination));
}

Python

For more information, see the Cloud Storage Python API reference documentation. 

from google.cloud import storage


def download_blob(bucket_name, source_blob_name, destination_file_name):
    """Downloads a blob from the bucket."""
    # bucket_name = "your-bucket-name"
    # source_blob_name = "storage-object-name"
    # destination_file_name = "local/path/to/file"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(source_blob_name)
    blob.download_to_filename(destination_file_name)

    print(
        "Blob {} downloaded to {}.".format(
            source_blob_name, destination_file_name
        )
    )

Ruby

For more information, see the Cloud Storage Ruby API reference documentation. 

# bucket_name = "Your Google Cloud Storage bucket name"
# file_name   = "Name of file in Google Cloud Storage to download locally"
# local_path  = "Destination path for downloaded file"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.download local_path

puts "Downloaded #{file.name}"

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

  2. Use cURL to call the JSON API with a GET 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 name of object you are downloading. For example, pets/dog.png. For information about how to URL encode object names to be path safe, see Encoding URI Path Parts.

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

  2. Use cURL to call the XML API with a GET 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 name of object you are downloading. For example, pets/dog.png.

To easily download all objects in a bucket or subdirectory, use the gsutil cp command.

What's next