Download objects

This page shows you how to download objects from your buckets in Cloud Storage to persistent storage. You can also download objects into memory.

Required permissions

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.

Client libraries

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 and require permissions as listed in IAM permissions for JSON methods. To see which JSON API methods are invoked when you make requests using a client library, log the raw requests.

For a list of relevant IAM 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 Buckets page.

    Go to Buckets

  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.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.

Command line

gcloud

Use the gcloud storage cp command:

gcloud storage 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:

Completed files 1/1 | 164.3kiB/164.3kiB

If your download is interrupted prior to completion, run the same cp command to resume the download from where it left off.

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.

If your download is interrupted prior to completion, run the same cp command to resume the download from where it left off.

Client libraries

C++

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

google/cloud/storage/examples/storage_object_samples.cc 
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;
  }
  if (stream.bad()) throw google::cloud::Status(stream.status());

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

C#

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

storage/api/Storage.Samples/DownloadFile.cs 

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

Go

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

storage/objects/download_file.go 
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: %w", 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: %w", err)
	}

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

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

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

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

	return nil

}

Java

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

samples/snippets/src/main/java/com/example/storage/object/DownloadObject.java 

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

Node.js

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

The following sample downloads an individual object:

samples/downloadFile.js 
/**
 * 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 multiple objects using multiple processes:

samples/downloadManyFilesWithTransferManager.js 
/**
 * 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 the first GCS file to download
// const firstFileName = 'your-first-file-name';

// The ID of the second GCS file to download
// const secondFileName = 'your-second-file-name;

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

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

// Creates a transfer manager client
const transferManager = new TransferManager(storage.bucket(bucketName));

async function downloadManyFilesWithTransferManager() {
  // Downloads the files
  await transferManager.downloadManyFiles([firstFileName, secondFileName]);

  for (const fileName of [firstFileName, secondFileName]) {
    console.log(`gs://${bucketName}/${fileName} downloaded to ${fileName}.`);
  }
}

downloadManyFilesWithTransferManager().catch(console.error);

The following sample downloads all objects with a common prefix using multiple processes:

samples/downloadFolderWithTransferManager.js 
/**
 * 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 the GCS folder to download. The folder will be downloaded to the local path of the executing code.
// const folderName = 'your-folder-name';

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

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

// Creates a transfer manager client
const transferManager = new TransferManager(storage.bucket(bucketName));

async function downloadFolderWithTransferManager() {
  // Downloads the folder
  await transferManager.downloadManyFiles(folderName);

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

downloadFolderWithTransferManager().catch(console.error);

PHP

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

The following sample downloads an individual object:

samples/snippets/storage_download_file.py 
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 multiple objects using multiple processes:

samples/snippets/storage_transfer_manager_download_many.py 
def download_many_blobs_with_transfer_manager(
    bucket_name, blob_names, destination_directory="", workers=8
):
    """Download blobs in a list by name, concurrently in a process pool.

    The filename of each blob once downloaded is derived from the blob name and
    the `destination_directory `parameter. For complete control of the filename
    of each blob, use transfer_manager.download_many() instead.

    Directories will be created automatically as needed to accommodate blob
    names that include slashes.
    """

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

    # The list of blob names to download. The names of each blobs will also
    # be the name of each destination file (use transfer_manager.download_many()
    # instead to control each destination file name). If there is a "/" in the
    # blob name, then corresponding directories will be created on download.
    # blob_names = ["myblob", "myblob2"]

    # The directory on your computer to which to download all of the files. This
    # string is prepended (with os.path.join()) to the name of each blob to form
    # the full path. Relative paths and absolute paths are both accepted. An
    # empty string means "the current working directory". Note that this
    # parameter allows accepts directory traversal ("../" etc.) and is not
    # intended for unsanitized end user input.
    # destination_directory = ""

    # The maximum number of processes to use for the operation. The performance
    # impact of this value depends on the use case, but smaller files usually
    # benefit from a higher number of processes. Each additional process occupies
    # some CPU and memory resources until finished. Threads can be used instead
    # of processes by passing `worker_type=transfer_manager.THREAD`.
    # workers=8

    from google.cloud.storage import Client, transfer_manager

    storage_client = Client()
    bucket = storage_client.bucket(bucket_name)

    results = transfer_manager.download_many_to_path(
        bucket, blob_names, destination_directory=destination_directory, max_workers=workers
    )

    for name, result in zip(blob_names, results):
        # The results list is either `None` or an exception for each blob in
        # the input list, in order.

        if isinstance(result, Exception):
            print("Failed to download {} due to exception: {}".format(name, result))
        else:
            print("Downloaded {} to {}.".format(name, destination_directory + name))

The following sample downloads all objects in a bucket using multiple processes:

samples/snippets/storage_transfer_manager_download_bucket.py 
def download_bucket_with_transfer_manager(
    bucket_name, destination_directory="", workers=8, max_results=1000
):
    """Download all of the blobs in a bucket, concurrently in a process pool.

    The filename of each blob once downloaded is derived from the blob name and
    the `destination_directory `parameter. For complete control of the filename
    of each blob, use transfer_manager.download_many() instead.

    Directories will be created automatically as needed, for instance to
    accommodate blob names that include slashes.
    """

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

    # The directory on your computer to which to download all of the files. This
    # string is prepended (with os.path.join()) to the name of each blob to form
    # the full path. Relative paths and absolute paths are both accepted. An
    # empty string means "the current working directory". Note that this
    # parameter allows accepts directory traversal ("../" etc.) and is not
    # intended for unsanitized end user input.
    # destination_directory = ""

    # The maximum number of processes to use for the operation. The performance
    # impact of this value depends on the use case, but smaller files usually
    # benefit from a higher number of processes. Each additional process occupies
    # some CPU and memory resources until finished. Threads can be used instead
    # of processes by passing `worker_type=transfer_manager.THREAD`.
    # workers=8

    # The maximum number of results to fetch from bucket.list_blobs(). This
    # sample code fetches all of the blobs up to max_results and queues them all
    # for download at once. Though they will still be executed in batches up to
    # the processes limit, queueing them all at once can be taxing on system
    # memory if buckets are very large. Adjust max_results as needed for your
    # system environment, or set it to None if you are sure the bucket is not
    # too large to hold in memory easily.
    # max_results=1000

    from google.cloud.storage import Client, transfer_manager

    storage_client = Client()
    bucket = storage_client.bucket(bucket_name)

    blob_names = [blob.name for blob in bucket.list_blobs(max_results=max_results)]

    results = transfer_manager.download_many_to_path(
        bucket, blob_names, destination_directory=destination_directory, max_workers=workers
    )

    for name, result in zip(blob_names, results):
        # The results list is either `None` or an exception for each blob in
        # the input list, in order.

        if isinstance(result, Exception):
            print("Failed to download {} due to exception: {}".format(name, result))
        else:
            print("Downloaded {} to {}.".format(name, destination_directory + name))

Ruby

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

google-cloud-storage/samples/storage_download_file.rb 
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

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 gcloud storage cp command or a client library.

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 the gcloud CLI instead.

Command line

gcloud

gcloud automatically attempts to resume interrupted downloads, except when performing streaming downloads. If your download gets interrupted, a partially downloaded temporary file becomes visible in the destination hierarchy. Run the same cp command to resume the download where it left off.

When the download is complete, the temporary file is deleted and replaced with the downloaded contents. Temporary files are stored in a configurable location, which by default is in the user's home directory under .config/gcloud/surface_data/storage/tracker_files. You can change or view the location that temporary files are stored by running gcloud config get storage/tracker_files_directory.

gsutil

gsutil automatically attempts to resume interrupted downloads, except when performing streaming downloads. If your download gets interrupted, a partially downloaded temporary file becomes visible in the destination directory. Run the same cp command to resume the download where it left off.

When the download is complete, the temporary 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.

Client libraries

C++

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

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;
  }
  if (stream.bad()) throw google::cloud::Status(stream.status());

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

C#

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 


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.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

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: %w", 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: %w", err)
	}

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

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

	if err = f.Close(); err != nil {
		return fmt.Errorf("f.Close: %w", 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.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 


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.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

/**
 * 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.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

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.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param int $startByte The starting byte at which to begin the download.
 *        (e.g. 1)
 * @param int $endByte The ending byte at which to end the download. (e.g. 5)
 * @param string $destination The local destination to save the object.
 *        (e.g. '/path/to/your/file')
 */
function download_byte_range(
    string $bucketName,
    string $objectName,
    int $startByte,
    int $endByte,
    string $destination
): void {
    $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.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

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.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

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

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.

What's next

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