How to Install the gcloud CLI on Windows, macOS, and Linux

What is the gcloud CLI?

gcloud is the primary command-line tool for Google Cloud. You install it once on your machine and use it to create and manage GCP resources, configure authentication, deploy services, and automate workflows from a terminal.

The gcloud CLI is part of the Google Cloud SDK. It wraps the same REST APIs that power the Cloud Console, which means almost anything you can do in the browser you can also do from the terminal. Terminal commands are repeatable, scriptable, and version-controllable. A Console click is none of those things.

Developers use gcloud to deploy code and manage permissions. Learners use it to follow tutorials without clicking through menus. Ops teams use it to script repeatable infrastructure tasks. If you are working with GCP seriously, you will use gcloud constantly.

When to use local gcloud vs Cloud Shell

Before installing anything, it helps to know that GCP offers two ways to run gcloud commands: a local installation on your own machine, and Cloud Shell, a free browser-based terminal that comes with gcloud pre-installed and pre-authenticated.

Install gcloud locally when you need to:

• work from your own machine without browser session limits or weekly usage quotas
• write and test scripts that call GCP APIs from local code
• use GCP client libraries in Python, Node.js, Go, or other languages
• configure Application Default Credentials for local development
• prepare for CI/CD pipelines and automation workflows
• integrate gcloud with local tools like Docker, kubectl, or Terraform

Cloud Shell is a better starting point if you are new to GCP and want to try commands immediately without setup. It opens in seconds, authentication is already handled, and you do not need admin access to your machine. Once you outgrow its 50-hour weekly quota or need local tool integration, come back here.

gcloud CLI vs Cloud Shell: a quick comparison

• Setup effort: local install takes a few minutes and requires running gcloud init. Cloud Shell opens instantly with no setup or configuration.

• Authentication: local gcloud requires running gcloud auth login and gcloud auth application-default login for client libraries. Cloud Shell is pre-authenticated as your Google account.

• Session limits: local gcloud has no session limits and no weekly quota. Cloud Shell has a 50-hour weekly quota and a 40-minute inactivity timeout.

• Persistence: local config, credentials, and files persist normally. Cloud Shell persists only 5 GB in your home directory; everything else resets when the session ends.

• Local development: local gcloud integrates with your code editor, local servers, and development workflow. Cloud Shell is browser-only.

• Best for: local install suits ongoing development. Cloud Shell suits quick tasks, learning, or machines where you cannot install software.

Before you install

• Google account: you need a Google account to authenticate after installation. A personal Gmail or Google Workspace account both work. If you do not have a GCP project yet, gcloud init will offer to create one.

• Terminal access: on macOS or Linux, use your default shell. On Windows, use PowerShell, Command Prompt, or WSL.

• Admin rights: Homebrew and apt installs may need sudo or admin privileges. The Windows installer requires admin rights to modify PATH.

• Choose one install method: mixing methods on the same machine creates two separate gcloud copies at potentially different versions. Pick one approach and use it for updates too.

Install on macOS

The recommended method is Homebrew. If you already use it for other tools, this keeps everything in one place and makes updates a single command.

# Install with Homebrew (recommended)
brew install --cask google-cloud-sdk

# After the install completes, open a new terminal window
# PATH changes do not apply to already-open terminals

# Verify the install
gcloud version

# Run the setup wizard
gcloud init

If you do not have Homebrew, download the macOS archive from cloud.google.com/sdk, extract it, and run the install.sh script inside. After the script runs, open a new terminal or source your shell profile to apply the PATH change.

Install on Linux

On Debian or Ubuntu-based systems, the recommended approach is to add the official Google Cloud apt repository. This lets apt manage updates alongside your other system packages.

# Add the Google Cloud package signing key
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg

# Add the repository
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] \
  https://packages.cloud.google.com/apt cloud-sdk main" \
  | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list

# Install
sudo apt-get update
sudo apt-get install google-cloud-cli

# Verify
gcloud version

# Run setup
gcloud init

On Red Hat, Fedora, or CentOS-based systems, the process is similar but uses a yum or dnf repository instead of apt. Once set up, future updates go through sudo dnf upgrade google-cloud-cli or the equivalent.

Install on Windows

