Install gsutil

Important: gsutil is not the recommended CLI forCloud Storage.Usegcloud storage commands in the Google Cloud CLI instead.

This page describes the installation and setup of gsutil, a tool that lets youaccess Cloud Storage from the command line using HTTPS.

Installing gsutil provides immediate access to public data, enabling you to readand write as permitted. To interact with the protected data shared with you,authentication with the Cloud Storage service is required. Enablingbilling gives you the ability to create and manage your own buckets.

System requirements

  • The gsutil tool runs on Linux/Unix, Mac OS, and Windows (XP or later).

  • gsutil versions 5.35 or later require Python 3.9 to 3.13, which you can obtain byusing your Python version manager or by installing an appropriate version.

Note: Support for Python 3.8 is dropped from gsutil v5.35.To ensure compatibility with future gsutil releases, upgrade your Pythonenvironment to a supported version (3.9+).

The following instructions show how to manage Python versions:

Linux

Prerequisites: Install a Python version manager (pyenv) and install a suitable Python version.

  1. Set the Global Python Version:
    • To set Python 3.13 as the global version:
      pyenv global 3.13
    • Or set the Python version locally for a specific project folder:
      pyenv local 3.13
  2. Confirm that the correct Python version is in use:
    python --version

    You should see:

    Python 3.13
macOS

Method 1: Using Homebrew (brew)

Prerequisites: Install Homebrew and install a suitable Python version through homebrew.

  1. Set a specific Python version as the default:
    • Add the version you want to your$PATH. For example, to use Python 3.13:
      export PATH="/usr/local/opt/python@3.13/bin:$PATH"
    • To make this change permanent, add the path to your shell configuration file (~/.bash_profile,~/.zshrc, or~/.bashrc).
  2. Confirm that the correct Python version is in use:
    python --version

    You should see:

    Python 3.13

Method 2: Using pyenv

Prerequisites: Install Python version manager (pyenv) and install a suitable python version through pyenv.

  1. Set the global Python version:
    • To set the Python version globally (for all terminals):
      pyenv global 3.13
    • Or set the Python version locally for a specific project folder:
      pyenv local 3.13
  2. Confirm that the correct Python version is in use:
    python --version

    You should see:

    Python 3.13
Windows

Prerequisites: Install Python version manager (pyenv-win) and install a suitable Python version through pyenv.

  1. Set the Global Python Version:
    • To set Python 3.13 as the global version:
      pyenv global 3.13
    • Or set the Python version locally for a specific project folder:
      pyenv local 3.13
  2. Confirm that the correct Python version is in use:
    python --version

    You should see:

    Python 3.13
  • If you plan to usecomposite objects, you need to install compiledcrcmod. On Windows, this is only available for 32-bit Python. For moreinformation on crcmod, install gsutil and see the help topic by using thecommandgsutil help crc32c.
Warning: On some Linux distributions, another tool namedgsutil, byGrandStream BudgeTone, is pre-installed. If you run this command instead of theCloud Storage gsutil, it will likely print an error message similar to"Choose one of -b, -d, -e, or -r to do something". If this happens, you caneither move the Cloud Storage version of gsutil to the front of yourPATH environment variable, or you can specify the full path when runningCloud Storage gsutil (for example,/home/users/joan/gsutil/gsutil ls).

Installing gsutil

Note: If you have previously installed theGoogle Cloud CLI, then gsutilis already included. Additionally, the Google Cloud CLI, including gsutil, isinstalled by default on a number ofGoogle Compute Engine images; seeOSdetails for a full list.

The officially supported installation and update method for gsutil is as partof the Google Cloud CLI.

Before you begin

Google Cloud CLI and gsutil have Python version dependencies that might causecompatibility issues. Google Cloud CLI requires Python 3.10 to 3.14, while gsutil requires Python 3.9 to 3.13.

To install gsutil, we recommend that youinstall it as part of theGoogle Cloud CLI. If you choose to install gsutil directly, usePython 3.9 to 3.13 to avoid compatibility issues.

