This page shows you how to upload objects to your Cloud Storage bucket. An uploaded object consists of the data you want to store along with any associated metadata. For a conceptual overview, including how to choose the optimal upload method based on your file size, see Uploads and downloads.
Prerequisites
Prerequisites can vary based on the tool used:
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 upload to 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 upload to 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.
Code samples
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 upload to 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.
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.
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 upload to 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.
Upload an object to a bucket
Complete the following steps to upload an object to a bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Browser page.
In the list of buckets, click on the name of the bucket that you want to upload an object to.
In the Objects tab for the bucket, either:
Drag and drop the desired files from your desktop or file manager to the main pane in the Cloud console.
Click the Upload Files button, select the files you want to upload in the dialog that appears, and click Open.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
Command line
Use the gsutil cp
command:
gsutil cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME/
Where:
OBJECT_LOCATION
is the local path to your object. For example,Desktop/dog.png
.DESTINATION_BUCKET_NAME
is the name of the bucket to which you are uploading your object. For example,my-bucket
.
If successful, the response looks like the following example:
Operation completed over 1 objects/58.8 KiB.
You can set fixed-key and custom object metadata as part of your
object upload in the headers of the request by using the
-h
global option.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
The following sample uploads an object from a file: The following sample uploads an object from memory:
For more information, see the
Cloud Storage C# API reference documentation.
The following sample uploads an object from a file: The following sample uploads an object from memory:
For more information, see the
Cloud Storage Go API reference documentation.
The following sample uploads an object from a file: The following sample uploads an object from memory:
For more information, see the
Cloud Storage Java API reference documentation.
The following sample uploads an object from a file: The following sample uploads an object from memory:
For more information, see the
Cloud Storage Node.js API reference documentation.
The following sample uploads an object from a file: The following sample uploads an object from memory:
For more information, see the
Cloud Storage PHP API reference documentation.
The following sample uploads an object from a file: The following sample uploads an object from memory:
For more information, see the
Cloud Storage Python API reference documentation.
The following sample uploads an object from a file: The following sample uploads an object from memory:
For more information, see the
Cloud Storage Ruby API reference documentation.
The following sample uploads an object from a file: The following sample uploads an object from memory:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Terraform
You can use a Terraform resource to upload an object.
Either content
or source
must be specified (you can also specify both).
REST APIs
JSON API
Single-request upload without object metadata
- 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.
Use
cURL
to call the JSON API with aPOST
Object request:curl -X POST --data-binary @OBJECT_LOCATION \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: OBJECT_CONTENT_TYPE" \ "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=media&name=OBJECT_NAME"
Where:
OBJECT_LOCATION
is the local path to your object. For example,Desktop/dog.png
.OAUTH2_TOKEN
is the access token you generated in Step 1.OBJECT_CONTENT_TYPE
is the content type of the object. For example,image/png
.BUCKET_NAME
is the name of the bucket to which you are uploading your object. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name you want to give your object. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
Single-request upload that includes object metadata
- 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.
Create a
multipart/related
file that contains the following information:--BOUNDARY_STRING Content-Type: application/json; charset=UTF-8 OBJECT_METADATA --BOUNDARY_STRING Content-Type: OBJECT_CONTENT_TYPE OBJECT_DATA --BOUNDARY_STRING--
Where:
BOUNDARY_STRING
is a string you define that identifies the different parts of the multipart file. For example,my-boundary
.OBJECT_METADATA
is metadata you want to include for the file, in JSON format. At a minimum, this section should include aname
attribute for the object, for example{"name": "myObject"}
OBJECT_CONTENT_TYPE
is the content type of the object. For example,image/png
.OBJECT_DATA
is the data for the object.
Use
cURL
to call the JSON API with aPOST
Object request:curl -X POST --data-binary @MULTIPART_FILE_LOCATION \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: multipart/related; boundary=BOUNDARY_STRING" \ -H "Content-Length: MULTIPART_FILE_SIZE" \ "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=multipart"
Where:
MULTIPART_FILE_LOCATION
is the local path to the multipart file you created in step 2. For example,Desktop/my-upload.multipart
.OAUTH2_TOKEN
is the access token you generated in Step 1.BOUNDARY_STRING
is the boundary string you defined in Step 2. For example,my-boundary
.MULTIPART_FILE_SIZE
is the total size, in bytes, of the multipart file you created in Step 2. For example,2000000
.BUCKET_NAME
is the name of the bucket to which you are uploading your object. For example,my-bucket
.
If the request succeeds, the server returns the HTTP 200 OK
status
code along with the file's metadata.
XML API
- 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.
Use
cURL
to call the XML API with aPUT
Object request:curl -X PUT --data-binary @OBJECT_LOCATION \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: OBJECT_CONTENT_TYPE" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
OBJECT_LOCATION
is the local path to your object. For example,Desktop/dog.png
.OAUTH2_TOKEN
is the access token you generated in Step 1.OBJECT_CONTENT_TYPE
is the content type of the object. For example,image/png
.BUCKET_NAME
is the name of the bucket to which you are uploading your object. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name you want to give your object. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
You can set additional object metadata as part of your object upload
in the headers of the request in the same way the above example sets
Content-Type
. When working with the XML API, metadata can only be set at
the time the object is written, such as when uploading, copying, or
replacing the object. For more information, see
Editing object metadata.
What's next
- Read the conceptual overview for uploading and downloading.
- Learn about naming requirements for objects.
- Transfer objects from your Compute Engine instance.
- Transfer data from cloud providers or other online sources (for example, using URL lists).
- Make your data publicly accessible.
- Control who has access to your objects and buckets.
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