DEV Community

Cover image for The Google Cloud CLI Installation Saga: How I Conquered Python Path Hell on macOS
Eunice js
Eunice js

Posted on

The Google Cloud CLI Installation Saga: How I Conquered Python Path Hell on macOS

#python #google #cli #mac

When Homebrew Fails You

Every macOS developer knows the mantra: "Just use Homebrew." But when it came to installing Google Cloud CLI, Homebrew led me down a rabbit hole of Python errors, broken symlinks, and network timeouts. This is the story of how I discovered that sometimes, the "official" installer is actually the escape hatch you need.

Chapter 1: The Homebrew Illusion

Like most developers, I started with what seemed like the simplest approach:

brew install --cask google-cloud-sdk
Enter fullscreen mode Exit fullscreen mode

The result? Immediate failure:

ERROR: /opt/homebrew/opt/python@3.13/libexec/bin/python3: command not found
Enter fullscreen mode Exit fullscreen mode

The Problem: Homebrew's cask made incorrect assumptions about my Python installation. Despite having Python 3.13 from python.org at /usr/local/bin/python3, Homebrew insisted on looking for it in /opt/homebrew/opt/python@3.13/libexec/bin/python3—a path that didn't exist in my system.

Chapter 2: The Symlink Band-Aid

My first instinct was to "fix" the path issue by creating the missing symlink:

sudo mkdir -p /opt/homebrew/opt/python@3.13/libexec/bin
sudo ln -sf /usr/local/bin/python3 /opt/homebrew/opt/python@3.13/libexec/bin/python3
Enter fullscreen mode Exit fullscreen mode

This allowed the installer to progress... only to hit the next wall.

Chapter 3: Network Timeouts and Cryptography Woes

Now the error changed to network issues:

ERROR: HTTPSConnectionPool(host='release-assets.githubusercontent.com', port=443): Read timed out
Enter fullscreen mode Exit fullscreen mode

The installer was trying to download the cryptography package from GitHub's CDN and failing consistently. I tried:

  • Increasing pip timeouts
  • Multiple retries
  • Different network conditions

Nothing worked. The GitHub CDN seemed to be rejecting or timing out the requests consistently.

Chapter 4: The Revelation - Use Google's Own Installer

After hours of frustration, I realized I was trying to fit a square peg (Homebrew's assumptions) into a round hole (my actual system setup). The solution was shockingly simple: Use Google's official installer directly.

The commands that actually worked:

curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/install_google_cloud_sdk.bash
chmod +x install_google_cloud_sdk.bash
./install_google_cloud_sdk.bash
Enter fullscreen mode Exit fullscreen mode

Why this worked when Homebrew failed:

  1. No Python assumptions - The installer used whatever Python was in my PATH
  2. Better error handling - More graceful fallbacks when components failed
  3. Direct from source - No Homebrew middleman with its own opinions

Chapter 5: The Installer's Wisdom

When the installer ran, it asked smart questions:

Modify profile to update your $PATH and enable shell command completion?
Do you want to continue (Y/n)?
Enter fullscreen mode Exit fullscreen mode

I pressed Y, and it automatically added the necessary lines to my ~/.zshrc:

# The Google Cloud SDK
source '/Users/username/google-cloud-sdk/path.zsh.inc'
source '/Users/username/google-cloud-sdk/completion.zsh.inc'
Enter fullscreen mode Exit fullscreen mode

The key difference: The official installer asked about configuration rather than assuming like Homebrew did.

Chapter 6: The GKE Authentication Finale

With gcloud installed, I still needed to connect to my Kubernetes cluster:

gcloud init  # Simple setup
gcloud components install gke-gcloud-auth-plugin  # Modern auth
gcloud container clusters get-credentials my-cluster --region us-central1
Enter fullscreen mode Exit fullscreen mode

And just like that, I could run:

kubectl get nodes
Enter fullscreen mode Exit fullscreen mode

Success!

The Lessons Learned

1. Homebrew Isn't Always the Answer

Homebrew excels at many things, but for complex, multi-component tools like Google Cloud SDK, its "opinionated" approach can conflict with existing system configurations. The official installer often has better logic for detecting and adapting to your actual environment.

2. The Power of Direct Installation

Google's install_google_cloud_sdk.bash script:

  • Handles Python detection more intelligently
  • Provides clearer error messages
  • Offers interactive configuration
  • Comes straight from the source (no packaging layer)

3. Python Environment Management is Critical

The root cause was my mixed Python installations. Going forward, I'll either:

  • Stick to one Python distribution method
  • Use pyenv for clean version management
  • Regularly audit my Python installations

4. Network Issues Need Workarounds

When packages fail to download:

  • Try the official installer (it might use different sources)
  • Install during off-peak hours
  • Consider manual component installation if needed

Your Cheat Sheet for Success

If you're facing similar Google Cloud CLI installation issues on macOS, skip Homebrew and use this proven sequence:

# 1. Download Google's official installer
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/install_google_cloud_sdk.bash

# 2. Make it executable
chmod +x install_google_cloud_sdk.bash

# 3. Run it (answer 'Y' to PATH modification)
./install_google_cloud_sdk.bash

# 4. Restart your shell or source your config
source ~/.zshrc  # or ~/.bash_profile

# 5. Initialize and configure
gcloud init
gcloud components install gke-gcloud-auth-plugin
Enter fullscreen mode Exit fullscreen mode

Conclusion: Sometimes Simpler is Better

My journey taught me that when "standard" installation methods fail, going back to the source—the official installer from the original developers—often provides the clearest path to success. The Google Cloud SDK installer is well-tested, comprehensive, and designed to handle edge cases that third-party package managers might not anticipate.

The next time you're stuck in dependency hell, remember: the solution might be simpler than you think. Sometimes, you just need to bypass the middleman and go straight to the source.

The working command that saved hours of frustration:

curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/install_google_cloud_sdk.bash && chmod +x install_google_cloud_sdk.bash && ./install_google_cloud_sdk.bash
Enter fullscreen mode Exit fullscreen mode

Sometimes, the official way is the easiest way after all.

Top comments (0)