Installing gsutil as part of the Google Cloud CLI

Follow the instructions for your operating system to install gsutil as a part ofthe Google Cloud CLI:

Linux
  1. Confirm that you have a supported version of Python. The Google Cloud CLI requires Python 3.10 to 3.14. The x86_64 Linux package includes a bundled Python interpreter that will be preferred by default. For information on how to choose and configure your Python interpreter, see thegcloud topic startup documentation.
  2. Download one of the following:Note: To determine your Linux platform, rununame -a at the command line.
    PlatformPackage nameSizeSHA256 Checksum
    Linux 64-bit

    (x86_64)

    		google-cloud-cli-linux-x86_64.tar.gz203.8 MBc23b87ad08cd2dfb9b0538bc74cf945dc32af7ff3089ae1e67e485daeab10943
    Linux 64-bit

    (Arm)

    		google-cloud-cli-linux-arm.tar.gz58.6 MB6832a5ce66edb445863b807ce1cffda8b489e6adf61c8dbcf0610d9133415964
    Linux 32-bit

    (x86)

    		google-cloud-cli-linux-x86.tar.gz58.7 MBcf828195cd40c2cc991dc42c215869708b72fcece46956ab10b439875f543a14

    To download the Linux archive file, run the following command:

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

    Refer to the table above and replacegoogle-cloud-cli-linux-x86_64.tar.gz with the*.tar.gz package name that applies to your configuration.

  3. To extract the contents of the file to your file system, run the following command:
    tar-xfgoogle-cloud-cli-linux-x86_64.tar.gz
     To replace an existing installation, delete the existinggoogle-cloud-sdk directory and then extract the archive to the same location.
  4. Run the installation script from the root of the folder you extracted:
    ./google-cloud-sdk/install.sh
     The script prompts you to perform the following setup actions. To accept, answerY when prompted.     You can also perform the installation non-interactively by providing flags. To view available flags, run:
    ./google-cloud-sdk/install.sh--help
  5. Optional: If you updated yourPATH in the previous step, open a new terminal so that the changes take effect.
  6. Rungcloud init to initialize, authorize, and configure the gcloud CLI.
  7. Optional: Install additional components using thecomponent manager.
Debian/Ubuntu

Package contents

The gcloud CLI is available in package format for installation on Debian and Ubuntu systems. This package contains thegcloud,gcloud alpha,gcloud beta,gsutil, andbq command-line tools only. It doesn't includekubectl or the App Engine extensions required to deploy an application usinggcloud commands. If you want these components, you mustinstall them separately.

Note: For specific setups, alternative installation methods are available:

Before you begin

Before you install the gcloud CLI, make sure that your operating system meets the following requirements:

  • It is an Ubuntu release that hasn't reachedend-of-life or a Debian stable release that hasn't reachedend-of-life.
  • It has recently updated its packages. To do this now, run the following command:
    sudoapt-getupdate
  • It hasca-certificates,gnupg, andcurl installed. To install these packages, run the following command:
    sudoapt-getinstallca-certificatesgnupgcurl

