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 roles

In order to get the required permissions for downloading objects, ask your administrator to grant you the Storage Object Viewer ( roles/storage.objectViewer ) role on the bucket. If you plan on using the Google Cloud console, ask your administrator to grant you the Storage Admin ( roles/storage.admin ) role on the bucket instead.

These roles contain the permissions required to download objects. To see the exact permissions that are required, expand the Required permissionssection:

Required permissions

storage.buckets.list
- This permission is only required for using the Google Cloud console to perform the tasks on this page.
storage.objects.get
storage.objects.list
- This permission is only required for using the Google Cloud console to perform the tasks on this page.

You might also be able to get these permissions with other predefined roles or custom roles .

For instructions on granting roles on buckets, see Set and manage IAM policies on buckets .

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 Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket that contains the object you want to download.

The Bucket detailspage opens, with the Objectstab selected.
Navigate to the object, which may be located in a folder.
Click the Downloadicon 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

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.

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 client libraries .

  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 client libraries .

  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 client libraries .

  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 client libraries .

The following sample downloads an individual object:

  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 
 ) 
  
 throws 
  
 Exception 
  
 { 
  
 // 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"; 
  
  StorageOptions 
 
  
 storageOptions 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (); 
  
 try 
  
 ( 
  Storage 
 
  
 storage 
  
 = 
  
 storageOptions 
 . 
  getService 
 
 ()) 
  
 { 
  
 storage 
 . 
 downloadTo 
 ( 
  BlobId 
 
 . 
 of 
 ( 
 bucketName 
 , 
  
 objectName 
 ), 
  
 Paths 
 . 
 get 
 ( 
 destFilePath 
 )); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
  
 "Downloaded object " 
  
 + 
  
 objectName 
  
 + 
  
 " from bucket name " 
  
 + 
  
 bucketName 
  
 + 
  
 " to " 
  
 + 
  
 destFilePath 
 ); 
  
 } 
  
 } 
 }

The following sample downloads multiple objects using multiple processes:

  import 
  
 com.google.cloud.storage. BlobInfo 
 
 ; 
 import 
  
 com.google.cloud.storage.transfermanager. DownloadResult 
 
 ; 
 import 
  
 com.google.cloud.storage.transfermanager. ParallelDownloadConfig 
 
 ; 
 import 
  
 com.google.cloud.storage.transfermanager. TransferManager 
 
 ; 
 import 
  
 com.google.cloud.storage.transfermanager. TransferManagerConfig 
 
 ; 
 import 
  
 java.nio.file.Path 
 ; 
 import 
  
 java.util.List 
 ; 
 class 
 DownloadMany 
  
 { 
  
 public 
  
 static 
  
 void 
  
 downloadManyBlobs 
 ( 
  
 String 
  
 bucketName 
 , 
  
 List<BlobInfo> 
  
 blobs 
 , 
  
 Path 
  
 destinationDirectory 
 ) 
  
 throws 
  
 Exception 
  
 { 
  
 try 
  
 ( 
  TransferManager 
 
  
 transferManager 
  
 = 
  
  TransferManagerConfig 
 
 . 
 newBuilder 
 (). 
 build 
 (). 
 getService 
 ()) 
  
 { 
  
  ParallelDownloadConfig 
 
  
 parallelDownloadConfig 
  
 = 
  
  ParallelDownloadConfig 
 
 . 
 newBuilder 
 () 
  
 . 
 setBucketName 
 ( 
 bucketName 
 ) 
  
 . 
 setDownloadDirectory 
 ( 
 destinationDirectory 
 ) 
  
 . 
 build 
 (); 
  
 List<DownloadResult> 
  
 results 
  
 = 
  
 transferManager 
 . 
 downloadBlobs 
 ( 
 blobs 
 , 
  
 parallelDownloadConfig 
 ). 
 getDownloadResults 
 (); 
  
 for 
  
 ( 
  DownloadResult 
 
  
 result 
  
 : 
  
 results 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
  
 "Download of " 
  
 + 
  
  result 
 
 . 
 getInput 
 (). 
 getName 
 () 
  
 + 
  
 " completed with status " 
  
 + 
  
  result 
 
 . 
 getStatus 
 ()); 
  
 } 
  
 } 
  
 } 
 }

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

  import 
  
 com.google.cloud.storage. BlobInfo 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 import 
  
 com.google.cloud.storage.transfermanager. DownloadResult 
 
 ; 
 import 
  
 com.google.cloud.storage.transfermanager. ParallelDownloadConfig 
 
 ; 
 import 
  
 com.google.cloud.storage.transfermanager. TransferManager 
 
 ; 
 import 
  
 com.google.cloud.storage.transfermanager. TransferManagerConfig 
 
 ; 
 import 
  
 java.nio.file.Path 
 ; 
 import 
  
 java.util.List 
 ; 
 import 
  
 java.util.stream.Collectors 
 ; 
 class 
 DownloadBucket 
  
 { 
  
 public 
  
 static 
  
 void 
  
 downloadBucketContents 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 , 
  
 Path 
  
 destinationDirectory 
 ) 
  
 { 
  
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
 getService 
 (); 
  
 List<BlobInfo> 
  
 blobs 
  
 = 
  
 storage 
  
 . 
 list 
 ( 
 bucketName 
 ) 
  
 . 
 streamAll 
 () 
  
 . 
 map 
 ( 
 blob 
  
 - 
>  
 blob 
 . 
  asBlobInfo 
 
 ()) 
  
 . 
 collect 
 ( 
 Collectors 
 . 
 toList 
 ()); 
  
  TransferManager 
 
  
 transferManager 
  
 = 
  
  TransferManagerConfig 
 
 . 
 newBuilder 
 (). 
 build 
 (). 
 getService 
 (); 
  
  ParallelDownloadConfig 
 
  
 parallelDownloadConfig 
  
 = 
  
  ParallelDownloadConfig 
 
 . 
 newBuilder 
 () 
  
 . 
 setBucketName 
 ( 
 bucketName 
 ) 
  
 . 
 setDownloadDirectory 
 ( 
 destinationDirectory 
 ) 
  
 . 
 build 
 (); 
  
 List<DownloadResult> 
  
 results 
  
 = 
  
 transferManager 
 . 
  downloadBlobs 
 
 ( 
 blobs 
 , 
  
 parallelDownloadConfig 
 ). 
 getDownloadResults 
 (); 
  
 for 
  
 ( 
  DownloadResult 
 
  
 result 
  
 : 
  
 results 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
  
 "Download of " 
  
 + 
  
  result 
 
 . 
 getInput 
 (). 
 getName 
 () 
  
 + 
  
 " completed with status " 
  
 + 
  
  result 
 
 . 
 getStatus 
 ()); 
  
 } 
  
 } 
 }

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 client libraries .

