Instalar a CLI do Google Cloud

Este guia de início rápido descreve o método recomendado para instalar e inicializar a Google Cloud CLI. Após a inicialização, execute alguns comandos principais da CLI gcloud para conferir informações sobre a instalação e verificar se ela foi bem-sucedida.


Para seguir as instruções detalhadas desta tarefa diretamente no console do Google Cloud , clique em Orientação:

Orientações


Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpar.

    Instalar a versão 548.0.0 da CLI gcloud

    Linux
    1. Confirme se você tem uma versão compatível do Python. A CLI do Google Cloud requer o Python de 3.9 a 3.14. O pacote Linux x86_64 inclui um intérprete de Python em pacote que terá preferência por padrão. Para informações sobre como escolher e configurar o interpretador do Python, consulte a documentação do gcloud topic startup.
    2. Faça o download de um dos seguintes itens:
      Plataforma Nome do pacote Tamanho Soma de verificação SHA256
      Linux de 64 bits

      (x86_64)

      google-cloud-cli-linux-x86_64.tar.gz 202,9 MB 71a81b5391dbc0418ac767a8522d8eab92780d708cb1c2740160d137fbeb760a
      Linux de 64 bits

      (Arm)

      google-cloud-cli-linux-arm.tar.gz 57,7 MB 001c4adc88fe796a0c0a0db9771949947528c5066bc5c9f6b7240b5ef59ee0f3
      Linux de 32 bits

      (x86)

      google-cloud-cli-linux-x86.tar.gz 57,8 MB 921b840acfbbb9cace1d696175aded8a891149ccfbab48e5aea11613bc4a31fc

      Para fazer o download do arquivo do Linux, execute o seguinte comando:

      curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz

      Consulte a tabela acima e substitua google-cloud-cli-linux-x86_64.tar.gz pelo nome do pacote *.tar.gz que se aplica à sua configuração.

    3. Para extrair o conteúdo do arquivo para o sistema de arquivos, execute o seguinte comando:
      tar -xf google-cloud-cli-linux-x86_64.tar.gz
      Para substituir uma instalação, exclua o diretório google-cloud-sdk e extraia o arquivo para o mesmo local.
    4. Execute o script de instalação na raiz da pasta extraída:
      ./google-cloud-sdk/install.sh
      O script pede que você execute as seguintes ações de configuração. Para aceitar, responda Y quando solicitado.
      • Adicione a CLI gcloud ao seu PATH.
      • Ative o preenchimento de comandos.
      • Ative o envio de estatísticas de uso anônimas para ajudar a melhorar a CLI gcloud.
      Também é possível fazer a instalação de forma não interativa fornecendo flags. Para conferir as flags disponíveis, execute:
      ./google-cloud-sdk/install.sh --help
    5. Opcional: se você atualizou o PATH na etapa anterior, abra um novo terminal para que as mudanças entrem em vigor.
    Debian/Ubuntu

    Conteúdo do pacote

    A CLI gcloud está disponível no formato de pacote para instalação em sistemas Debian e Ubuntu. O pacote contém apenas as ferramentas de linha de comando gcloud, gcloud alpha, gcloud beta, gsutil e bq. Ele não inclui kubectl ou as extensões do App Engine necessárias para implantar um aplicativo usando os comandos gcloud. Se você quiser esses componentes, instale-os separadamente.

    Antes de começar

    Antes de instalar a CLI gcloud, verifique se o sistema operacional atende aos requisitos a seguir:

    • É uma versão do Ubuntu que não atingiu o fim da vida útil ou uma versão estável do Debian que não atingiu o fim da vida útil.
    • Recentemente, os pacotes foram atualizados. Para fazer isso agora, execute o seguinte comando:
      sudo apt-get update
    • Ele tem apt-transport-https, ca-certificates, gnupg e curl instalados. Para instalar esses pacotes, execute o seguinte comando:
      sudo apt-get install apt-transport-https ca-certificates gnupg curl

    Instalação

    1. Importe a Google Cloud chave pública.
      • Para distribuições mais recentes (Debian 9+ ou Ubuntu 18.04+), execute o seguinte comando:

        curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
      • Para distribuições mais antigas, execute o seguinte comando:
        curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -
      • Se o comando apt-key da sua distribuição não for compatível com o argumento --keyring, execute o seguinte comando:

        curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
      • Se não for possível receber as atualizações mais recentes devido a uma chave expirada, consiga o arquivo de chave apt-get.gpg mais recente.

    2. Adicione o URI de distribuição da CLI gcloud como uma origem de pacote.
      • Para distribuições mais recentes (Debian 9+ ou Ubuntu 18.04+), execute o seguinte comando:
        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
      • Para distribuições mais antigas que não são compatíveis com a opção "assinado por", execute o seguinte comando:

        echo "deb https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
    3. Atualize e instale a gcloud CLI:
      sudo apt-get update && sudo apt-get install google-cloud-cli
      Para mais opções de apt-get, como desativar prompts ou simulações, consulte as apt-get páginas do manual de.

      Dica do Docker: se você estiver instalando a gcloud CLI dentro de uma imagem Docker, use uma única etapa RUN:

      RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg && apt-get update -y && apt-get install google-cloud-cli -y
          
      Para imagens de base mais antigas que não são compatíveis com o comando gpg --dearmor:
      RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key --keyring /usr/share/keyrings/cloud.google.gpg  add - && apt-get update -y && apt-get install google-cloud-cli -y
            
    4. Opcional: instale qualquer um dos seguintes componentes adicionais:
      • google-cloud-cli-anthos-auth
      • google-cloud-cli-app-engine-go
      • google-cloud-cli-app-engine-grpc
      • google-cloud-cli-app-engine-java
      • google-cloud-cli-app-engine-python
      • google-cloud-cli-app-engine-python-extras
      • google-cloud-cli-bigtable-emulator
      • google-cloud-cli-cbt
      • google-cloud-cli-cloud-build-local
      • google-cloud-cli-cloud-run-proxy
      • google-cloud-cli-config-connector
      • google-cloud-cli-datastore-emulator
      • google-cloud-cli-firestore-emulator
      • google-cloud-cli-gke-gcloud-auth-plugin
      • google-cloud-cli-kpt
      • google-cloud-cli-kubectl-oidc
      • google-cloud-cli-local-extract
      • google-cloud-cli-minikube
      • google-cloud-cli-nomos
      • google-cloud-cli-pubsub-emulator
      • google-cloud-cli-skaffold
      • google-cloud-cli-spanner-emulator
      • google-cloud-cli-terraform-validator
      • google-cloud-cli-tests
      • kubectl

      Por exemplo, o componente google-cloud-cli-app-engine-java pode ser instalado da seguinte maneira:

      sudo apt-get install google-cloud-cli-app-engine-java

    Fazer downgrade das versões da CLI gcloud

    Para reverter para uma versão específica da CLI gcloud, em que VERSION é do formulário 123.0.0, execute o seguinte comando:

    sudo apt-get update && sudo apt-get install google-cloud-cli=123.0.0-0

    As dez versões mais recentes estão sempre disponíveis no repositório. Para versões anteriores a 371.0.0, o nome do pacote é google-cloud-sdk

    Red Hat/Fedora/CentOS

    Conteúdo do pacote

    A CLI gcloud está disponível no formato de pacote para instalação no Red Hat Enterprise Linux 7, 8, 9 e 10; Fedora 41 e 42; e CentOS 7 e 8. O pacote contém apenas os comandos gcloud, gcloud alpha, gcloud beta, gsutil e bq. Ele não inclui kubectl ou as extensões do App Engine necessárias para implantar um aplicativo usando comandos gcloud, que podem ser instalados separadamente conforme descrito posteriormente nesta seção.

    Instalação

    1. Atualize o DNF com informações de repositório da gcloud CLI.
      • O comando de exemplo a seguir é para instalações compatíveis com o Red Hat Enterprise Linux 7, 8 ou 9, mas certifique-se de atualizar as configurações conforme necessário para sua configuração:

        sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
        [google-cloud-cli]
        name=Google Cloud CLI
        baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el9-x86_64
        enabled=1
        gpgcheck=1
        repo_gpgcheck=0
        gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
        EOM
      • Para instalações compatíveis com o RHEL 10, use o seguinte comando com o gpgkey atualizado:

        sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
        [google-cloud-cli]
        name=Google Cloud CLI
        baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el10-x86_64
        enabled=1
        gpgcheck=1
        repo_gpgcheck=0
        gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key-v10.gpg
        EOM
    2. Instale libxcrypt-compat.x86_64.
      sudo dnf install libxcrypt-compat.x86_64
    3. Instale a CLI gcloud.
      sudo dnf install google-cloud-cli
    4. Opcional: instale qualquer um dos seguintes componentes adicionais:
      • google-cloud-cli-anthos-auth
      • google-cloud-cli-app-engine-go
      • google-cloud-cli-app-engine-grpc
      • google-cloud-cli-app-engine-java
      • google-cloud-cli-app-engine-python
      • google-cloud-cli-app-engine-python-extras
      • google-cloud-cli-bigtable-emulator
      • google-cloud-cli-cbt
      • google-cloud-cli-cloud-build-local
      • google-cloud-cli-cloud-run-proxy
      • google-cloud-cli-config-connector
      • google-cloud-cli-datastore-emulator
      • google-cloud-cli-firestore-emulator
      • google-cloud-cli-gke-gcloud-auth-plugin
      • google-cloud-cli-kpt
      • google-cloud-cli-kubectl-oidc
      • google-cloud-cli-local-extract
      • google-cloud-cli-minikube
      • google-cloud-cli-nomos
      • google-cloud-cli-pubsub-emulator
      • google-cloud-cli-skaffold
      • google-cloud-cli-spanner-emulator
      • google-cloud-cli-terraform-validator
      • google-cloud-cli-tests
      • kubectl

      Por exemplo, para instalar o componente google-cloud-cli-app-engine-java, execute o seguinte comando:

      sudo dnf install google-cloud-cli-app-engine-java

    Fazer downgrade das versões da CLI gcloud

    Para reverter para uma versão específica da CLI gcloud, execute o seguinte comando. Substitua 123.0.0 pela versão que você quer instalar:

    sudo dnf downgrade google-cloud-cli-123.0.0

    As dez versões mais recentes estão disponíveis no repositório. Para versões anteriores a 371.0.0, use google-cloud-sdk como o nome do pacote.

    macOS
    1. Confirme se você tem uma versão compatível do Python. A CLI do Google Cloud requer o Python de 3.9 a 3.14.

      Para verificar a versão do Python, execute python3 -V ou python -V.

      O script de instalação pode instalar o Python para você, se necessário. Isso exige as ferramentas de linha de comando do Xcode. Para instalá-los, execute sudo xcode-select --install. Como alternativa, você pode instalar uma versão compatível do Python em python.org.

      Para mais informações sobre como configurar o interpretador do Python, especialmente se você tiver várias versões instaladas, consulte a documentação do gcloud topic startup.

    2. Faça o download de um dos seguintes itens:
      Plataforma Pacote Tamanho Soma de verificação SHA256
      macOS de 64 bits

      (x86_64)

      google-cloud-cli-darwin-x86_64.tar.gz 57,9 MB 6a838eacf37a2505c4d90fb74bd97abdb488b0a85321c3d886e4bd9851a78fd8
      macOS de 64 bits

      (ARM64, Apple silicon)

      google-cloud-cli-darwin-arm.tar.gz 57,8 MB 36e2838b7b3ec0659df7a142bb870f8612576ca6883240d657363e3391964339
      macOS de 32 bits

      (x86)

      google-cloud-cli-darwin-x86.tar.gz 56,3 MB eaeef651be72fb86379e1fd6c208d625c5ebaf3f87d9deb540594e456fc4ed56

      Como alternativa, faça o download do arquivo na linha de comando. Substitua FILE_NAME pelo nome do pacote da sua plataforma na tabela acima.

      curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/FILE_NAME
    3. Extraia o conteúdo do arquivo para o local de sua preferência no sistema de arquivos. Uma prática comum é extrair para o diretório inicial.

      No macOS, isso pode ser feito abrindo o arquivo .tar.gz salvo no local de preferência. Outra opção é executar o seguinte na linha de comando:

      tar -xf FILE_NAME

      Para substituir uma instalação, exclua o diretório google-cloud-sdk e extraia o arquivo para o mesmo local.

    4. Execute o script de instalação na raiz da pasta extraída:
      ./google-cloud-sdk/install.sh
      O script pede que você execute as seguintes ações de configuração. Para aceitar, responda Y quando solicitado.
      • Instale o Python 3.13 e os módulos recomendados, se necessário.
      • Adicione a CLI gcloud ao PATH e ative o preenchimento de comandos.
      • Ative o envio de estatísticas de uso anônimas para ajudar a melhorar a CLI gcloud.
      Também é possível fazer a instalação de forma não interativa fornecendo flags. Para conferir as flags disponíveis, execute:
      ./google-cloud-sdk/install.sh --help
      Para executar o script de instalação com o modo de leitor de tela ativado:
      ./google-cloud-sdk/install.sh --screen-reader=true
    5. Opcional: se você atualizou o PATH na etapa anterior, abra um novo terminal para que as mudanças entrem em vigor.
    Windows

    A Google Cloud CLI no Windows exige o Windows 8.1 e versões mais recentes ou o Windows Server 2012 e versões mais recentes.

    1. Faça o download do Instalador da CLI do Google Cloud.

      Se preferir, abra um terminal do PowerShell e execute os comandos a seguir:

      (New-Object Net.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe")
      
      & $env:Temp\GoogleCloudSDKInstaller.exe
          
    2. Inicie o instalador e siga os prompts. O instalador é assinado pela Google LLC.

      • Se você estiver usando um leitor de tela, marque a caixa de seleção Ativar modo leitor de tela. Essa opção configura gcloud para usar rastreadores de status em vez de spinners unicode, exibir o progresso como uma porcentagem e nivelar tabelas. Para mais informações, consulte o Guia de recursos de acessibilidade.
      • A Google Cloud CLI requer Python. As versões compatíveis são Python 3.9 a 3.14. Por padrão, a versão para Windows da Google Cloud CLI vem com o Python 3. Para usar a Google Cloud CLI, seu sistema operacional precisa executar uma versão compatível do Python.
      • O instalador instala todas as dependências necessárias, incluindo a versão necessária do Python. Embora a CLI do Google Cloud instale e gerencie o Python 3 por padrão, é possível usar uma instalação atual do Python ao desmarcar a opção de instalar o Bundled Python, se necessário. Consulte gcloud topic startup para saber como usar uma instalação existente do Python.
    3. Depois que a instalação for concluída, o instalador oferecerá a opção de criar os atalhos do menu e da área de trabalho, além de iniciar o shell da Google Cloud CLI. Desmarque a opção para iniciar o shell. Você vai executar e configurar a CLI gcloud nas próximas etapas.

    Dicas para solução de problemas

    • Se a instalação não for bem-sucedida devido ao comando find não ter sido reconhecido, verifique se sua variável de ambiente PATH está definida para incluir a pasta que contém find. Geralmente, isso é C:\WINDOWS\system32;.
    • Se você desinstalou a CLI gcloud, é necessário reinicializar o sistema antes de instalá-la novamente.
    • Se a descompactação falhar, execute o instalador como um administrador.
    Chromebook
    1. Configure o ambiente de desenvolvimento do Linux no Chromebook.
    2. Adicione o URI de distribuição da CLI gcloud como uma origem de pacote. Execute este comando:
      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
    3. Importe a chave pública Google Cloud :
      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -
    4. Atualize e instale a CLI gcloud:
      sudo apt-get update && sudo apt-get install google-cloud-cli
    5. Opcional: instale qualquer um dos seguintes componentes adicionais:
      • google-cloud-cli-anthos-auth
      • google-cloud-cli-app-engine-go
      • google-cloud-cli-app-engine-grpc
      • google-cloud-cli-app-engine-java
      • google-cloud-cli-app-engine-python
      • google-cloud-cli-app-engine-python-extras
      • google-cloud-cli-bigtable-emulator
      • google-cloud-cli-cbt
      • google-cloud-cli-cloud-build-local
      • google-cloud-cli-cloud-run-proxy
      • google-cloud-cli-config-connector
      • google-cloud-cli-datastore-emulator
      • google-cloud-cli-firestore-emulator
      • google-cloud-cli-gke-gcloud-auth-plugin
      • google-cloud-cli-kpt
      • google-cloud-cli-kubectl-oidc
      • google-cloud-cli-local-extract
      • google-cloud-cli-minikube
      • google-cloud-cli-nomos
      • google-cloud-cli-pubsub-emulator
      • google-cloud-cli-skaffold
      • google-cloud-cli-spanner-emulator
      • google-cloud-cli-terraform-validator
      • google-cloud-cli-tests
      • kubectl

      Por exemplo, para instalar o componente google-cloud-cli-app-engine-java, execute o seguinte comando:

      sudo apt-get install google-cloud-cli-app-engine-java

    Fazer downgrade das versões da CLI gcloud

    Para reverter para uma versão específica da CLI gcloud, execute o comando a seguir. Substitua 123.0.0 pela versão que você quer instalar:

    sudo apt-get update && sudo apt-get install google-cloud-cli=123.0.0-0

    As dez versões mais recentes estão disponíveis no repositório. Para versões anteriores a 371.0.0, use google-cloud-sdk como o nome do pacote.

    Inicializar e autorizar a CLI gcloud

    Se você estiver usando um proxy ou firewall, consulte Configuração de proxy para ativar o acesso à rede para a CLI gcloud.

    Depois de instalar a CLI gcloud, inicialize-a para autorizar o acesso a Google Cloud e configurar uma configuração padrão. Para mais informações, consulte gcloud init.

    1. Execute gcloud init para inicializar a CLI gcloud:

      gcloud init
      

      Por padrão, esse comando abre um navegador da Web para autorizar o acesso. Para autorizar na linha de comando, adicione a flag --console-only. Para autorização não interativa, crie uma conta de serviço com os escopos adequados no consoleGoogle Cloud e use gcloud auth activate-service-account com o arquivo de chave JSON.

    2. Siga as instruções para autorizar e configurar:

      • Quando solicitado, aceite e faça login na sua Conta do Google no navegador. Clique em Permitir para conceder permissão de acesso a recursos.

      • Na lista de projetos em que você tem permissões de proprietário, editor ou leitor, selecione um projeto. Se você tiver apenas um projeto, gcloud init o selecionará para você.

        Se você tiver mais de 200 projetos, será necessário inserir um ID, criar ou listar projetos. Se você optar por criar um projeto, também será necessário ativar o faturamento nele.

      • Se a API do Compute Engine estiver ativada, selecione uma zona padrão do Compute Engine.

    3. Opcional: para uma experiência de leitor de tela aprimorada, ative a propriedade accessibility/screen_reader com o seguinte comando:

      gcloud config set accessibility/screen_reader true
      

      Para mais informações, consulte o guia Como ativar recursos de acessibilidade.

    Executar comandos principais

    Execute comandos principais para conferir informações sobre a instalação da gcloud CLI:

    1. Liste as contas com credenciais armazenadas no sistema local:

      gcloud auth list
      

      A CLI gcloud mostra uma lista de contas credenciadas:

      Credentialed Accounts
      ACTIVE             ACCOUNT
      *                  example-user-1@example.com
                         example-user-2@example.com
      

    2. Liste as propriedades na configuração ativa da gcloud CLI:

      gcloud config list
      

      A CLI gcloud mostra a lista de propriedades:

      [core]
      account = example-user-1@example.com
      disable_usage_reporting = False
      project = example-project
      

    3. Confira informações sobre os comandos gcloud e outros tópicos:

      gcloud help
      

      Por exemplo, para visualizar a ajuda para gcloud compute instances create:

      gcloud help compute instances create
      

      A CLI gcloud mostra um tópico de ajuda com uma descrição do comando, uma lista de flags e argumentos e exemplos de como usar o comando.

    Opcional: instalar outros componentes

    Para instalar outros componentes, como os emuladores do App Engine, kubectl ou comandos da CLI gcloud no nível de lançamento Alfa ou Beta, consulte Como gerenciar componentes da CLI gcloud.

    Limpar

    Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga as etapas abaixo.

    A seguir

    • Leia o guia da gcloud CLI para uma visão geral da CLI gcloud, incluindo uma rápida introdução aos principais conceitos, convenções de comando e dicas úteis.
    • Leia o guia de referência da gcloud CLI para páginas detalhadas sobre cada comando da CLI gcloud, incluindo descrições, flags e exemplos que podem ser usados para executar diversas tarefas no Google Cloud.
    • Consulte a folha de referência da CLI gcloud para ver uma lista de comandos e conceitos-chave mais usados.