gsutil 설치

이 페이지에서는 HTTPS를 사용하여 명령줄에서 Cloud Storage에 액세스할 수 있는 도구인 gsutil의 설치 및 설정을 설명합니다.

gsutil을 설치하면 공개 데이터에 대한 즉시 액세스가 가능하여 허용된 권한에 따라 읽기 및 쓰기를 수행할 수 있습니다. 내게 공유된 보호 데이터와 상호작용하기 위해서는 Cloud Storage 서비스에 대한 인증이 필요합니다. 결제를 사용 설정하면 버킷을 직접 만들고 관리할 수 있습니다.

시스템 요구사항

  • gsutil 도구는 Linux/Unix, Mac OS, Windows(XP 이상)에서 실행됩니다.

  • gsutil 버전 5.35 이상에는 Python 3.9~3.13이 필요하며, 이는 Python 버전 관리자를 사용하거나 적절한 버전을 설치하여 가져올 수 있습니다.

다음 안내에서는 Python 버전을 관리하는 방법을 보여줍니다.

Linux

기본 요건: Python 버전 관리자(pyenv)를 설치하고 적합한 Python 버전을 설치합니다.

  1. 글로벌 Python 버전을 설정합니다.
    • Python 3.13을 글로벌 버전으로 설정하려면 다음 단계를 따르세요. 
      pyenv global 3.13
    • 또는 특정 프로젝트 폴더의 Python 버전을 로컬에서 설정합니다. 
      pyenv local 3.13
  2. 올바른 Python 버전이 사용 중인지 확인합니다. 
    python --version

    다음과 같이 표시됩니다.

    Python 3.13
macOS

방법 1: Homebrew(brew) 사용

기본 요건: Homebrew를 설치하고 homebrew를 통해 적절한 Python 버전을 설치합니다.

  1. 특정 Python 버전을 기본값으로 설정합니다.
    • $PATH에 원하는 버전을 추가합니다. 예를 들어 Python 3.13을 사용하려면 다음 안내를 따르세요. 
      export PATH="/usr/local/opt/python@3.13/bin:$PATH"
    • 이 변경사항을 영구적으로 적용하려면 셸 구성 파일(~/.bash_profile, ~/.zshrc 또는 ~/.bashrc)의 경로를 추가합니다.
  2. 올바른 Python 버전이 사용 중인지 확인합니다. 
    python --version

    다음과 같이 표시됩니다.

    Python 3.13

방법 2: pyenv 사용

기본 요건: Python 버전 관리자(pyenv)를 설치하고 pyenv를 통해 적절한 Python 버전을 설치합니다.

  1. 글로벌 Python 버전을 설정합니다.
    • Python 버전을 전역적으로 설정하려면(모든 터미널에 적용) 다음 단계를 따르세요. 
      pyenv global 3.13
    • 또는 특정 프로젝트 폴더의 Python 버전을 로컬에서 설정합니다. 
      pyenv local 3.13
  2. 올바른 Python 버전이 사용 중인지 확인합니다. 
    python --version

    다음과 같이 표시됩니다.

    Python 3.13
Windows

기본 요건: Python 버전 관리자(pyenv-win)를 설치하고 pyenv를 통해 적절한 Python 버전을 설치합니다.

  1. 글로벌 Python 버전을 설정합니다.
    • Python 3.13을 글로벌 버전으로 설정하려면 다음 단계를 따르세요. 
      pyenv global 3.13
    • 또는 특정 프로젝트 폴더의 Python 버전을 로컬에서 설정합니다. 
      pyenv local 3.13
  2. 올바른 Python 버전이 사용 중인지 확인합니다. 
    python --version

    다음과 같이 표시됩니다.

    Python 3.13
  • 복합 객체를 사용하려면 컴파일된 crcmod를 설치해야 합니다. Windows에서는 32비트 Python용으로만 제공됩니다. crcmod에 대한 자세한 내용을 보려면 gsutil을 설치하고 gsutil help crc32c 명령어를 사용하여 도움말 항목을 참조하세요.

gsutil 설치

공식적으로 지원되는 gsutil의 설치 및 업데이트 방법은 Google Cloud CLI를 사용하는 것입니다.

시작하기 전에

Google Cloud CLI 및 gsutil에는 호환성 문제를 일으킬 수 있는 Python 버전 종속 항목이 포함됩니다. Google Cloud CLI에는 Python 3.9~3.14가 필요하지만 gsutil에는 Python 3.9~3.13이 필요합니다.

gsutil을 설치하려면 이를 Google Cloud CLI의 일부로 설치하는 것이 좋습니다. gsutil을 직접 설치할 경우에는 호환성 문제를 방지하기 위해 Python 3.9~3.13을 선택하세요.

Google Cloud CLI의 일부로 gsutil 설치

운영체제의 안내에 따라 gsutil을 Google Cloud CLI의 일부로 설치하세요.

