Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.392s · 21.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.368s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from serpapi import Client
GoogleSearch
✓ from google_search_results import GoogleSearch
✗ from serpapi import GoogleSearch
The `GoogleSearch` class is part of the legacy `google-search-results` package (also sometimes imported as `serpapi`), not the current `serpapi` client library. Use `serpapi.Client` instead for the recommended package.
This example demonstrates how to perform a Google search using the `serpapi.Client`. It fetches results for 'Coffee' in Austin, Texas, and prints the title of the first organic result. The API key is securely retrieved from an environment variable.
import os
from serpapi import Client
# Ensure SERPAPI_KEY is set as an environment variable
# Example (bash): export SERPAPI_KEY='your_private_api_key'
api_key = os.environ.get('SERPAPI_KEY', '')
if not api_key:
print("Error: SERPAPI_KEY environment variable not set.")
else:
client = Client(api_key=api_key)
try:
results = client.search({
"engine": "google",
"q": "Coffee",
"location": "Austin, Texas, United States",
"hl": "en",
"gl": "us"
})
print(results.get("organic_results", [])[0].get("title"))
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe `serpapi` package (current official client) is distinct from the older `google-search-results` package, which sometimes used `from serpapi import GoogleSearch`. Code written for the legacy package will not work directly with the new `serpapi` client.fixMigrate your import and usage pattern. Replace `from serpapi import GoogleSearch` with `from serpapi import Client` and instantiate `Client(api_key=...)` directly, then use `client.search(...)`.
affects: All versions >= 1.0.0 of `serpapi` when migrating from `google-search-results`.
gotchaIncorrect API key handling (hardcoding or not setting environment variable) is a common cause of `Unauthorized` (401) or `Bad Request` (400) errors.fixAlways set your `SERPAPI_KEY` as an environment variable (e.g., `export SERPAPI_KEY='your_key'`) and access it via `os.environ.get('SERPAPI_KEY')` or pass it directly when initializing `Client(api_key='your_key')`. Avoid hardcoding in source control. affects: All versions
breakingVersion 1.0.0 removed the 'redundant engine' parameter for Google searches and changed `yield_pages` to start from the first page, potentially altering expected behavior or requiring adjustments for pagination logic.fixReview code interacting with Google search parameters and pagination logic if upgrading from versions prior to 1.0.0. The `engine` parameter may still be specified but its internal handling or default behavior changed. Ensure pagination starts at the correct point if `yield_pages` is used.
affects: < 1.0.0
gotchaPrior to v1.0.0, `serpapi.HTTPError` instances might have been missing essential status code and error messages, making debugging API request failures difficult.fixUpgrade to `serpapi` version 1.0.0 or higher to ensure `serpapi.HTTPError` provides full details, including `status_code` and `message`, for more robust error handling.
affects: < 1.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'serpapi'
The 'serpapi' Python library has not been installed in the current Python environment.
fixInstall the library using pip: `pip install serpapi`
serpapi.SerpApiError: Invalid API key. Please re-check your API key
The SerpApi API key provided is incorrect, expired, or missing.
fixObtain a valid API key from SerpApi.com and ensure it's correctly passed to the SerpApi client or set as an environment variable (SERPAPI_API_KEY).
KeyError: 'organic_results'
The specific key (e.g., 'organic_results') does not exist in the JSON response for the given search query, often because no results were found for that section or the search parameters are incorrect.
fixCheck for the existence of the key using the `.get()` method or a conditional check before accessing it, or implement error handling for `KeyError`.
AttributeError: module 'serpapi' has no attribute 'search_results'
The user is attempting to call a method directly on the `serpapi` module that does not exist, instead of instantiating a search client like `GoogleSearch`.
fixImport and instantiate the appropriate search client (e.g., `GoogleSearch`) and then call its methods: `from serpapi import GoogleSearch; search = GoogleSearch(params); results = search.get_dict()`
AttributeError: module 'serpapi' has no attribute 'GoogleSearch'
The `GoogleSearch` class (or other search engines) must be imported directly from the `serpapi` module.
fixfrom serpapi import GoogleSearch
Upgrade
Version history
1.1.0latest on PyPI · released Aug 14, 2026
Audit
Dependencies
No dependency data recorded yet.