Cloud Storage client library

2 min readMay 19, 2021

This tutorial shows how to get started with the Cloud Storage Python client library.

Create a storage bucket

Buckets are the basic containers that hold your data. Everything that you store in Cloud Storage must be contained in a bucket. You can use buckets to organize your data and control access to your data.

Start by importing the library:

from google.cloud import storage

The storage.Client object uses your default project. Alternatively, you can specify a project in the Client constructor. For more information about how the default project is determined, see the google-auth documentation.

Run the following to create a client with your default project:

client = storage.Client()
print("Client created using default project: {}".format(client.project))

To explicitly specify a project when constructing the client, set the project parameter:

# client = storage.Client(project='your-project-id')

Finally, create a bucket with a globally unique name.

For more information about naming buckets, see Bucket name requirements.

# Replace the string below with a unique name for the new bucket
bucket_name = "your-new-bucket"

# Creates the new bucket
bucket = client.create_bucket(bucket_name)

print("Bucket {} created.".format(bucket.name))

List buckets in a project

buckets = client.list_buckets()

print("Buckets in {}:".format(client.project))
for item in buckets:
    print("\t" + item.name)

Get bucket metadata

The next cell shows how to get information on metadata of your Cloud Storage buckets.

To learn more about specific bucket properties, see Bucket locations and Storage classes.

bucket = client.get_bucket(bucket_name)

print("Bucket name: {}".format(bucket.name))
print("Bucket location: {}".format(bucket.location))
print("Bucket storage class: {}".format(bucket.storage_class))

Upload a local file to a bucket

Objects are the individual pieces of data that you store in Cloud Storage. Objects are referred to as “blobs” in the Python client library. There is no limit on the number of objects that you can create in a bucket.

An object’s name is treated as a piece of object metadata in Cloud Storage. Object names can contain any combination of Unicode characters (UTF-8 encoded) and must be less than 1024 bytes in length.

For more information, including how to rename an object, see the Object name requirements.

blob_name = "us-states.txt"
blob = bucket.blob(blob_name)

source_file_name = "resources/us-states.txt"
blob.upload_from_filename(source_file_name)

print("File uploaded to {}.".format(bucket.name))

List blobs in a bucket

blobs = bucket.list_blobs()

print("Blobs in {}:".format(bucket.name))
for item in blobs:
    print("\t" + item.name)

Get a blob and display metadata

See documentation for more information about object metadata.

blob = bucket.get_blob(blob_name)

print("Name: {}".format(blob.id))
print("Size: {} bytes".format(blob.size))
print("Content type: {}".format(blob.content_type))
print("Public URL: {}".format(blob.public_url))

Download a blob to a local directory

output_file_name = "resources/downloaded-us-states.txt"
blob.download_to_filename(output_file_name)

print("Downloaded blob {} to {}.".format(blob.name, output_file_name))

Cleaning up

Delete a blob

blob = client.get_bucket(bucket_name).get_blob(blob_name)
blob.delete()

print("Blob {} deleted.".format(blob.name))

Delete a bucket

Note that the bucket must be empty before it can be deleted.

bucket = client.get_bucket(bucket_name)
bucket.delete()

print("Bucket {} deleted.".format(bucket.name))

Next Steps

Read more about Cloud Storage in the documentation: