Download objects

This page shows you how to download objects from your buckets in Cloud Storage. For a conceptual overview, see Uploads and downloads.

Note: If you use customer-supplied encryption keys with your objects, see Using Customer-Supplied Encryption Keys for downloading instructions.

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

1. In the Google Cloud console, go to the Cloud Storage Browser page.
   

   Go to 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 Download icon associated with the object.

   Your browser settings control the download location for the object.

Note: For some object types, selecting Download opens the object in the browser. To download these objects to your local computer, right-click on Download and select Save Link As....

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

C++

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

The following sample downloads an object to a file:

View on GitHub Feedback

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";
}

The following sample downloads an object into memory:

View on GitHub Feedback

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);
  std::string buffer{std::istream_iterator<char>(stream),
                     std::istream_iterator<char>()};

  std::cout << "The object has " << buffer.size() << " characters\n";
}

C#

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

The following sample downloads an object to a file:

View on GitHub Feedback

using Google.Cloud.Storage.V1;
using System;
using System.IO;

public class DownloadFileSample
{
    public void DownloadFile(
        string bucketName = "your-unique-bucket-name",
        string objectName = "my-file-name",
        string localPath = "my-local-path/my-file-name")
    {
        var storage = StorageClient.Create();
        using var outputFile = File.OpenWrite(localPath);
        storage.DownloadObject(bucketName, objectName, outputFile);
        Console.WriteLine($"Downloaded {objectName} to {localPath}.");
    }
}

The following sample downloads an object into memory:

View on GitHub Feedback

using Google.Cloud.Storage.V1;
using System;
using System.IO;

public class DownloadObjectIntoMemorySample
{
    public Stream DownloadObjectIntoMemory(
        string bucketName = "unique-bucket-name",
        string objectName = "file-name")
    {
        var storage = StorageClient.Create();
        Stream stream = new MemoryStream();
        storage.DownloadObject(bucketName, objectName, stream);

        Console.WriteLine($"The contents of {objectName} from bucket {bucketName} are downloaded");
        return stream;
    }
}

Go

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

The following sample downloads an object to a file:

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"os"
	"time"

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

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

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

	f, err := os.Create(destFileName)
	if err != nil {
		return fmt.Errorf("os.Create: %v", err)
	}

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

	if _, err := io.Copy(f, rc); err != nil {
		return fmt.Errorf("io.Copy: %v", err)
	}

	if err = f.Close(); err != nil {
		return fmt.Errorf("f.Close: %v", err)
	}

	fmt.Fprintf(w, "Blob %v downloaded to local file %v\n", object, destFileName)

	return nil

}

The following sample downloads an object into memory:

View on GitHub Feedback

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

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

// downloadFileIntoMemory downloads an object.
func downloadFileIntoMemory(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.

The following sample downloads an object to a file:

View on GitHub Feedback

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.Paths;

public class DownloadObject {
  public static void downloadObject(
      String projectId, String bucketName, String objectName, String 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
    // String destFilePath = "/local/path/to/file.txt";

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

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

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

The following sample downloads an object into memory:

View on GitHub Feedback

import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.nio.charset.StandardCharsets;

public class DownloadObjectIntoMemory {
  public static void downloadObjectIntoMemory(
      String projectId, String bucketName, String objectName) {
    // 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";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    byte[] content = storage.readAllBytes(bucketName, objectName);
    System.out.println(
        "The contents of "
            + objectName
            + " from bucket name "
            + bucketName
            + " are: "
            + new String(content, StandardCharsets.UTF_8));
  }
}

Node.js

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

The following sample downloads an object to a file:

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// The path to which the file should be downloaded
// const destFileName = '/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 = {
    destination: destFileName,
  };

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

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

downloadFile().catch(console.error);

The following sample downloads an object into memory:

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

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

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

async function downloadIntoMemory() {
  // Downloads the file into a buffer in memory.
  const contents = await storage.bucket(bucketName).file(fileName).download();

  console.log(
    `Contents of gs://${bucketName}/${fileName} are ${contents.toString()}.`
  );
}

downloadIntoMemory().catch(console.error);

PHP

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

The following sample downloads an object to a file:

View on GitHub Feedback

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 Cloud Storage bucket.
 * @param string $objectName The name of your Cloud Storage object.
 * @param string $destination The local destination to save the object.
 */
function download_object($bucketName, $objectName, $destination)
{
    // $bucketName = 'my-bucket';
    // $objectName = 'my-object';
    // $destination = '/path/to/your/file';

    $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)
    );
}

The following sample downloads an object into memory:

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Download an object from Cloud Storage and save into a buffer in memory.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 * @param string $objectName The name of your Cloud Storage object.
 */
function download_object_into_memory(
    string $bucketName,
    string $objectName
): void {
    // $bucketName = 'my-bucket';
    // $objectName = 'my-object';

    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $contents = $object->downloadAsString();
    printf(
        'Downloaded %s from gs://%s/%s' . PHP_EOL,
        $contents,
        $bucketName,
        $objectName
    );
}

Python

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

The following sample downloads an object to a file:

View on GitHub Feedback

from google.cloud import storage


def download_blob(bucket_name, source_blob_name, destination_file_name):
    """Downloads a blob from the bucket."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The ID of your GCS object
    # source_blob_name = "storage-object-name"

    # The path to which the file should be downloaded
    # destination_file_name = "local/path/to/file"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Construct a client side representation of a blob.
    # Note `Bucket.blob` differs from `Bucket.get_blob` as it doesn't retrieve
    # any content from Google Cloud Storage. As we don't need additional data,
    # using `Bucket.blob` is preferred here.
    blob = bucket.blob(source_blob_name)
    blob.download_to_filename(destination_file_name)

    print(
        "Downloaded storage object {} from bucket {} to local file {}.".format(
            source_blob_name, bucket_name, destination_file_name
        )
    )

The following sample downloads an object into memory:

View on GitHub Feedback

from google.cloud import storage


def download_blob_into_memory(bucket_name, blob_name):
    """Downloads a blob into memory."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The ID of your GCS object
    # blob_name = "storage-object-name"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Construct a client side representation of a blob.
    # Note `Bucket.blob` differs from `Bucket.get_blob` as it doesn't retrieve
    # any content from Google Cloud Storage. As we don't need additional data,
    # using `Bucket.blob` is preferred here.
    blob = bucket.blob(blob_name)
    contents = blob.download_as_string()

    print(
        "Downloaded storage object {} from bucket {} as the following string: {}.".format(
            blob_name, bucket_name, contents
        )
    )

Ruby

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

The following sample downloads an object to a file:

View on GitHub Feedback

def download_file bucket_name:, file_name:, local_file_path:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  # The path to which the file should be downloaded
  # local_file_path = "/local/path/to/file.txt"

  require "google/cloud/storage"

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

  file.download local_file_path

  puts "Downloaded #{file.name} to #{local_file_path}"
end

The following sample downloads an object into memory:

View on GitHub Feedback

# The name of the bucket to access
# bucket_name = "my-bucket"

# The name of the remote file to download
# file_name = "file.txt"

require "google/cloud/storage"

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

downloaded = file.download
downloaded.rewind # Optional - not needed on first read
contents = downloaded.read

puts "Contents of storage object #{file.name} in bucket #{bucket_name} are: #{contents}"

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. For instructions, see API authentication.

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 URL-encoded name of the object you are downloading. For example, pets/dog.png, URL-encoded as pets%2Fdog.png.

XML API

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

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 URL-encoded name of the object you are downloading. For example, pets/dog.png, URL-encoded as pets%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

C++

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

View on GitHub Feedback

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

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

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

C#

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

View on GitHub Feedback

using Google.Apis.Storage.v1;
using Google.Cloud.Storage.V1;
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class DownloadByteRangeAsyncSample
{
    public async Task DownloadByteRangeAsync(
        string bucketName = "your-unique-bucket-name",
        string objectName = "my-file-name",
        long firstByte = 0,
        long lastByte = 20,
        string localPath = "my-local-path/my-file-name")
    {
        var storageClient = StorageClient.Create();

        // Create an HTTP request for the media, for a limited byte range.
        StorageService storage = storageClient.Service;
        var uri = new Uri($"{storage.BaseUri}b/{bucketName}/o/{objectName}?alt=media");

        var request = new HttpRequestMessage { RequestUri = uri };
        request.Headers.Range = new RangeHeaderValue(firstByte, lastByte);

        using var outputFile = File.OpenWrite(localPath);
        // Use the HttpClient in the storage object because it supplies
        // all the authentication headers we need.
        var response = await storage.HttpClient.SendAsync(request);
        await response.Content.CopyToAsync(outputFile, null);
        Console.WriteLine($"Downloaded {objectName} to {localPath}.");
    }
}

Go

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

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"os"
	"time"

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

// downloadByteRange downloads a specific byte range of an object to a file.
func downloadByteRange(w io.Writer, bucket, object string, startByte int64, endByte int64, destFileName string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// startByte := 0
	// endByte := 20
	// destFileName := "file.txt"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

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

	f, err := os.Create(destFileName)
	if err != nil {
		return fmt.Errorf("os.Create: %v", err)
	}

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

	if _, err := io.Copy(f, rc); err != nil {
		return fmt.Errorf("io.Copy: %v", err)
	}

	if err = f.Close(); err != nil {
		return fmt.Errorf("f.Close: %v", err)
	}

	fmt.Fprintf(w, "Bytes %v to %v of blob %v downloaded to local file %v\n", startByte, startByte+length, object, destFileName)

	return nil

}