Download the Windows installer (.exe) from cloud.google.com/sdk and run it. The installer guides you through setup, adds gcloud to your PATH, and optionally launches gcloud init at the end.

# After the installer finishes, open a new terminal window, then verify:
gcloud version

# Run the setup wizard if the installer did not launch it automatically
gcloud init

If gcloud version is not recognised, close your current terminal and open a fresh one. The PATH modification only applies to new terminal sessions, not already-open ones.

First-time setup with gcloud init

Think of installing the SDK and running gcloud init as two separate steps, like downloading an app and then actually logging into it. Downloading WhatsApp does not add your contacts. Installing gcloud does not sign you in. Until you run gcloud init, most commands will fail.

gcloud init walks you through three things:

1. Sign in: opens a browser window so you can authenticate with your Google account. Once completed, gcloud stores a credential token locally.

2. Select or create a project: sets a GCP project as your default. Every gcloud command without an explicit —project flag will target this project.

3. Set a default region and zone: optional, but strongly recommended. Without these defaults, any command that needs a location will prompt you every time.

# Interactive setup wizard
gcloud init

# Confirm what was configured afterwards
gcloud config list

The defaults you set here apply to every subsequent gcloud command that needs them. Choose the region where you plan to create most of your resources. You can change specific values later with gcloud config set. For the full configuration reference, see the gcloud CLI guide.

How it works after installation

When you type a gcloud command, here is what actually happens:

1. gcloud reads your local configuration (active project, region, zone) from a config file in your home directory.
2. It signs the request using your stored authentication credentials.
3. It sends an HTTP request to the relevant GCP API, the same one the Cloud Console uses.
4. The API returns a result, which gcloud formats and prints to your terminal.

Your default project tells gcloud where to send commands, but the relevant API must still be enabled in that project before you can use it. And your Google account needs the right IAM roles to perform the action, just as it would in the Cloud Console.

Verify your installation

After gcloud init, run these five checks before creating any resources. Each command confirms a specific part of your setup.

# 1. Confirm gcloud is on your PATH and installed correctly
gcloud version

# 2. Confirm your sign-in worked and see which account is active
gcloud auth list

# 3. Confirm a default project is set
gcloud config get-value project

# 4. Confirm region and zone defaults are set
gcloud config get-value compute/region
gcloud config get-value compute/zone

# 5. Make a real API call to verify credentials and connectivity
gcloud compute regions list --limit=3

If step 5 fails with an authentication error, run gcloud auth login and sign in again. If it fails with an API or project error, confirm your active project is correct and check whether the Compute Engine API is enabled in that project.

Set up Application Default Credentials

There are two separate authentication commands, and they unlock two different things. Think of them as two different keys for two different locks.

• gcloud auth login gives you a key to run gcloud commands from the terminal. This is what gcloud init handles automatically.

• gcloud auth application-default login gives your code a key to call GCP APIs directly. This one is not run by gcloud init and must be set up separately.

If you write code that calls GCP APIs (a Python script using the Cloud Storage client, a Node.js app using Firestore, a Go service querying BigQuery), you need Application Default Credentials (ADC) set up locally. Without it, your code will fail with authentication errors even if gcloud commands themselves work fine.

# Set up ADC so local code can call GCP APIs as your user account
gcloud auth application-default login

# Confirm which identity ADC will use
gcloud auth application-default print-access-token

After running this, GCP client libraries in any language automatically find and use these credentials without extra configuration in your code. When your code runs on GCP infrastructure (Cloud Run, a Compute Engine VM), ADC picks up the attached service account automatically. No extra command needed.

For the full explanation of how user credentials differ from service account credentials, see Identity vs Service Accounts.

Keeping gcloud up to date

The update method must match the install method. Mixing them creates version conflicts that surface as subtle, hard-to-diagnose errors.

# Homebrew install: update with Homebrew
brew upgrade google-cloud-sdk

# apt install: update with apt
sudo apt-get upgrade google-cloud-cli

# Interactive installer or manual archive: update with gcloud
gcloud components update

# See what is installed and what has available updates
gcloud components list

# Install optional components as needed
gcloud components install kubectl       # Kubernetes CLI
gcloud components install beta          # Preview/beta commands