Installation

  1. Import the Google Cloud public key.

    • For newer distributions (Debian 9+ or Ubuntu 18.04+) run the following command:

      curlhttps://packages.cloud.google.com/apt/doc/apt-key.gpg|sudogpg--dearmor-o/usr/share/keyrings/cloud.google.gpg
    • For older distributions, run the following command:
      curlhttps://packages.cloud.google.com/apt/doc/apt-key.gpg|sudoapt-key--keyring/usr/share/keyrings/cloud.google.gpgadd-

    • If your distribution's apt-key command doesn't support the--keyring argument, run the following command:

      curlhttps://packages.cloud.google.com/apt/doc/apt-key.gpg|sudoapt-keyadd-

    • If you can't get latest updates due to an expired key,obtain the latest apt-get.gpg key file.

  2. Add the gcloud CLI distribution URI as a package source.
    • For newer distributions (Debian 9+ or Ubuntu 18.04+), run the following command:
      echo"deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main"|sudotee-a/etc/apt/sources.list.d/google-cloud-sdk.list

    • For older distributions that don't support the signed-by option, run the following command:

      echo"deb https://packages.cloud.google.com/apt cloud-sdk main"|sudotee-a/etc/apt/sources.list.d/google-cloud-sdk.list
    Note: Make sure you don't have duplicate entries for thecloud-sdk repo in/etc/apt/sources.list.d/google-cloud-sdk.list.
  3. Update and install the gcloud CLI:
    sudoapt-getupdate&&sudoapt-getinstallgoogle-cloud-cli
     For additionalapt-get options, such as disabling prompts or dry runs, refer to the    apt-get man pages.

    Docker Tip: If installing the gcloud CLI inside a Docker image, use a single RUN step instead:

    RUNecho"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&&curlhttps://packages.cloud.google.com/apt/doc/apt-key.gpg|gpg--dearmor-o/usr/share/keyrings/cloud.google.gpg&&apt-getupdate-y&&apt-getinstallgoogle-cloud-cli-y
     For older base images that do not support thegpg --dearmor command:
    RUNecho"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&&curlhttps://packages.cloud.google.com/apt/doc/apt-key.gpg|apt-key--keyring/usr/share/keyrings/cloud.google.gpgadd-&&apt-getupdate-y&&apt-getinstallgoogle-cloud-cli-y
  4. Optional: Install any of the following additional components:
    • 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

    For example, thegoogle-cloud-cli-app-engine-java component can be installed as follows:

    sudoapt-getinstallgoogle-cloud-cli-app-engine-java
  5. Rungcloud init to initialize, authorize, and configure the gcloud CLI.

Downgrade gcloud CLI versions

To revert to a specific version of the gcloud CLI, whereVERSION is of the form123.0.0, run the following command:

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

The ten most recent releases are always available in the repo. For releases prior to 371.0.0, the package name isgoogle-cloud-sdk

Red Hat/Fedora/CentOS

Package contents

The gcloud CLI is available in package format for installation on Red Hat Enterprise Linux 7, 8, 9, and 10; Fedora 41 and 42; and CentOS 7 and 8 systems. This package contains thegcloud,gcloud alpha,gcloud beta,gsutil, andbq commands only. It doesn't includekubectl or the App Engine extensions required to deploy an application usinggcloud commands, which can be installed separately as described later in this section.

Note: If you're using an instance on Compute Engine, the Google Cloud CLI isinstalled by default on a number of OS images. SeeOS details for a full list.

Installation

  1. Update DNF with gcloud CLI repository information.

    • The following sample command is for a Red Hat Enterprise Linux 7, 8, or 9-compatible installations, but make sure that you update the settings as needed for your configuration:

      sudotee-a/etc/yum.repos.d/google-cloud-sdk.repo<< EOM[google-cloud-cli]name=Google Cloud CLIbaseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el9-x86_64enabled=1gpgcheck=1repo_gpgcheck=0gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpgEOM

    • For RHEL 10-compatible installations, use the following command with the updatedgpgkey:

      sudotee-a/etc/yum.repos.d/google-cloud-sdk.repo<< EOM[google-cloud-cli]name=Google Cloud CLIbaseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el10-x86_64enabled=1gpgcheck=1repo_gpgcheck=0gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key-v10.gpgEOM
  2. Installlibxcrypt-compat.x86_64.
    sudodnfinstalllibxcrypt-compat.x86_64
  3. Install the gcloud CLI:
    sudodnfinstallgoogle-cloud-cli
    Note: If you haven't moved todnf on your system, you can run these commands usingyum instead.

    You can also usednf/yum options, such as disabling prompts or dry runs, with the provided commands.

  4. Optional: Install any of the followingadditional components:
    • 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

    For example, to install thegoogle-cloud-cli-app-engine-java component, run the following command:

    sudodnfinstallgoogle-cloud-cli-app-engine-java
  5. Rungcloud init to initialize, authorize, and configure the gcloud CLI.

