gsutil: the legacy Cloud Storage CLI that Google tells you to replace

The README starts with a warning

The first line of the gsutil README is a notice, not an introduction. It says in bold that gsutil is not the recommended CLI for Cloud Storage, and points to the gcloud storage commands in the Google Cloud CLI instead.

Three bullets explain why. The gsutil tool is a legacy Cloud Storage CLI and minimally maintained. It does not support working with newer Cloud Storage features, such as soft delete and managed folders. And the gcloud storage commands require less manual optimization in order to achieve the fastest upload and download rates.

That framing changes what this repository is. It is not the current recommended tool that a new user should reach for, and the vendor says so plainly. The questions for an engineer are therefore not whether gsutil is good, but where it still has a job.

The answer is in the third bullet, and it is a real one. Upload and download rate tuning is a domain where the older tool has accumulated hard-won knobs, and the newer gcloud commands assume you do not need them. A team moving terabytes between a local machine and a bucket may find that the gcloud path is simpler but slower unless they tune it, and that the choice is not as clear-cut as the README's first line suggests.

Everything else in this article should be read with that notice attached.

What gsutil still does

gsutil is a Python application that lets you access Google Cloud Storage from the command line. The README lists the task surface, and it is broad. You can create and delete buckets, upload, download and delete objects, list buckets and objects, move, copy and rename objects, and edit object and bucket ACLs.

That last item is worth pausing on. ACL editing is not just another verb; it reflects an era of Cloud Storage access control in which bucket and object permissions were set on the objects themselves, and it is the kind of capability that disappears from new tools when the platform moves towards uniform bucket-level access and IAM roles. Its presence in the feature list tells you which generation of Cloud Storage this tool belongs to.

The same is true of the renaming and moving verbs. Renaming an object in Cloud Storage is a copy plus a delete, which has cost implications in a bucket with versioning or with many objects. A tool that exposes rename as a first-class operation is optimising for a workflow where people move things around, and that workflow is still common in data engineering tasks even though the storage platform itself has not moved on.

The tool is also self-documenting at runtime. The README says to run the gsutil help command for a list of the built-in help topics, and the help pages are also browsable online. For a tool in maintenance mode, having a complete offline reference is worth more than it would be for a fast-moving project.

The dependency list dates the codebase

The setup.py file for gsutil is the most revealing artefact in the repository, because it names the entire dependency set in one block:

requires = [
    'argcomplete>=3.6.2',
    'crcmod>=1.7',
    'fasteners>=0.14.1',
    'gcs-oauth2-boto-plugin>=3.3',
    'google-apitools>=0.5.32',
    'httplib2==0.20.4',
    'google-reauth>=0.1.0',
    'mock>=2.0.0, <=3.0.5; python_version < "3.3"',
    'monotonic>=1.4',
    'pyOpenSSL>=0.13, <=26.4.0',
    'retry_decorator>=1.0.0',
    'six>=1.17.0',
]

gcs-oauth2-boto-plugin and google-apitools are the tells. This tool is built on the boto-era Python libraries that Google Cloud Storage clients used before the modern client libraries, with google-reauth handling credential refresh and httplib2 providing the HTTP transport.

Two pins stand out. httplib2 is pinned exactly, at 0.20.4, with no version range at all, which is the signature of a project that cannot absorb a breaking change in its HTTP layer. pyOpenSSL is capped at 26.4.0 with an upper bound. Both are the shape of a maintenance freeze: the dependencies move forward when they must and not before.

The mock constraint carries a comment explaining that mock is part of the standard library in Python 3.3 onwards, and that 3.0.5 is the last version supporting Python 3.3 or lower. That comment describes a codebase that still carries compatibility paths for Python versions long out of support, which is normal for a tool with a very large installed base and a burden for anyone trying to run it in a modern, pinned environment.

How the gcloud path differs

The README does not enumerate every difference between gsutil and the gcloud storage commands, which is itself a point: the migration is documented elsewhere, in the Cloud Storage documentation, and in the repository itself.

The repository top level contains a file called GCLOUD-MIGRATION.md, which is the artefact to read before planning a move. It sits next to CHANGES.md, which records the release history of gsutil itself, and CONTRIBUTING.md with the contribution guidance. The README separately points to the contributing documentation page for best practices on how to contribute code changes to the gsutil repository.

What the README does state about the difference is a rate argument and a feature-coverage argument. On features, gsutil does not support newer Cloud Storage features such as soft delete and managed folders, and those are exactly the capabilities that change the shape of a retention policy or a bucket layout. On rates, gcloud storage commands require less manual optimization to achieve the fastest upload and download rates, which implies that gsutil can be faster for someone who knows how to configure it, and slower for someone who does not.

For a team doing the migration, that produces a concrete checklist rather than a slogan: for each script that calls gsutil, find the gcloud storage equivalent, check whether the operation touches soft delete or managed folders, and check whether any throughput tuning was tuned into the original invocation.

Repository layout: gslib, third_party and a CHECKSUM

The top level entries describe a Python project with a vendored dependency story. There is gslib/ for the package itself, gsutil.py and a gsutil entry script at the root, setup.py, MANIFEST.in for packaging, a third_party/ directory, and a .gitmodules file.

The .gitmodules and third_party/ combination is the old pattern for pinning third-party code as submodules, so that the released tarball carries a known copy of each dependency rather than resolving them at install time. It works, and it works at the cost of carrying the maintenance burden of those pins yourself.

Two other files tell you something. There is a CHECKSUM file at the top level, which is how a distribution records the integrity of the artefacts it ships, and a VERSION file, which is where the tool keeps its version. The presence of both, alongside CHANGES.md, is the shape of a project that packages releases as tarballs rather than as tagged GitHub releases. The repository has no GitHub releases at all, so the version information for a given installation lives in the installed tree rather than in a release history you can browse.

The development tooling is old-school as well. There is a .style.yapf and a .yapfignore, which means the code is formatted with yapf rather than with black, and the test/ directory holds the test suite. For a project that receives occasional patches rather than regular ones, this is a coherent choice: the tooling does not churn, and the code diffs stay small.

Licence, maintenance status and who should still be using it

The licence field on the repository says Apache-2.0, and the setup.py header carries the standard Apache 2.0 boilerplate with the copyright line for Google Inc. The dependency list is the other licensing surface: gcs-oauth2-boto-plugin, google-apitools, httplib2, google-reauth, crcmod, fasteners, retry_decorator, monotonic, six and argcomplete each carry their own terms, and a redistributed gsutil tarball inherits those obligations alongside the Apache grant on gsutil itself.

On maintenance, the facts are narrow. The repository is not archived, and the last push was on 2026-10-06. There are no GitHub releases, so there is no tag list to consult, and the README's own word for the project is minimally maintained. What that means in practice is that bugs that already exist may be fixed when someone cares enough, and features will not arrive.

So who should still be running it. The short answer is anyone who already has it, because a working script that calls gsutil is not improved by a migration notice, and the migration itself has a cost measured in engineer hours and in behavioural differences. The README's advice is aimed at new work, and for new work it is clear enough to follow.

The longer answer is that the interesting question is not gsutil versus gcloud, but where the vendor is heading. The tool does not support soft delete or managed folders, which means it cannot express the newer retention and organisation models of Cloud Storage at all. As more of the platform's behaviour moves into features gsutil cannot reach, the gap between the two tools widens rather than narrows.

Editorial conclusion

gsutil suits an engineer with existing scripts and runbooks that call gsutil and who needs those to keep working, or who needs a specific capability that the migration path has not covered. It does not suit a new project, since the vendor's own README tells you to use gcloud storage commands, and it does not suit anyone whose work depends on soft delete or managed folders, which the tool does not support. Before adopting, read GCLOUD-MIGRATION.md in the repository, run gsutil help on an existing machine to see what your current scripts actually use, and confirm that the gcloud storage equivalent of each command behaves the same for your access patterns and IAM roles.

Frequently asked questions

Official sources

1. GoogleCloudPlatform/gsutil on GitHub
2. Issues
3. License: Apache-2.0
4. README