Bucket and Object Naming Guidelines

This page outlines the naming guidelines you should follow when creating buckets and uploading objects in Cloud Storage. To learn how to create a bucket, see the Creating storage buckets guide.

Bucket name requirements

Your bucket names must meet the following requirements:

  • Bucket names must contain only lowercase letters, numbers, dashes (-), underscores (_), and dots (.). Names containing dots require verification.
  • Bucket names must start and end with a number or letter.
  • Bucket names must contain 3 to 63 characters. Names containing dots can contain up to 222 characters, but each dot-separated component can be no longer than 63 characters.
  • Bucket names cannot be represented as an IP address in dotted-decimal notation (for example, 192.168.5.4).
  • Bucket names cannot begin with the "goog" prefix.
  • Bucket names cannot contain "google" or close misspellings of "google".

Also, for DNS compliance and future compatibility, you should not use underscores (_) or have a period adjacent to another period or dash. For example, ".." or "-." or ".-" are not valid in DNS names.

Bucket name considerations

Bucket names reside in a single Cloud Storage namespace, which means that every bucket name must be unique. If you try to create a bucket with a name that is already assigned to an existing bucket, Cloud Storage responds with an error message. However, once you delete a bucket, its name can be reused by you or another user when creating a new bucket.

A bucket name can only be assigned during creation: you cannot change the name of an existing bucket. Instead, you should create a new bucket with the desired name and move the contents from the old bucket to the new bucket. See the related topic in Managing Buckets for a step-by-step guide.

See also the Naming Best Practices section, which includes recommendations about excluding proprietary information from bucket and object names.

Object name requirements

Your object names must meet the following requirements:

  • Object names can contain any sequence of valid Unicode characters, of length 1-1024 bytes when UTF-8 encoded.
  • Object names must not contain Carriage Return or Line Feed characters.

For more information about Carriage Return and Line Feed characters, see Newline.

It is strongly recommend that you avoid the following in your object names:

  • Avoid using control characters that are illegal in XML 1.0 (#x7F–#x84 and #x86–#x9F): these characters will cause XML listing issues when you try to list your objects.
  • Avoid using "#" in your object names: gsutil interprets object names ending with #<numeric string> as version identifiers, so including "#" in object names can make it difficult or impossible to perform operations on such versioned objects using gsutil (see Object Versioning and Concurrency Control).
  • Avoid using "[", "]", "*", or "?" in your object names: gsutil interprets these characters as wildcards, so including them in object names can make it difficult or impossible to perform wildcard operations using gsutil.

Object name considerations

Object names reside in a flat namespace within a bucket, which means that different buckets can have objects with the same name. It also means that objects do not reside within subdirectories in a bucket. For example, you can name an object /europe/france/paris.jpg to make it appear that paris.jpg resides in the subdirectory /europe/france, but to Cloud Storage, the object simply exists in the bucket and has the name /europe/france/paris.jpg.

As with buckets, existing objects cannot be renamed. Instead, renaming is effectively achieved by copying an object, giving the desired name to the new object, and deleting the old object. This can be done easily with the gsutil mv command, which handles the process automatically. For files (but not folders), renaming can also be easily achieved through the Google Cloud Platform Console, by clicking on the desired file's drop-down menu (which appears as three vertical dots on the far right of the file's line) and clicking move/rename. When using Google Cloud Storage through the JSON and XML APIs, object renames need to be done explicitly by copying, then deleting, the object.

Send feedback about...

Cloud Storage Documentation