En esta página se describe la instalación y la configuración de gsutil, una herramienta que te permite acceder a Cloud Storage desde la línea de comandos mediante HTTPS.
Instalar gsutil proporciona acceso inmediato a los datos públicos, lo que le permite leer y escribir según lo permitido. Para interactuar con los datos protegidos que se han compartido contigo, debes autenticarte en el servicio Cloud Storage. Si habilitas la facturación, podrás crear y gestionar tus propios contenedores.
Requisitos del sistema
La herramienta gsutil se ejecuta en Linux/Unix, Mac OS y Windows (XP o versiones posteriores).
Las versiones 5.35 o posteriores de gsutil requieren Python 3.9 a 3.13, que puedes obtener mediante tu gestor de versiones de Python o instalando una versión adecuada.
A continuación, se explica cómo gestionar las versiones de Python:
Requisitos previos: instala un gestor de versiones de Python (pyenv) e instala una versión de Python adecuada.
-
Establece la versión global de Python:
-
Para definir Python 3.13 como la versión global, sigue estos pasos:
pyenv global 3.13
-
También puedes definir la versión de Python localmente para una carpeta de proyecto específica:
pyenv local 3.13
-
Para definir Python 3.13 como la versión global, sigue estos pasos:
-
Confirma que se está usando la versión correcta de Python:
python --version
Deberías ver lo siguiente:
Python 3.13
Método 1: Usar Homebrew (brew)
Requisitos previos: instala Homebrew e instala una versión de Python adecuada a través de Homebrew.
-
Establece una versión específica de Python como predeterminada:
-
Añada la versión que quiera a su archivo
$PATH. Por ejemplo, para usar Python 3.13:export PATH="/usr/local/opt/python@3.13/bin:$PATH"
-
Para que este cambio sea permanente, añade la ruta al archivo de configuración de tu shell (
~/.bash_profile,~/.zshrco~/.bashrc).
-
Añada la versión que quiera a su archivo
-
Confirma que se está usando la versión correcta de Python:
python --version
Deberías ver lo siguiente:
Python 3.13
Método 2: Usar pyenv
Requisitos previos: instala el gestor de versiones de Python (pyenv) e instala una versión de Python adecuada a través de pyenv.
-
Establece la versión global de Python:
-
Para definir la versión de Python de forma global (para todas las terminales), sigue estos pasos:
pyenv global 3.13
-
También puedes definir la versión de Python localmente para una carpeta de proyecto específica:
pyenv local 3.13
-
Para definir la versión de Python de forma global (para todas las terminales), sigue estos pasos:
-
Confirma que se está usando la versión correcta de Python:
python --version
Deberías ver lo siguiente:
Python 3.13
Requisitos previos: instala el gestor de versiones de Python (pyenv-win) e instala una versión de Python adecuada a través de pyenv.
-
Establece la versión global de Python:
-
Para definir Python 3.13 como la versión global, sigue estos pasos:
pyenv global 3.13
-
También puedes definir la versión de Python localmente para una carpeta de proyecto específica:
pyenv local 3.13
-
Para definir Python 3.13 como la versión global, sigue estos pasos:
-
Confirma que se está usando la versión correcta de Python:
python --version
Deberías ver lo siguiente:
Python 3.13
- Si tienes previsto usar objetos compuestos, debes instalar crcmod compilado. En Windows, esta opción solo está disponible para Python de 32 bits. Para obtener más información sobre crcmod, instala gsutil y consulta el tema de ayuda con el comando
gsutil help crc32c.
Instalar gsutil
El método de instalación y actualización oficialmente admitido para gsutil es como parte de Google Cloud CLI.
Antes de empezar
La CLI de Google Cloud y gsutil tienen dependencias de la versión de Python que pueden causar problemas de compatibilidad. La CLI de Google Cloud requiere Python 3.9 a 3.14, mientras que gsutil requiere Python 3.9 a 3.13.Para instalar gsutil, te recomendamos que lo instales como parte de la CLI de Google Cloud. Si decides instalar gsutil directamente, usa Python 3.9 a 3.13 para evitar problemas de compatibilidad.
Instalar gsutil como parte de Google Cloud CLI
Sigue las instrucciones correspondientes a tu sistema operativo para instalar gsutil como parte de Google Cloud CLI:
- Confirma que tienes una versión compatible de Python. Google Cloud CLI requiere Python 3.9 a 3.14. El paquete de Linux x86_64 incluye
un intérprete de Python empaquetado que se usará de forma predeterminada. Para obtener información sobre cómo elegir y configurar tu intérprete de Python, consulta la documentación de
gcloud topic startup. - Descarga una de las siguientes opciones:
Plataforma Nombre del paquete Tamaño Suma de comprobación 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 descargar el archivo Linux, ejecuta el siguiente comando:
curl -O https://storage.s3nsapis.fr/cloud-sdk-release/google-cloud-cli-linux-x86_64.tar.gz
Consulta la tabla de arriba y sustituye google-cloud-cli-linux-x86_64.tar.gz por el nombre del paquete
*.tar.gzque corresponda a tu configuración. - Para extraer el contenido del archivo en tu sistema de archivos, ejecuta el siguiente comando:
Para sustituir una instalación, elimina el directoriotar -xf google-cloud-cli-linux-x86_64.tar.gz
google-cloud-sdky, a continuación, extrae el archivo en la misma ubicación. - Ejecuta la secuencia de comandos de instalación desde la raíz de la carpeta que has extraído:
El script te pedirá que realices las siguientes acciones de configuración. Para aceptar, responde./google-cloud-sdk/install.sh
Ycuando se te solicite.- Añade gcloud CLI a tu
PATH. - Habilita la finalización de comandos.
- Acepta enviar estadísticas de uso anónimas para ayudar a mejorar gcloud CLI.
./google-cloud-sdk/install.sh --help - Añade gcloud CLI a tu
- Opcional: Si has actualizado tu
PATHen el paso anterior, abre una nueva terminal para que los cambios surtan efecto.
Contenido del paquete
La CLI de gcloud está disponible en formato de paquete para instalarla en sistemas Debian y Ubuntu. Este paquete solo contiene las herramientas de línea de comandos gcloud, gcloud alpha, gcloud beta, gsutil y bq. No incluye kubectl ni las extensiones de App Engine necesarias para desplegar una aplicación mediante comandos de gcloud. Si quieres usar estos componentes, debes instalarlos por separado.
Antes de empezar
Antes de instalar la CLI de gcloud, comprueba que tu sistema operativo cumpla los siguientes requisitos:
- Se trata de una versión de Ubuntu que no ha alcanzado el fin de su ciclo de vida o de una versión estable de Debian que no ha alcanzado el fin de su ciclo de vida.
- Ha actualizado recientemente sus paquetes. Para hacerlo ahora, ejecuta el siguiente comando:
sudo apt-get update
- Tiene instaladas las aplicaciones
apt-transport-https,ca-certificates,gnupgycurl. Para instalar estos paquetes, ejecuta el siguiente comando:sudo apt-get install apt-transport-https ca-certificates gnupg curl
Instalación
- Importa la Cloud de Confiance by S3NS clave pública.
En distribuciones más recientes (Debian 9 o Ubuntu 18.04 y versiones posteriores), ejecuta el siguiente comando:
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
- En distribuciones anteriores, ejecuta el siguiente comando:
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -
Si el comando apt-key de tu distribución no admite el argumento
--keyring, ejecuta el siguiente comando:curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
Si no puedes obtener las últimas actualizaciones debido a que una clave ha caducado, obtén el archivo de clave apt-get.gpg más reciente.
- Añade el URI de distribución de gcloud CLI como fuente de paquetes.
- En distribuciones más recientes (Debian 9 o Ubuntu 18.04, o versiones posteriores), ejecuta el siguiente 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
En las distribuciones anteriores que no admiten la opción signed-by, ejecuta el siguiente comando:
echo "deb https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
- En distribuciones más recientes (Debian 9 o Ubuntu 18.04, o versiones posteriores), ejecuta el siguiente comando:
- Actualiza e instala gcloud CLI:
Para ver más opciones desudo apt-get update && sudo apt-get install google-cloud-cli
apt-get, como inhabilitar las peticiones o hacer pruebas, consulta las páginas del manual deapt-get.Consejo sobre Docker: Si vas a instalar la CLI de gcloud en una imagen de Docker, usa un solo paso RUN:
En el caso de las imágenes base antiguas que no admiten el comandoRUN 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
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
- Opcional: Instala cualquiera de los siguientes
componentes adicionales:
google-cloud-cli-anthos-authgoogle-cloud-cli-app-engine-gogoogle-cloud-cli-app-engine-grpcgoogle-cloud-cli-app-engine-javagoogle-cloud-cli-app-engine-pythongoogle-cloud-cli-app-engine-python-extrasgoogle-cloud-cli-bigtable-emulatorgoogle-cloud-cli-cbtgoogle-cloud-cli-cloud-build-localgoogle-cloud-cli-cloud-run-proxygoogle-cloud-cli-config-connectorgoogle-cloud-cli-datastore-emulatorgoogle-cloud-cli-firestore-emulatorgoogle-cloud-cli-gke-gcloud-auth-plugingoogle-cloud-cli-kptgoogle-cloud-cli-kubectl-oidcgoogle-cloud-cli-local-extractgoogle-cloud-cli-minikubegoogle-cloud-cli-nomosgoogle-cloud-cli-pubsub-emulatorgoogle-cloud-cli-skaffoldgoogle-cloud-cli-spanner-emulatorgoogle-cloud-cli-terraform-validatorgoogle-cloud-cli-testskubectl
Por ejemplo, el componente
google-cloud-cli-app-engine-javase puede instalar de la siguiente manera:sudo apt-get install google-cloud-cli-app-engine-java
-
Ejecuta
gcloud initpara inicializar, autorizar y configurar gcloud CLI.
Revertir a versiones anteriores de gcloud CLI
Para volver a una versión específica de la CLI de gcloud, donde VERSION tiene el formato 123.0.0, ejecuta el siguiente comando:
sudo apt-get update && sudo apt-get install google-cloud-cli=123.0.0-0
Las diez versiones más recientes están siempre disponibles en el repositorio. En las versiones anteriores a la 371.0.0,
el nombre del paquete es google-cloud-sdk
Contenido del paquete
La CLI de gcloud está disponible en formato de paquete para instalarse en sistemas Red Hat Enterprise Linux 7, 8, 9 y 10; Fedora 41 y 42; y CentOS 7 y 8.
Este paquete solo contiene los comandos gcloud, gcloud alpha, gcloud beta, gsutil y bq. No incluye kubectl ni las extensiones de App Engine
necesarias para desplegar una aplicación con comandos de gcloud, que se pueden
instalar por separado, como se describe más adelante en esta sección.
Instalación
- Actualiza DNF con la información del repositorio de gcloud CLI.
-
El siguiente comando de ejemplo es para instalaciones compatibles con Red Hat Enterprise Linux 7, 8 o 9, pero asegúrate de actualizar los ajustes según sea necesario para tu configuración:
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 las instalaciones compatibles con RHEL 10, usa el siguiente comando con el
gpgkeyactualizado: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
-
-
Instala
libxcrypt-compat.x86_64.sudo dnf install libxcrypt-compat.x86_64
- Instala gcloud CLI:
sudo dnf install google-cloud-cli
- Opcional: Instala cualquiera de los siguientes componentes adicionales:
google-cloud-cli-anthos-authgoogle-cloud-cli-app-engine-gogoogle-cloud-cli-app-engine-grpcgoogle-cloud-cli-app-engine-javagoogle-cloud-cli-app-engine-pythongoogle-cloud-cli-app-engine-python-extrasgoogle-cloud-cli-bigtable-emulatorgoogle-cloud-cli-cbtgoogle-cloud-cli-cloud-build-localgoogle-cloud-cli-cloud-run-proxygoogle-cloud-cli-config-connectorgoogle-cloud-cli-datastore-emulatorgoogle-cloud-cli-firestore-emulatorgoogle-cloud-cli-gke-gcloud-auth-plugingoogle-cloud-cli-kptgoogle-cloud-cli-kubectl-oidcgoogle-cloud-cli-local-extractgoogle-cloud-cli-minikubegoogle-cloud-cli-nomosgoogle-cloud-cli-pubsub-emulatorgoogle-cloud-cli-skaffoldgoogle-cloud-cli-spanner-emulatorgoogle-cloud-cli-terraform-validatorgoogle-cloud-cli-testskubectl
Por ejemplo, para instalar el componente
google-cloud-cli-app-engine-java, ejecuta el siguiente comando:sudo dnf install google-cloud-cli-app-engine-java
-
Ejecuta
gcloud initpara inicializar, autorizar y configurar gcloud CLI.
Revertir a versiones anteriores de gcloud CLI
Para volver a una versión específica de gcloud CLI, ejecuta el siguiente comando. Sustituye 123.0.0 por la versión que quieras instalar:
sudo dnf downgrade google-cloud-cli-123.0.0
Las diez versiones más recientes están disponibles en el repositorio. En las versiones anteriores a la 371.0.0, usa google-cloud-sdk como nombre de paquete.
- Confirma que tienes una versión compatible de Python. Google Cloud CLI requiere Python 3.9 a 3.14.
Para comprobar tu versión de Python, ejecuta
python3 -Vopython -V.La secuencia de comandos de instalación puede instalar Python por ti si es necesario. Para ello, necesitas las herramientas de línea de comandos de Xcode. Para instalarlos, ejecuta
sudo xcode-select --install. También puedes instalar una versión compatible de Python desde python.org.Para obtener más información sobre cómo configurar tu intérprete de Python, sobre todo si tienes varias versiones instaladas, consulta la documentación de
gcloud topic startup. -
Descarga uno de los siguientes:
Plataforma Paquete Tamaño Suma de comprobación 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 También puedes descargar el archivo desde la línea de comandos. Sustituye
FILE_NAMEpor el nombre del paquete de tu plataforma de la tabla anterior.curl -O https://storage.s3nsapis.fr/cloud-sdk-release/FILE_NAME
- Extrae el contenido del archivo en la ubicación que prefieras de tu sistema de archivos. Lo habitual es extraerlo al directorio principal.
En macOS, puedes hacerlo abriendo el archivo
.tar.gzdescargado en la ubicación que prefieras. También puede ejecutar el siguiente comando desde la línea de comandos:tar -xf FILE_NAME
Para sustituir una instalación, elimina el directorio
google-cloud-sdky, a continuación, extrae el archivo en la misma ubicación. - Ejecuta la secuencia de comandos de instalación desde la raíz de la carpeta que has extraído:
El script te pedirá que realices las siguientes acciones de configuración. Para aceptar, responde./google-cloud-sdk/install.sh
Ycuando se te solicite.- Instala Python 3.13 y los módulos recomendados si es necesario.
- Añade la CLI de gcloud a tu
PATHy habilita la función de autocompletar comandos. - Acepta enviar estadísticas de uso anónimas para ayudar a mejorar gcloud CLI.
Para ejecutar la secuencia de comandos de instalación con el modo Lector de pantalla habilitado, sigue estos pasos:./google-cloud-sdk/install.sh --help./google-cloud-sdk/install.sh --screen-reader=true
- Opcional: Si has actualizado tu
PATHen el paso anterior, abre una nueva terminal para que los cambios surtan efecto.
La CLI de Google Cloud en Windows requiere Windows 8.1 o una versión posterior, o Windows Server 2012 o una versión posterior.
-
Descarga el instalador de Google Cloud CLI.
También puedes abrir un terminal de PowerShell y ejecutar los siguientes comandos de PowerShell:
(New-Object Net.WebClient).DownloadFile("https://storage.s3nsapis.fr/cloud-sdk-release/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe") & $env:Temp\GoogleCloudSDKInstaller.exe
-
Inícialo y sigue las instrucciones. El instalador está firmado por Google LLC.
- Si usas un lector de pantalla, marca la casilla Activar el modo de lector de pantalla. Esta opción configura
gcloudpara que use indicadores de estado en lugar de spinners Unicode, muestre el progreso como un porcentaje y acople las tablas. Para obtener más información, consulta la guía de funciones de accesibilidad. - Google Cloud CLI requiere Python. Las versiones compatibles son de Python 3.9 a 3.14. De forma predeterminada, la versión de Windows de Google Cloud CLI incluye Python 3. Para usar la CLI de Google Cloud, tu sistema operativo debe poder ejecutar una versión compatible de Python.
- El instalador instala todas las dependencias necesarias, incluida la versión de Python que se necesita.
Aunque la CLI de Google Cloud instala y gestiona Python 3 de forma predeterminada, puedes usar una instalación de Python que ya tengas si es necesario. Para ello, desmarca la opción Instalar Python incluido.
Consulta
gcloud topic startuppara obtener información sobre cómo usar una instalación de Python.
- Si usas un lector de pantalla, marca la casilla Activar el modo de lector de pantalla. Esta opción configura
- Una vez completada la instalación, el instalador te ofrece la opción de crear accesos directos en el menú Inicio y en el escritorio, iniciar el shell de la CLI de Google Cloud y configurar la CLI de gcloud. Deje seleccionadas las opciones para iniciar el shell y configurar la instalación. El instalador inicia una ventana de terminal y ejecuta el comando
gcloud initpara inicializar, autorizar y configurar gcloud CLI. - La instalación predeterminada no incluye las extensiones de App Engine necesarias para desplegar una aplicación mediante comandos
gcloud. Estos componentes se pueden instalar con el gestor de componentes de gcloud CLI.
Consejos para solucionar problemas
- Si la instalación no se realiza correctamente porque no se reconoce el comando
find, asegúrate de que la variable de entornoPATHincluya la carpeta que contienefind. Por lo general, esC:\WINDOWS\system32;. - Si has desinstalado gcloud CLI, debes reiniciar el sistema antes de volver a instalarla.
- Si la descompresión falla, ejecuta el instalador como administrador.
Como parte de la instalación de gsutil, debes definir la variable de entorno CLOUDSDK_PYTHON para usar la versión correcta de Python. Para obtener más información, consulta la gcloud startup topic.
Realiza las actualizaciones con el comando components update: gcloud components update.
Configurar credenciales para acceder a datos protegidos
Para acceder a datos protegidos o escribir en un contenedor protegido, debes configurar las credenciales (autenticarte). Por ejemplo, si otra persona ha creado una cuenta de Cloud Storage y ha subido datos a los que solo puedes acceder tú u otras personas concretas, debes configurar tus credenciales en el servicio Cloud Storage para poder acceder a esos datos.
Cuando se usa gsutil como parte de Google Cloud CLI, se utiliza OAuth2 para autenticar y autorizar el acceso a los recursos de Cloud Storage. Para establecer el acceso, ejecuta el comando gcloud init y sigue las instrucciones que se indican en la línea de comandos, que incluyen iniciar sesión en tu cuenta de usuario. Ten en cuenta que es probable que ya hayas realizado esta configuración si has seguido los pasos de instalación. Si ya has ejecutado gcloud init anteriormente, cuando vuelvas a ejecutar el comando, se te preguntará si quieres reinicializar la configuración o crear una nueva. Para obtener más información, consulta Inicializar Google Cloud CLI.
Eso es todo. Ya puedes acceder a los datos protegidos. Para ver una lista de comandos de gsutil, escribe gsutil en la petición de comandos.
Solución de problemas
Si intentas autenticar gsutil con el comando gcloud init, pero sigues sin poder acceder a los objetos o los contenedores esperados, es posible que tu sistema tenga instaladas tanto la versión antigua independiente de gsutil como la versión de gsutil incluida en la CLI de Google Cloud. Ejecuta el comando gsutil version -l y comprueba el valor de using cloud sdk. Si False, tu sistema está usando la versión independiente de gsutil cuando ejecutas comandos. Te recomendamos que elimines la versión independiente de gsutil de tu sistema. Sin embargo, también puedes autenticarte con gsutil config -a o gsutil config -e.
Autenticarse con HMAC
Aunque OAuth 2.0 es el método recomendado para autenticar gsutil, también puedes usar claves HMAC para tus credenciales. Para autenticarte con HMAC, usa el siguiente comando:
gsutil config -a
Al usar este comando, se te guiará por un proceso de autenticación en el que se te pedirá el ID de acceso y el secreto asociados a tu clave HMAC.
Cuando te autentiques con claves HMAC, debes inhabilitar la transferencia de credenciales desde la CLI de Google Cloud mediante el siguiente comando:
gcloud config set pass_credentials_to_gsutil false.
Habilitar mTLS
También puedes habilitar TLS mutuo (mTLS). Cuando mTLS está habilitado en tu dispositivo, este intenta conectarse al endpoint de solicitud mTLS de la API JSON. Antes de permitir la conexión, Cloud Storage verifica el certificado de tu dispositivo.
La forma más sencilla de obtener un certificado es a través de la CLI de Google Cloud. Puedes definir uno manualmente en el archivo .boto. Para ello, define los siguientes valores en "Credentials":
-
use_client_certificate: una marca que controla si se debe usar mTLS o no. -
cert_provider_command: un comando de shell que imprime un certificado en stdout para que lo lea gsutil.