google-api-python-client: The Discovery Client Google Now Calls Maintenance Mode

What google-api-python-client Is For, and Who Should Still Reach For It

Google publishes hundreds of HTTP APIs, and most of them are described by a discovery document: a JSON description of the service's resources, methods, parameters and scopes. google-api-python-client reads those documents and builds a Python object model at runtime, so one installed package can talk to Calendar, Drive, YouTube, Compute and the rest without a separate hand-written client for each. That is the problem it solves. You do not want to hand-roll URL construction, OAuth plumbing and request serialization for an API you touch twice a month.

The audience is narrow and specific. It fits scripts and internal tools that call one or two Google APIs, migration work on code that already imports googleapiclient, and any API that has no dedicated Cloud Client Library. It does not fit a team starting fresh on an API that does have one. The README is explicit on that point: the maintainers "recommend using Cloud Client Libraries for Python, where possible, for new code development." The same README states the library "is considered complete and is in maintenance mode," meaning critical bugs and security issues get attention but no new features arrive. The repository has not been archived, and the last push was on 2026-09-15, so the maintenance is real and current rather than abandoned. Maintenance mode plus weekly releases is an unusual combination, and it is worth reading carefully: the release cadence exists to keep discovery documents fresh, not to grow the API surface.

How discovery.build() Works and Why v2 Changed the Data Flow

In version 1.x, calling discovery.build() fetched the discovery document over the network at that moment. Version 2.0 moved the documents inside the package. The README describes this as "a substantial reliability improvement" and states that discovery documents "will no longer be retrieved dynamically when you call discovery.build()." They come from the client library directly. The consequence is stated just as plainly: because the documents are cached in the package, the installed size is "at least 50 MB larger compared to the previous version."

That trade is the whole architecture in one sentence. You give up a small install for a build step that does not depend on a network round trip to Google's discovery endpoint, and you accept that the documents you have are the ones that shipped with your installed version. The repository layout reflects the split: the top level holds both apiclient/ and googleapiclient/, with googleapiclient/discovery_cache/ as its own package in setup.py. The README says new versions are released weekly, which is how the bundled documents stay current. If you pin an old version and an API changes its surface, your generated client will not know about the new fields until you upgrade. That is a real operational constraint, not a theoretical one.

Underneath, the dependency list in setup.py tells you what actually performs the HTTP work: httplib2 between 0.19.0 and 1.0.0, google-auth between 1.32.0 and 3.0.0 with 2.24.0 and 2.25.0 excluded, google-auth-httplib2, google-api-core, and uritemplate. Credentials come from google-auth, transport from httplib2, URL templates from uritemplate. The exclusions in the google-auth range are worth noticing if you already pin google-auth elsewhere in the same environment.

Installing google-api-python-client and Making a First Call

The README recommends a virtualenv rather than a system install, on the grounds that it avoids dependency clashes and system permissions. On Mac and Linux the sequence is three commands. The first installs virtualenv itself, the second creates an environment in a directory you choose, and the third activates it.

pip3 install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install google-api-python-client

On Windows the README gives the equivalent with different paths. Note that the last line invokes pip.exe from the environment's Scripts directory rather than relying on an activated shell.

pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install google-api-python-client

After installation, the package name you import is googleapiclient, and the module you use to construct a service is googleapiclient.discovery. The repository ships a samples/ directory with worked examples grouped by API, including samples/calendar_api/, samples/storage/, samples/analytics/ and samples/customsearch/. Those directories are the practical starting point, because the README itself defers to the docs folder for detailed instructions rather than walking through an authenticated call. Python 3.10, 3.11, 3.12, 3.13 and 3.14 are listed as fully supported and tested; setup.py exits with an error message on anything below 3.10, so the version floor is enforced at install time rather than documented only.

The 50 MB Package and the Missing Rollback Story

The most concrete cost is disk. A single library that carries discovery documents for every supported API is over 50 MB larger than the 1.x line, and that weight lands in every container image, every lambda bundle and every CI cache that installs it. If you deploy to a size-limited environment, this is the number that decides whether the library is viable at all. The README presents the size increase as the accepted price of removing a network dependency from discovery.build(), which is a defensible engineering choice, but it is a choice you inherit whether or not you use more than one API.

The second limitation is documentation coverage at the edges. The README points to the docs folder and to the samples directory, and it documents installation, supported Python versions, dependencies and the v2 change. It does not document rollback. If a weekly release introduces a regression in a discovery document that your code depends on, the README gives you no procedure for pinning back or for overriding the bundled document. You are left with ordinary pip version pinning and the UPGRADING.md migration guide, which the README references for the 1.x to 2.x move specifically. Treat the weekly cadence as something to pin against in production, not something to float on.

The third case where this is the wrong tool is any API that has a dedicated Cloud Client Library. The README lists the reasons itself: separate libraries mean you download only what you use, breaking changes get stricter controls because each library focuses on one API, the dedicated libraries carry more features, and developers get intellisense. A discovery-generated client cannot offer typed completion for arbitrary APIs, because the surface is assembled at runtime.

Cloud Client Libraries for Python: The Same APIs, a Different Design

The recommended alternative is googleapis/google-cloud-python, the Cloud Client Libraries for Python. The difference in approach is packaging and typing, not protocol. Cloud Client Libraries ship one library per API, so you install google-cloud-storage or google-cloud-bigquery and nothing else. google-api-python-client ships one library for all APIs, which is why its size crosses 50 MB.

That split changes the failure modes. With per-API libraries, a breaking change in one service is contained in that service's package and its version number. With a single discovery-driven client, the generated surface for every API moves together each week. Per-API libraries also carry hand-written conveniences and typed signatures, which is where the intellisense benefit comes from. The maintainers are careful to say that google-api-python-client "will continue to be supported," so this is not a deprecation notice. It is a routing recommendation, and it only applies where a Cloud Client Library exists.

Two adjacent cases get their own recommendations. For the Google Ads API the README points to googleads/google-ads-python, and for the Firebase Admin API it points to firebase/firebase-admin-python. If you are working in either of those, the general-purpose discovery client is not the intended path.

Licence, Releases and What an Upgrade Actually Costs

The project is Apache-2.0. For most teams that means permissive use with the usual obligations around notices and the licence text; the repository ships LICENSE at the top level. This is a description of the licence identifier, not legal advice, and anyone redistributing the package inside a product should read the file itself.

The upgrade cost is dominated by one event. The 1.x to 2.x move bundled discovery documents into the package, added the size, and dropped support for Python versions below 3.10. The README states that only Python 3.10 and newer is supported and directs anyone who cannot upgrade the interpreter to stay on v1, which continues to support Python 2.7 and later. That means the upgrade is gated on your interpreter, not on the library's API. If you are already on a modern Python, the code-level change is small and UPGRADING.md covers it. If you are not, staying on v1 is the documented path, and it is a dead end for anything else.

Ongoing cost is the weekly release cadence. Releases are frequent: v2.198.0 on 2026-06-25, v2.199.0 on 2026-08-20, and v2.200.0 on 2026-08-31, with the last push to the default branch on 2026-09-15. A library that ships this often will surface in dependency scanners regularly, and each release refreshes the bundled discovery documents. The maintenance-mode statement tells you what will not arrive: new features. What arrives is refreshed documents and fixes for critical bugs and security issues.

Editorial conclusion

Adopt google-api-python-client when you need a Google API that has no Cloud Client Library, when you are maintaining existing code against it, or when you want one dependency to reach many services. Do not adopt it for new code on an API that already has a dedicated Cloud Client Library, and do not adopt it on Python 3.9 or older, because setup.py exits below 3.10. Before you commit, check whether a Cloud Client Library exists for your specific API, confirm your interpreter version, and budget disk for the discovery cache: the README states the package is at least 50 MB larger than the 1.x line because discovery documents ship inside the library.

Frequently asked questions

Official sources

1. googleapis/google-api-python-client on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases