Quickstart: Using the gsutil Tool

This page shows you how to perform basic tasks in Cloud Storage using the gsutil command-line tool.

Before you begin

  1. Sign in to your Google account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Cloud Platform Console project.

    Go to the Projects page

  3. Enable billing for your project.

    Enable billing

  4. Install the Cloud SDK.

    When prompted, choose the project that you created or selected above.

  5. Install Python 2.7.

    If you are using Windows, this is done automatically as part of the Cloud SDK installation (if you leave the checkbox selected for installing Python).

Create a bucket

  1. Open a terminal window.
  2. Use the gsutil mb command and a unique name to create a bucket:

    gsutil mb gs://my-awesome-bucket/
    
    This quickstart uses a bucket named "my-awesome-bucket." You will need to choose your own, unique, bucket name.

    If successful, the command returns:

    Creating gs://my-awesome-bucket/...
    
    You've just created a bucket where you can store your stuff!

Upload an object into your bucket

  1. Right-click on the icon the following icon: . Save it somewhere on your computer, such as on the desktop.
  2. Use the gsutil cp command to copy the icon from the location where you saved it to the bucket you created:
    gsutil cp Desktop/cloud-storage-logo.png gs://my-awesome-bucket
    
    If successful, the command returns:
    Copying file://Desktop/cloud-storage-logo.png [Content-Type=image/png]...
    Uploading   gs://my-awesome-bucket/cloud-storage-logo.png:       0 B/2.58 KiB
    Uploading   gs://my-awesome-bucket/cloud-storage-logo.png:       2.58 KiB/2.58 KiB
    
    You've just stored an object in your bucket.

Download an object from your bucket

  1. Use the gsutil cp command to download the icon you stored in your bucket to somewhere on your computer, such as the desktop:
    gsutil cp gs://my-awesome-bucket/cloud-storage-logo.png Desktop
    
    If successful, the command returns:

    Copying gs://my-awesome-bucket/cloud-storage-logo.png...
    Downloading file://Desktop/cloud-storage-logo.png:               0 B/2.58 KiB
    Downloading file://Desktop/cloud-storage-logo.png:               2.58 KiB/2.58 KiB
    
    You've just downloaded something from your bucket.

Copy an object to a folder in the bucket

  1. Use the gsutil cp command to create a folder and copy the icon into it:

    gsutil cp gs://my-awesome-bucket/cloud-storage-logo.png gs://my-awesome-bucket/just-a-folder/
    

    If successful, the command returns:

    Copying gs://my-awesome-bucket/cloud-storage-logo.png [Content-Type=image/png]...
    Copying     ...my-awesome-bucket/just-a-folder/cloud-storage.logo.png: 2.58 KiB/2.58 KiB
    
    You've just copied your object into a new folder in your bucket.

List contents of a bucket or folder

  1. Use the gsutil ls command to list the contents of the bucket:
    gsutil ls gs://my-awesome-bucket
    
    If successful, the command returns a message similar to:
    gs://my-awesome-bucket/cloud-storage-logo.png
    gs://my-awesome-bucket/just-a-folder/
    
    You've just seen the contents of your bucket.

List details for an object

  1. Use the gsutil ls command, with the -l flag to get some details about an object:
    gsutil ls -l gs://my-awesome-bucket/cloud-storage-logo.png
    
    If successful, the command returns a message similar to:
    2638  2016-02-26T23:05:14Z  gs://my-awesome-bucket/cloud-storage-logo.png
    TOTAL: 1 objects, 2638 bytes (2.58 KiB)
    
    You've just obtained information about the object's size and date of creation.

Make your object publicly accessible

  1. Use the gsutil acl ch command to grant all users read permission for the object stored in your bucket:
    gsutil acl ch -u AllUsers:R gs://my-awesome-bucket/cloud-storage-logo.png
    
    If successful, the command returns:

    Updated ACL on gs://my-awesome-bucket/cloud-storage-logo.png
    
    Now anyone can get your object.
  2. To remove this permission, use the command:
    gsutil acl ch -d AllUsers gs://my-awesome-bucket/cloud-storage-logo.png
    
    If successful, the command returns:

    Updated ACL on gs://my-awesome-bucket/cloud-storage-logo.png
    
    You have removed public access to this object.

Give someone access to your bucket

  1. Use the gsutil acl ch command to give a specific email address read and write permission for your bucket:
    gsutil acl ch -u user@gmail.com:W gs://my-awesome-bucket
    
    If successful, the command returns:

    Updated ACL on gs://my-awesome-bucket/
    
    Now someone else can put things into and take things out of your bucket.
  2. To remove this permission, use the command:
    gsutil acl ch -d user@gmail.com gs://my-awesome-bucket
    
    If successful, the command returns:

    Updated ACL on gs://my-awesome-bucket/
    
    You have removed the user's access to this bucket.

Delete objects

  1. Use the gsutil rm command to delete an object:
    gsutil rm gs://my-awesome-bucket/cloud-storage-logo.png
    
    If successful, the command returns:
    Removing gs://my-awesome-bucket/cloud-storage-logo.png...
    
    This copy of the object is no longer stored on Cloud Storage (though the copy you made in the folder just-a-folder/ still exists).

Clean up

To avoid incurring charges to your Google Cloud Platform account for the resources used in this quickstart:

  1. Open a terminal window (if not already open).
  2. Use the gsutil rm command with the -r flag to delete the bucket and anything inside of it:
    gsutil rm -r gs://my-awesome-bucket
    
    If successful, the command returns a message similar to:
    Removing gs://my-awesome-bucket/just-a-folder/cloud-storage.logo.png#1456530077282000...
    Removing gs://my-awesome-bucket/...
    
    Your bucket and its contents are deleted.

What's next

Send feedback about...

Cloud Storage