Downgrade gcloud CLI versions

To revert to a specific version of gcloud CLI, run the following command. Replace123.0.0 with the version that you want to install:

sudodnfdowngradegoogle-cloud-cli-123.0.0

The ten most recent releases are available in the repository. For releases prior to 371.0.0, usegoogle-cloud-sdk as the package name.

macOS
  1. Confirm that you have a supported version of Python. The Google Cloud CLI requires Python 3.10 to 3.14.

    To check your Python version, runpython3 -V orpython -V.

    The installation script can install Python for you if needed. This requiresXcode Command Line Tools. To install them, runsudo xcode-select --install. Alternatively, you can install a supported Python version frompython.org.

    For more information about configuring your Python interpreter, especially if you have multiple versions installed, see thegcloud topic startup documentation.

  2. Download one of the following: Note: To determine your platform, rununame -m from a command line.
    PlatformPackageSizeSHA256 Checksum
    macOS 64-bit

    (x86_64)

    		google-cloud-cli-darwin-x86_64.tar.gz58.8 MB 2ea3a172327dcc42b75248a60a45aceb38027d1064bf01ecb7230f21dea50bed
    macOS 64-bit

    (ARM64, Apple silicon)

    		google-cloud-cli-darwin-arm.tar.gz58.7 MB 3d999f0eccf7c933cab2e8034fba38c265f4fbe395a1b18bbebb033248a503fa
    macOS 32-bit

    (x86)

    		google-cloud-cli-darwin-x86.tar.gz57.2 MB f25627e2130c606fa4cf6b3e26ace19129a36b9d6c4d72e7c0084c13d6af8d57

    Alternatively, you can download the archive from the command line. ReplaceFILE_NAME with the package name for your platform from the table above.

    curl-Ohttps://dl.google.com/dl/cloudsdk/channels/rapid/downloads/FILE_NAME
  3. Extract the contents of the file to your preferred location on your file system. A common practice is to extract it to your home directory.

    On macOS, you can do this by opening the downloaded.tar.gz file in your preferred location. Alternatively, from the command line, run:

    tar-xfFILE_NAME

    To replace an existing installation, delete the existinggoogle-cloud-sdk directory and then extract the archive to the same location.

  4. Run the installation script from the root of the folder you extracted:
    ./google-cloud-sdk/install.sh
     The script prompts you to perform the following setup actions. To accept, answerY when prompted.     You can also perform the installation non-interactively by providing flags. To view available flags, run:
    ./google-cloud-sdk/install.sh--help
     To run the install script with screen reader mode enabled:
    ./google-cloud-sdk/install.sh--screen-reader=true
  5. Optional: If you updated yourPATH in the previous step, open a new terminal so that the changes take effect.
  6. Rungcloud init to initialize, authorize, and configure the gcloud CLI.
  7. Optional: Install additional components using thecomponent manager.
Windows

