How to Upload Files to Google Cloud Storage Using gcloud and gsutil

The basics in plain English

Before diving into commands, here is the core model you need to understand:

• A bucket is the container that holds your files. Think of it as a top-level folder with a globally unique name. Buckets are explained in detail in the Storage Buckets Explained guide.

• An object is any file stored inside a bucket. Objects do not have a real directory structure, just a flat name that can contain slashes (like reports/2026/summary.pdf) to simulate folders.

• cp copies a file from one location to another. The source and destination can be local paths or gs:// bucket paths.

• rsync keeps a source and destination in sync by transferring only what has changed. It is efficient for repeated deployments where most files stay the same.

• gcloud storage is the modern CLI for Cloud Storage, built into the gcloud CLI you already use for other GCP services.

• gsutil is the older standalone CLI. It still works but is no longer actively developed. You will encounter it constantly in existing code and tutorials.

gcloud storage vs gsutil

Both tools do the same job. The difference is age and direction of travel.

Commands map directly between the two tools. gsutil cp becomes gcloud storage cp. gsutil ls becomes gcloud storage ls. Flag names occasionally differ: for example, gsutil cp -r versus gcloud storage cp —recursive.

You will see gsutil in a large proportion of existing tutorials and Stack Overflow answers. Knowing the equivalent gcloud storage command is straightforward once you understand the pattern.

How uploading files to Cloud Storage works

When you run a cp command, you specify a source path and a destination path. The destination is always a gs:// URL:

gcloud storage cp ./report.pdf gs://my-bucket/reports/report.pdf
#                 ^source       ^destination bucket   ^object name

Key things to understand before you start:

• Object names are flat. Cloud Storage does not have real directories. The slash in reports/report.pdf is part of the object name, not a directory structure. It behaves like a folder in the console and most tools, but it is just a naming convention.

• Overwriting is silent. If an object with the same name already exists, uploading replaces it without any warning or confirmation prompt. If you need to recover overwritten objects, enable versioning on the bucket before you need it.

• Recursive uploads require a flag. Uploading a directory does not happen automatically. You must pass —recursive (gcloud) or -r (gsutil). Without this flag, the command will error or skip the directory.

• Authentication is implicit. Commands use the credentials from gcloud auth login or a service account configured in the environment. If a command fails with a permission error, check your IAM permissions on the bucket.

• Syncing vs copying. cp transfers files unconditionally. rsync compares source and destination and only transfers what has changed. For large deployments where most files are unchanged, rsync is considerably faster.

Common upload and download tasks

# Upload a single file
gcloud storage cp ./report.pdf gs://my-app-data/reports/report.pdf
# gsutil equivalent
gsutil cp ./report.pdf gs://my-app-data/reports/report.pdf

# Upload an entire local directory recursively
gcloud storage cp --recursive ./dist/ gs://my-app-assets/
# gsutil equivalent
gsutil cp -r ./dist/ gs://my-app-assets/

# Upload a large file using parallel composite uploads
gcloud storage cp --parallel-composite-upload-threshold=150M \
  ./large-dataset.tar.gz gs://my-app-data/

# Download a single file
gcloud storage cp gs://my-app-data/reports/report.pdf ./downloaded-report.pdf

# Download an entire prefix (simulated folder) from a bucket
gcloud storage cp --recursive gs://my-app-assets/ ./local-assets/

# List all objects in a bucket
gcloud storage ls gs://my-app-data/

# List with details (size and date)
gcloud storage ls -l gs://my-app-data/reports/

# List all objects recursively under a prefix
gcloud storage ls --recursive gs://my-app-data/reports/

# Copy an object within the same bucket (for renaming or reorganising)
gcloud storage cp \
  gs://my-app-data/old-name.txt \
  gs://my-app-data/new-name.txt

# Copy an object to a different bucket
gcloud storage cp \
  gs://source-bucket/data.json \
  gs://destination-bucket/archive/data.json

