Download an Object From a Google Cloud Storage Bucket in NodeJS

Marco Rapaccini
Geek Culture
Published in
3 min readMar 3, 2021
Photo by Tony Mucci on Unsplash

An overview

Google Cloud Platform (GCP) is the cloud computing services suite from mother Google, a good rival of Amazon Web Services (AWS) and Microsoft Azure.

I’m playing a bit with GCP because I’m working on an interesting FinTech project and the company needs scalability (the magic word!) on a Google-like environment.

Google Cloud Platform comes with easy user interface and fair prices.

But GCP’s documentation has 2 problems:

  • sometime is confusing;
  • it’s not well indexed on Google (yes, you understood correctly — the king of search engines doesn’t index correctly its own documentation).

I had to download some objects in NodeJS from a Google Cloud Storage (the GCP’s storage service) bucket, so I faced some friction and I’d like to help you (and help me, reading this article in the future) with this little guide.

Google Cloud Storage Client Library

In order to download an object from a Google Cloud Storage bucket you need to have the Google Cloud Storage library.

If not done yet, you need to install the Google Cloud Storage Client Library with npm package manager:

npm install @google-cloud/storage


The client authentication is based on a Service Account Key, basically a JSON key.
If you don’t have any key, you can create one following this link .
For more details about the key generation, please see the Google Docs here .

Once you have downloaded the JSON file that contains the Service Account Key, it’s suggested to rename it (e.g. my-service-account-key.json) and to move it to an appropriate folder (a folder unlikely to be renamed or deleted in the future).

Setting the environment variable

The downloaded Service Account Key has to be set as environment variable.

> Linux/MacOS

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/my-service-account-key.json"

> Windows

Remember that Windows Powershell and command prompt use the backslash \ to describe a path.

>> [Option A] Windows Powershell


>> [Option B] Windows command prompt

set GOOGLE_APPLICATION_CREDENTIALS=C:\path\to\my-service-account-key.json

>> [Option C] Windows Subsystem for Linux (WSL)

If you use the WSL, please configure the environment variable in Linux too, or you wouldn’t be able to run the code via Linux CLI (it will work only using the Windows command prompt).

It’s recommended to copy the Service Account Key into the Linux folder /etc/profile.d/.

Then execute the following command to add the environment variable:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/my-service-account-key.json"

Download an object from GCS, a working example

Use the below code to download an object from a Google Cloud Storage bucket, changing the references bucketName, srcFilename and destFilename with the right values.

Note 1: object name

Please note that Google Cloud Storage identifies an object by a name that also contains the path.
So, srcFilename should never start witht the slash / because the Google Cloud Storage Client Library will automatically convert the srcFilename into the object name.

For example, the following srcFilename

const srcFilename = 'path/to/object/to/download/file.format';

will be interpreted by Google Cloud Storage this way

where b identify the bucket name and o the object name.

But if there’s the slash / in front of the srcFilename

const srcFilename = '/path/to/object/to/download/file.format';

then the name will be converted into

leading to an error

404 Error: No such object: bucket-name//path/to/object/to/download/file.format

Note 2: destination folder

If you want to put the downloaded object into a specific folder, remember to create the directory before passing the value to destFilename.

Run the code!

Use the default node command to test the code:

node example-code.js

🙏 Thank you for reading!

🔎 You can find me on Twitter and LinkedIn.



Marco Rapaccini
Geek Culture

Senior Software Engineer ~ Startup Technical Cofounder ~ R&D lover