Java

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

View on GitHub Feedback

import com.google.cloud.ReadChannel;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.io.ByteStreams;
import java.io.IOException;
import java.nio.channels.FileChannel;
import java.nio.file.Paths;
import java.nio.file.StandardOpenOption;

public class DownloadByteRange {

  public static void downloadByteRange(
      String projectId,
      String bucketName,
      String blobName,
      long startByte,
      long endBytes,
      String destFileName)
      throws IOException {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

    // The name of the blob/file that you wish to modify permissions on
    // String blobName = "your-blob-name";

    // The starting byte at which to begin the download
    // long startByte = 0;

    // The ending byte at which to end the download
    // long endByte = 20;

    // The path to which the file should be downloaded
    // String destFileName = '/local/path/to/file.txt';

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, blobName);
    try (ReadChannel from = storage.reader(blobId);
        FileChannel to = FileChannel.open(Paths.get(destFileName), StandardOpenOption.WRITE)) {
      from.seek(startByte);
      from.limit(endBytes);

      ByteStreams.copy(from, to);

      System.out.printf(
          "%s downloaded to %s from byte %d to byte %d",
          blobId.toGsUtilUri(), destFileName, startByte, endBytes);
    }
  }
}

Node.js

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

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// The starting byte at which to begin the download
// const startByte = 0;

// The ending byte at which to end the download
// const endByte = 20;

// The path to which the file should be downloaded
// const destFileName = '/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 downloadByteRange() {
  const options = {
    destination: destFileName,
    start: startByte,
    end: endByte,
  };

  // Downloads the file from the starting byte to the ending byte specified in options
  await storage.bucket(bucketName).file(fileName).download(options);

  console.log(
    `gs://${bucketName}/${fileName} downloaded to ${destFileName} from byte ${startByte} to byte ${endByte}.`
  );
}

downloadByteRange();

PHP

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

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Download a byte range from Cloud Storage and save it as a local file.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 * @param string $objectName The name of your Cloud Storage object.
 * @param int $startByte The starting byte at which to begin the download.
 * @param int $endByte The ending byte at which to end the download.
 * @param string $destination The local destination to save the object.
 */
function download_byte_range(
    string $bucketName,
    string $objectName,
    int $startByte,
    int $endByte,
    string $destination
): void {
    // $bucketName = 'my-bucket';
    // $objectName = 'my-object';
    // $startByte = 1;
    // $endByte = 5;
    // $destination = '/path/to/your/file';

    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->downloadToFile($destination, [
        'restOptions' => [
            'headers' => [
                'Range' => "bytes=$startByte-$endByte",
            ],
        ],
    ]);
    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.

View on GitHub Feedback

from google.cloud import storage


def download_byte_range(
    bucket_name, source_blob_name, start_byte, end_byte, destination_file_name
):
    """Downloads a blob from the bucket."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The ID of your GCS object
    # source_blob_name = "storage-object-name"

    # The starting byte at which to begin the download
    # start_byte = 0

    # The ending byte at which to end the download
    # end_byte = 20

    # The path to which the file should be downloaded
    # destination_file_name = "local/path/to/file"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Construct a client side representation of a blob.
    # Note `Bucket.blob` differs from `Bucket.get_blob` as it doesn't retrieve
    # any content from Google Cloud Storage. As we don't need additional data,
    # using `Bucket.blob` is preferred here.
    blob = bucket.blob(source_blob_name)
    blob.download_to_filename(destination_file_name, start=start_byte, end=end_byte)

    print(
        "Downloaded bytes {} to {} of object {} from bucket {} to local file {}.".format(
            start_byte, end_byte, source_blob_name, bucket_name, destination_file_name
        )
    )

Ruby

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

View on GitHub Feedback

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"

# file_name = "Name of a file in the Storage bucket"

# The starting byte at which to begin the download
# start_byte = 0

# The ending byte at which to end the download
# end_byte = 20

# The path to which the file should be downloaded
# local_file_path = "/local/path/to/file.txt"

require "google/cloud/storage"

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

file.download local_file_path, range: start_byte..end_byte

puts "Downloaded bytes #{start_byte} to #{end_byte} of object #{file_name} from bucket #{bucket_name}" \
     + " to local file #{local_file_path}."

REST APIs

JSON API

Use the Range header in your request to download a portion of an object.

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

2. Use cURL to call the JSON API with a GET 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 as pets%2Fdog.png.

Note: If object transcoding occurs, the Range header is silently ignored and the response instead serves the entire requested object.

XML API

Use the Range header in your request to download a portion of an object.

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

2. Use cURL to call the XML API with a GET 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 as pets%2Fdog.png.

Note: If object transcoding occurs, the Range header is silently ignored and the response instead serves the entire requested object.

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