Object naming guidelines

Stay organized with collections Save and categorize content based on your preferences.

This page outlines the naming guidelines you should follow when uploading objects in Cloud Storage. To learn how to upload an object, see the Uploading objects guide.

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 cannot contain Carriage Return or Line Feed characters.
  • Object names cannot start with .well-known/acme-challenge/.
  • Objects cannot be named . or ...

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

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

  • Control characters that are illegal in XML 1.0 (#x7F–#x84 and #x86–#x9F): these characters cause XML listing issues when you try to list your objects.
  • The "#" character: Google Cloud CLI commands interpret 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 the gcloud CLI.
  • The "[", "]", "*", or "?" characters: gcloud storage and gsutil interpret these characters as wildcards, so including them in object names can make it difficult or impossible to perform wildcard operations with those tools.
  • Sensitive or personally identifiable information (PII): object names are more broadly visible than object data. For example, object names appear in URLs for the object and when listing objects in a bucket.

Object name considerations

Object names reside in a flat namespace within a bucket. This means that:

  • Different buckets can have objects with the same name.
  • 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 a result, while deeply nested, directory-like structures using slash delimiters are possible within Cloud Storage, they don't have the performance that a native filesystem has when listing deeply nested sub-directories.

As with buckets, existing objects cannot be directly renamed, but you can indirectly rename an object by copying and deleting the original object.

See Request rate best practices for recommendations on how to optimize performance by avoiding sequential names during large-scale uploads. Objects uploaded with sequential names are likely to hit the same backend server and constrain performance.

What's next