Command Palette

Search for a command to run...

GitHubGitHub

Google Cloud CLI Installation Guide

Install the Google Cloud CLI 590 on Linux, macOS and Windows, authenticate with IAM, manage configurations and automate Google Cloud with gcloud.

The Google Cloud CLI (gcloud) is the command-line tool for Google Cloud. It manages resources, configures authentication and installs the companion tools you need.

System Requirements

  • A 64-bit operating system: Linux, macOS or Windows
  • Python 3.10 to 3.15 (the Linux x86_64 package bundles its own interpreter)
  • A Google Cloud project and an account with access to it
  • curl, tar and unzip for the manual installation

Installation Instructions

Ubuntu / Debian (apt)

# Install the signing key in a keyring
sudo mkdir -p -m 755 /usr/share/keyrings
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
sudo chmod a+r /usr/share/keyrings/cloud.google.gpg
 
# Add the Cloud SDK repository
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
  | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
 
# Install
sudo apt update
sudo apt install -y google-cloud-cli
 
# Initialize
gcloud init
 
# Verify
gcloud --version

Verifying the Installation

# Version and components
gcloud --version
 
# The active configuration
gcloud info
 
# The projects you can reach
gcloud projects list

Authentication

# Interactive login — opens a browser
gcloud init
 
# Log in again without re-running init
gcloud auth login
 
# Use a device code on a headless machine
gcloud auth login --no-launch-browser

Application Default Credentials

Every Google Cloud client library and every tool that talks to the API uses ADC:

# Create the ADC file for local development
gcloud auth application-default login
 
# Check what ADC currently points at
gcloud auth application-default print-access-token

Service accounts and impersonation

# Create a service account
gcloud iam service-accounts create my-sa \
  --display-name "My Service Account"
 
# Grant it the least privilege it needs
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:my-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/viewer"
 
# Impersonate it instead of downloading a key
gcloud auth application-default login \
  --impersonate-service-account=my-sa@PROJECT_ID.iam.gserviceaccount.com

Configurations

A configuration is a named set of properties (account, project, region, zone):

# Create one
gcloud config configurations create my-config
 
# List them
gcloud config configurations list
 
# Switch to one
gcloud config configurations activate my-config
 
# See the active properties
gcloud config list
 
# Set properties
gcloud config set project PROJECT_ID
gcloud config set compute/region europe-west4
gcloud config set compute/zone europe-west4-a
# ~/.config/gcloud/configurations/config_my-config
[core]
account = user@example.com
project = my-project-id
disable_usage_reporting = True
 
[compute]
zone = europe-west4-a
region = europe-west4

Everyday Commands

Compute Engine

# List instances
gcloud compute instances list
 
# Create an instance
gcloud compute instances create my-instance \
  --machine-type=e2-medium \
  --image-family=ubuntu-2404-lts-amd64 \
  --image-project=ubuntu-os-cloud \
  --zone=europe-west4-a
 
# SSH into it
gcloud compute ssh my-instance --zone=europe-west4-a
 
# Stop and delete
gcloud compute instances stop my-instance --zone=europe-west4-a
gcloud compute instances delete my-instance --zone=europe-west4-a

Cloud Storage

# Use gcloud storage — gsutil is the legacy tool
gcloud storage buckets create gs://my-bucket --location=EU
 
# List buckets
gcloud storage ls
 
# Copy files
gcloud storage cp ./file.txt gs://my-bucket/
gcloud storage rs --recursive ./local-dir gs://my-bucket/dir/
 
# IAM on a bucket
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="user:john@example.com" \
  --role="roles/storage.objectViewer"

Kubernetes Engine

# Install the auth plugin for GKE (a separate package when installed with apt)
sudo apt install -y google-cloud-cli-gke-gcloud-auth-plugin
 
# Get the credentials for a cluster
gcloud container clusters get-credentials my-cluster --region=europe-west4
 
# Then use kubectl
kubectl get nodes

Components and Extra Tools

# With a tarball or Homebrew installation you can manage components
gcloud components list
gcloud components install kubectl
gcloud components update
# With apt or rpm, install the matching package instead
sudo apt install -y google-cloud-cli-kubectl
sudo apt install -y google-cloud-cli-gke-gcloud-auth-plugin
sudo apt install -y google-cloud-cli-docker-credential-gcr

Upgrading

# With apt or rpm
sudo apt update && sudo apt install --only-upgrade google-cloud-cli
 
# With a tarball installation
gcloud components update

Troubleshooting

Best Practices

  1. Use named configurations per project or environment and activate them explicitly.
  2. Use impersonation or workload identity federation instead of service account keys.
  3. Grant the narrowest role that works — start from roles/viewer and add on.
  4. Use gcloud storage, not the legacy gsutil.
  5. Always pass --project and --zone explicitly in scripts so the command does not depend on the active configuration.
  6. Use --format=json and --filter to get machine-readable output.
  7. Pin the CLI version in CI images.
  8. Keep gcloud config set core/disable_usage_reporting true in automation so non-interactive runs never block on a prompt.

Next Steps

AWS CLI

Install AWS CLI v2 on Linux, macOS and Windows with the signed install script, authenticate with IAM Identity Center or SSO, and automate AWS from your terminal.

Azure CLI

Install Azure CLI 2.91 on Linux, macOS, Windows and Docker, authenticate with device code, service principals and federated credentials, and manage Azure resources from the terminal.