The following sample downloads an individual object:

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

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

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

  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 client libraries .

The following sample downloads an individual object:

  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:

  def 
  
 download_many_blobs_with_transfer_manager 
 ( 
 bucket_name 
 , 
 blob_names 
 , 
 destination_directory 
 = 
 "" 
 , 
 blob_name_prefix 
 = 
 "" 
 , 
 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 to the name of each blob to form the full path using 
 # pathlib. Relative paths and absolute paths are both accepted. An empty 
 # string means "the current working directory". Note that this parameter 
 # will NOT allow files to escape the destination_directory and will skip 
 # downloads that attempt directory traversal outside of it. 
 # 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 
 , 
 blob_name_prefix 
 = 
 blob_name_prefix 
 , 
 max_workers 
 = 
 workers 
 , 
 ) 
 for 
 name 
 , 
 result 
 in 
 zip 
 ( 
 blob_names 
 , 
 results 
 ): 
 # The results list is either `None`, an exception, or a warning for each blob in 
 # the input list, in order. 
 if 
 isinstance 
 ( 
 result 
 , 
 UserWarning 
 ): 
 print 
 ( 
 "Skipped download for 
 {} 
 due to warning: 
 {} 
 " 
 . 
 format 
 ( 
 name 
 , 
 result 
 )) 
 elif 
 isinstance 
 ( 
 result 
 , 
 Exception 
 ): 
 print 
 ( 
 "Failed to download 
 {} 
 due to exception: 
 {} 
 " 
 . 
 format 
 ( 
 name 
 , 
 result 
 )) 
 else 
 : 
 print 
 ( 
 "Downloaded 
 {} 
 inside 
 {} 
 directory." 
 . 
 format 
 ( 
 name 
 , 
 destination_directory 
 ) 
 )

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

  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 client libraries .

  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

Rust

  use 
  
 google_cloud_storage 
 :: 
 client 
 :: 
 Storage 
 ; 
 use 
  
 tokio 
 :: 
 io 
 :: 
 AsyncWriteExt 
 ; 
 pub 
  
 async 
  
 fn 
  
 sample 
 ( 
  
 client 
 : 
  
& Storage 
 , 
  
 bucket 
 : 
  
& str 
 , 
  
 object 
 : 
  
& str 
 , 
  
 file_path 
 : 
  
& str 
 , 
 ) 
  
 - 
>  
 Result 
< (), 
  
 anyhow 
 :: 
 Error 
>  
 { 
  
 let 
  
 mut 
  
 reader 
  
 = 
  
 client 
  
 . 
 read_object 
 ( 
 format! 
 ( 
 "projects/_/buckets/{bucket}" 
 ), 
  
 object 
 ) 
  
 . 
 send 
 () 
  
 . 
 await 
 ? 
 ; 
  
 let 
  
 mut 
  
 file 
  
 = 
  
 tokio 
 :: 
 fs 
 :: 
 File 
 :: 
 create 
 ( 
 file_path 
 ). 
 await 
 ? 
 ; 
  
 while 
  
 let 
  
 Some 
 ( 
 data 
 ) 
  
 = 
  
 reader 
 . 
 next 
 (). 
 await 
 . 
 transpose 
 () 
 ? 
  
 { 
  
 file 
 . 
 write_all 
 ( 
& data 
 ). 
 await 
 ? 
 ; 
  
 } 
  
 file 
 . 
 flush 
 (). 
 await 
 ? 
 ; 
  
 println! 
 ( 
 "Downloaded {object} in bucket {bucket} to {file_path}." 
 ); 
  
 Ok 
 (()) 
 }

Download objects Stay organized with collections Save and categorize content based on your preferences.

Required roles

Required permissions

Download an object from a bucket

Console

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

REST APIs

JSON API

XML API

Download a portion of an object

Console

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

REST APIs

JSON API

XML API

Read an object without downloading it

Console

Command line

REST APIs

JSON API

XML API

What's next

Try it for yourself

Download objects