# Copy all objects under a prefix to another bucket
gcloud storage cp --recursive \
  gs://source-bucket/exports/ \
  gs://archive-bucket/2026/exports/

# Move an object using gcloud storage (two steps)
gcloud storage cp gs://my-bucket/old-path/file.csv gs://my-bucket/new-path/file.csv
gcloud storage rm gs://my-bucket/old-path/file.csv

# Move using gsutil (one step)
gsutil mv gs://my-bucket/old-path/file.csv gs://my-bucket/new-path/file.csv

cp vs rsync: which one to use

Both commands move files to Cloud Storage but behave differently when the destination already contains files.

# Sync a local directory to a bucket (upload new and changed files only)
gcloud storage rsync ./dist/ gs://my-app-assets/

# Sync with deletion: also remove destination objects not present in the source
# Verify your source is complete before adding this flag
gcloud storage rsync --delete-unmatched-destination-objects \
  ./dist/ gs://my-app-assets/

# Sync two buckets
gcloud storage rsync gs://source-bucket/ gs://destination-bucket/

# gsutil equivalents
gsutil rsync -r ./dist/ gs://my-app-assets/
gsutil rsync -r -d ./dist/ gs://my-app-assets/  # -d deletes unmatched destination objects

Deleting objects and buckets

Deletion in Cloud Storage is immediate and permanent on non-versioned buckets. Be specific with your paths.

# Delete a single object
gcloud storage rm gs://my-app-data/temp/scratch.log

# Delete all objects under a prefix
gcloud storage rm --recursive gs://my-app-data/temp/

# Delete a bucket and all its contents
gcloud storage rm --recursive gs://my-app-data/**
gcloud storage buckets delete gs://my-app-data

# gsutil: delete bucket and all contents in one command
gsutil rm -r gs://my-app-data

# Delete all versions of an object in a versioned bucket
gcloud storage rm --all-versions gs://my-app-data/config.json

When to use CLI uploads

CLI uploads are the right choice when you have GCP credentials in your environment and need to move files directly. Common scenarios:

• Deploying a static website. Build your site locally or in CI, then run rsync to push the output to a Cloud Storage bucket configured for static hosting. Only changed files are transferred on subsequent deploys. The storage class you choose affects how you are billed for access to those assets.

• Uploading reports or data exports. A script that generates a report or data export can use cp to push the output to a known bucket path immediately after generation.

• Archiving and backing up files. Copy files from a server or local machine to Cloud Storage as part of a backup routine. Pair with object lifecycle management to automatically move old backups to cheaper storage classes over time.

• Moving data between buckets. Use cp —recursive to copy a prefix from one bucket to another, for example when migrating data to a new region or separating environments.

• CI/CD pipelines. After a successful build, upload artefacts to Cloud Storage for distribution or downstream consumption. This is a common pattern across GCP deployment workflows.

If you need external users or services to upload directly without GCP credentials, CLI uploads are the wrong tool. Use signed URLs instead. Signed URLs grant temporary, scoped access to a specific object without requiring any GCP account.

Setting metadata and content type

Cloud Storage uses object metadata to tell browsers and CDNs how to handle served files. If you are hosting a static website or serving assets through a CDN, getting these right matters.

Without an explicit Content-Type, served files may be treated as application/octet-stream. Browsers will download them rather than render them. Cloud Storage attempts to infer content type from the file extension, but inference is not always correct, particularly for less common file types.

# Upload with an explicit content type
gcloud storage cp ./index.html gs://my-static-site/ \
  --content-type=text/html

# Upload with a custom cache-control header (gsutil)
gsutil -h "Cache-Control:public,max-age=3600" \
  cp ./logo.png gs://my-static-site/images/logo.png

# Update metadata on an existing object (gsutil)
gsutil setmeta -h "Content-Type:application/json" \
  gs://my-app-data/config.json

# View object metadata
gcloud storage objects describe gs://my-app-data/config.json

Access controls for serving assets publicly are covered in the Cloud Storage IAM vs ACLs guide, and broader data protection in the Cloud Storage Security guide.