Linux
  1. 지원되는 Python 버전이 있는지 확인합니다. Google Cloud CLI에는 Python 3.9~3.14가 필요합니다. x86_64 Linux 패키지에는 기본적으로 선호되는 번들 Python 인터프리터가 포함되어 있습니다. Python 인터프리터를 선택하고 구성하는 방법에 대한 자세한 내용은 gcloud topic startup를 참조하세요.
  2. 다음 중 하나를 다운로드합니다.
    플랫폼 패키지 이름 크기 SHA256 체크섬
    Linux 64비트

    (x86_64)

    		 google-cloud-cli-linux-x86_64.tar.gz 202.9MB 71a81b5391dbc0418ac767a8522d8eab92780d708cb1c2740160d137fbeb760a
    Linux 64비트

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 57.7MB 001c4adc88fe796a0c0a0db9771949947528c5066bc5c9f6b7240b5ef59ee0f3
    Linux 32비트

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 57.8MB 921b840acfbbb9cace1d696175aded8a891149ccfbab48e5aea11613bc4a31fc

    Linux 보관 파일을 다운로드하려면 다음 명령어를 실행합니다. 

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

    위 표를 참조하고 google-cloud-cli-linux-x86_64.tar.gz을 구성에 적용되는 *.tar.gz 패키지 이름으로 바꿉니다.

  3. 파일 콘텐츠를 파일 시스템(홈 디렉터리 추천)에 추출하려면 다음 명령어를 실행합니다. 
    tar -xf google-cloud-cli-linux-x86_64.tar.gz
     (선택사항) 기존 설치를 대체하려면 기존 google-cloud-sdk 디렉터리를 삭제하고 동일한 위치에 보관 파일 압축을 풉니다.
  4. (선택사항) PATH에 gcloud CLI를 추가합니다. 셸 및 사용 통계 수집에 명령어 완성 옵션을 선택할 수도 있습니다. 다음 명령어를 사용하여 설치 스크립트를 실행(마지막 단계에서 추출한 폴더의 루트에서)합니다. 
    ./google-cloud-sdk/install.sh
     이 경우 환경설정을 플래그로 제공하여 비대화형(예: 스크립트 사용)으로도 수행할 수 있습니다. 사용 가능한 플래그를 보려면 다음을 실행합니다. 
    ./google-cloud-sdk/install.sh --help
    • gcloud CLI 개선을 위해 익명 사용 통계를 보내려면 메시지가 표시될 때 Y로 응답합니다.
    • PATH에 gcloud CLI를 추가하고 명령어 완성을 사용 설정하려면 메시지가 표시될 때 Y로 응답합니다.
  5. 이전 단계에서 PATH를 업데이트한 경우 변경사항이 적용되도록 새 터미널을 엽니다.
  6. gcloud CLI를 초기화하려면 gcloud init를 실행합니다. 
    7. ./google-cloud-sdk/bin/gcloud init
  7. (선택사항) 구성요소 관리자를 사용하여 추가 구성요소를 설치합니다.
Debian/Ubuntu

패키지 콘텐츠

Debian 및 Ubuntu 시스템에서 gcloud CLI는 설치용 패키지 형식으로 제공됩니다. 이 패키지에는 gcloud, gcloud alpha, gcloud beta, gsutil, bq 명령어만 포함됩니다. gcloud 명령어를 사용하여 애플리케이션을 배포하는 데 필요한 kubectl 또는 App Engine 확장 프로그램은 포함되지 않습니다. 이러한 구성요소를 사용하려면 별도로 설치해야 합니다.

시작하기 전에

gcloud CLI를 설치하기 전 운영체제가 다음 요구사항을 충족하는지 확인합니다.

  • 지원 종료에 도달하지 않은 Ubuntu 출시 버전 또는 지원 종료에 도달하지 않은 Debian 안정적인 출시 버전
  • 패키지가 최근에 업데이트되었습니다. 
    sudo apt-get update
  • apt-transport-https가 있고 curl이 설치되어 있습니다. 
    sudo apt-get install apt-transport-https ca-certificates gnupg curl
설치
  1. Google Cloud 공개 키를 가져옵니다.

    • 최신 배포판(Debian 9+ 또는 Ubuntu 18.04+)의 경우 다음 명령어를 실행합니다.

      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
    • 이전 배포판의 경우 다음 명령어를 실행합니다. 
      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

    • 배포판의 apt-key 명령어가 --keyring 인수를 지원하지 않는 경우 다음 명령어를 실행합니다.

      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -

    • 키가 만료되어 최신 업데이트를 가져올 수 없는 경우에는 최신 apt-get.gpg 키 파일을 가져오세요.

  2. 패키지 소스로 gcloud CLI 배포 URI를 추가합니다.
    • 최신 배포판(Debian 9+ 또는 Ubuntu 18.04+)의 경우 다음 명령어를 실행합니다. 
      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

    • 서명 옵션을 지원하지 않는 이전 배포판의 경우에는 다음 명령어를 실행합니다.

      echo "deb https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
  3. gcloud CLI를 업데이트하고 설치합니다. 
    sudo apt-get update && sudo apt-get install google-cloud-cli
     프롬프트 사용 중지 또는 연습 실행과 같은 추가 apt-get 옵션에 대해서는 apt-get 메인 페이지를 참조하세요.

    Docker 팁: Docker 이미지 내에 gcloud CLI를 설치하는 경우 대신 단일 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
    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