The Google Cloud CLI on Windows requires Windows 8.1 and later, or Windows Server 2012 and later.

  1. Download theGoogle Cloud CLI installer.

    Alternatively, open a PowerShell terminal and run the following PowerShell commands:

    (New-ObjectNet.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe","$env:Temp\GoogleCloudSDKInstaller.exe")&$env:Temp\GoogleCloudSDKInstaller.exe

  2. Launch the installer and follow the prompts. The installer is signed by Google LLC.

    • If you're using a screen reader, check theTurn on screen reader mode checkbox. This option configuresgcloud to use status trackers instead of unicode spinners, display progress as a percentage, and flatten tables. For more information, see theAccessibility features guide.
    • Google Cloud CLI requires Python; supported versions are Python 3.10 to 3.14. By default, the Windows version of Google Cloud CLI comes bundled with Python 3. To use Google Cloud CLI your operating system must be able to run a supported version of Python.
    • The installer installs all necessary dependencies, including the needed Python version. While Google Cloud CLI installs and manages Python 3 by default, you can use an existing Python installation if necessary byunchecking the option to Install Bundled Python. Seegcloud topic startup to learn how to use an existing Python installation.
  3. After installation is complete, the installer gives you the option to create Start Menu and Desktop shortcuts, start the Google Cloud CLI shell, and configure the gcloud CLI. Leave the options to start the shell and configure your installation selected. The installer starts a terminal window and runs thegcloud init command to initialize, authorize, and configure the gcloud CLI.
  4. The default installation doesn't include the App Engine extensions required to deploy an application usinggcloud commands. These components can be installed using thegcloud CLI component manager.

Troubleshooting tips

  • If your installation is unsuccessful due to thefind command not being recognized, ensure yourPATHenvironment variable is set to include the folder containingfind. Usually, this isC:\WINDOWS\system32;.
  • If you uninstalled the gcloud CLI, you must reboot your system before installing the gcloud CLI again.
  • If unzipping fails, run the installer as an administrator.

As part of installinggsutil, you must set theCLOUDSDK_PYTHON environment variable to use the correctPython version. For more details, see thegcloud startup topic.

Perform updates with thecomponents update command:gcloud components update.

Setting Up Credentials to Access Protected Data

In order to access protected data or write to a protected bucket, you needto set up credentials (authenticate). For example, if someone else has created aCloud Storage account and uploaded data that is only accessible to youor other specific individuals, you must set up your credentials to theCloud Storage service to be able to access this data.

When using gsutil as part of the Google Cloud CLI,OAuth2 is used toauthenticate and authorize access to your Cloud Storage resources. Toestablish access, run the commandgcloud init and follow theinstructions provided in the command line, which include logging into your useraccount. Note that you likely already performed this setup if you followed theinstallation steps. If you rangcloud init previously,when you run the command again you are asked if you want to re-initialize theconfiguration or create a new one. For more information, seeInitialize the Google Cloud CLI.

That's it. You're ready to access protected data. To see a listing of gsutilcommands, typegsutil at the command prompt.

Troubleshooting

If you try to authenticate gsutil using thegcloud init command, but are stillnot able to access the expected buckets or objects, your system might have boththe legacy, stand-alone version of gsutil and the Google Cloud CLI-bundledversion of gsutil installed on it. Run the commandgsutil version -l and checkthe value forusing cloud sdk. IfFalse, your system is using thestand-alone version of gsutil when you run commands. It's recommended that youremove the stand-alone version of gsutil from your system; however, you canalternatively authenticate usinggsutil config -a orgsutil config -e.

Authenticate with HMAC

While OAuth 2.0 is the recommended way to authenticate gsutil, you can alsouseHMAC keys for your credentials. To authenticate with HMAC,use the following command:

gsutil config -a

Using this command takes you through an authentication process in which you areprompted for theaccess ID andsecret associated with your HMAC key.

When authenticating with HMAC keys, you should disable credential passing fromthe Google Cloud CLI by using the command:gcloud config set pass_credentials_to_gsutil false.

Enable mTLS

You might also want to enable mutual TLS (mTLS). When mTLS is enabled on yourdevice, your device attempts to connect to themTLS request endpoint forthe JSON API. Before the connection is allowed, Cloud Storage verifiesthe certificate on your device.

Note: This feature only works when gsutil makes requests through theCloud Storage JSON API.

The simplest way to to obtain a certificate is throughGoogle Cloud CLI.You can set one manually in the.boto file by setting the followingvalues under "Credentials":

  1. use_client_certificate: A flag controlling whether or not to use mTLS.
  2. cert_provider_command: A shell command that prints a certificate to stdout for gsutil to read.

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how Cloud Storage performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Try Cloud Storage free

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.