{"id":4032,"library":"gsutil","title":"gsutil","description":"gsutil is a Python application that serves as a command-line tool for interacting with Google Cloud Storage. It allows users to perform a wide range of bucket and object management tasks, such as creating and deleting buckets, uploading, downloading, and deleting objects, and managing ACLs. While `gsutil` is functional and widely documented, Google now recommends using `gcloud storage` commands from the Google Cloud CLI for Cloud Storage interactions due to better performance and support for newer features. The current version is 5.36, and it sees regular maintenance releases.","status":"maintenance","version":"5.36","language":"en","source_language":"en","source_url":"https://github.com/GoogleCloudPlatform/gsutil","tags":["google cloud","cloud storage","cli","command-line","gcs"],"install":[{"cmd":"pip install gsutil","lang":"bash","label":"Install via pip (Note: Google recommends installing via Google Cloud SDK)"},{"cmd":"gcloud components install gsutil","lang":"bash","label":"Recommended: Install as part of Google Cloud CLI"}],"dependencies":[{"reason":"Official Python client library for programmatic interaction with Google Cloud Storage, recommended over direct gsutil calls from Python.","package":"google-cloud-storage","optional":true},{"reason":"Required for integrity checks.","package":"crcmod","optional":false},{"reason":"Google API client library dependencies.","package":"google-apitools","optional":false},{"reason":"Google authentication library dependencies.","package":"google-auth","optional":false}],"imports":[],"quickstart":{"code":"import subprocess\nimport os\n\n# Ensure gcloud is authenticated (e.g., via `gcloud auth login` in terminal)\n# For programmatic use, consider setting GOOGLE_APPLICATION_CREDENTIALS\n# os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = '/path/to/keyfile.json'\n\nbucket_name = os.environ.get('GSUTIL_TEST_BUCKET', 'my-test-bucket-12345')\nfile_name = 'test_file.txt'\nfile_content = 'Hello, Cloud Storage!'\n\n# Create a local file to upload\nwith open(file_name, 'w') as f:\n    f.write(file_content)\n\ntry:\n    # Create a bucket\n    print(f\"Creating bucket gs://{bucket_name}...\")\n    subprocess.run(['gsutil', 'mb', f'gs://{bucket_name}'], check=True, capture_output=True)\n    print(f\"Bucket gs://{bucket_name} created.\")\n\n    # Upload a file\n    print(f\"Uploading {file_name} to gs://{bucket_name}/{file_name}...\")\n    subprocess.run(['gsutil', 'cp', file_name, f'gs://{bucket_name}/{file_name}'], check=True, capture_output=True)\n    print(\"File uploaded.\")\n\n    # List bucket contents\n    print(f\"Listing contents of gs://{bucket_name}:\")\n    result = subprocess.run(['gsutil', 'ls', f'gs://{bucket_name}'], check=True, capture_output=True, text=True)\n    print(result.stdout)\n\n    # Download the file\n    downloaded_file_name = 'downloaded_test_file.txt'\n    print(f\"Downloading gs://{bucket_name}/{file_name} to {downloaded_file_name}...\")\n    subprocess.run(['gsutil', 'cp', f'gs://{bucket_name}/{file_name}', downloaded_file_name], check=True, capture_output=True)\n    print(\"File downloaded.\")\n\n    with open(downloaded_file_name, 'r') as f:\n        content = f.read()\n        print(f\"Downloaded content: {content}\")\n\nexcept subprocess.CalledProcessError as e:\n    print(f\"gsutil command failed: {e}\")\n    print(f\"STDOUT: {e.stdout.decode()}\")\n    print(f\"STDERR: {e.stderr.decode()}\")\nfinally:\n    # Clean up (delete file and bucket)\n    print(f\"Cleaning up: deleting objects from gs://{bucket_name}...\")\n    subprocess.run(['gsutil', '-m', 'rm', '-r', f'gs://{bucket_name}/**'], check=False, capture_output=True)\n    print(f\"Deleting bucket gs://{bucket_name}...\")\n    subprocess.run(['gsutil', 'rb', f'gs://{bucket_name}'], check=False, capture_output=True)\n    print(\"Cleanup complete.\")\n    if os.path.exists(file_name):\n        os.remove(file_name)\n    if os.path.exists(downloaded_file_name):\n        os.remove(downloaded_file_name)\n","lang":"python","description":"This quickstart demonstrates how to interact with `gsutil` from Python by calling it as a subprocess. This is the common pattern for programmatic use, as `gsutil` is primarily a command-line interface. It includes creating a bucket, uploading a file, listing contents, downloading a file, and cleaning up resources."},"warnings":[{"fix":"Transition scripts and workflows to use `gcloud storage` commands. Refer to the 'Transition from gsutil to gcloud storage' documentation.","message":"`gsutil` is a legacy Cloud Storage CLI and minimally maintained. Google strongly recommends migrating to `gcloud storage` commands for all Cloud Storage interactions.","severity":"breaking","affected_versions":"All versions, as of March 2026. Explicitly noted from version 5.36 onwards."},{"fix":"For direct integration into Python applications, use the `google-cloud-storage` client library (e.g., `pip install google-cloud-storage`). If `gsutil` CLI functionality is strictly required, use Python's `subprocess` module to execute `gsutil` commands.","message":"There is no official Python client library for `gsutil` itself. Programmatic interaction from Python is typically achieved by invoking `gsutil` commands via `subprocess` calls. For a native Python API, use `google-cloud-storage`.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Ensure your environment uses a compatible Python version (3.9-3.13 for recent `gsutil` versions). Upgrade Python if necessary.","message":"`gsutil` dropped support for older Python versions. Versions 5.35 and later require Python 3.9 to 3.13.","severity":"breaking","affected_versions":"5.32 and later."},{"fix":"Thoroughly review and update any automated scripts that rely on parsing `gsutil` output if migrating to `gcloud storage`.","message":"Scripts that parse `gsutil` command output may break when transitioning to `gcloud storage` due to differences in output formatting, error messages, and data listings.","severity":"gotcha","affected_versions":"All versions, when considering migration."},{"fix":"For optimal performance with large transfers, especially for new projects, consider using `gcloud storage`. If sticking with `gsutil`, explore options like the `-m` (multi-threaded/multi-processing) flag for `cp` and `rsync` operations, or adjusting `parallel_process_count` and `parallel_thread_count` settings in the `.boto` configuration.","message":"When transferring a large number of files or large single files, `gsutil`'s performance might require manual optimization, whereas `gcloud storage` is engineered for speed by default.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}