Google Search Python Library

1.3.0 · active · verified Sun Apr 12

googlesearch is a Python library for scraping the Google search engine. It uses `requests` and `BeautifulSoup4` to parse Google's search results. The library is actively maintained with releases addressing changes in Google's search page structure. The current version is 1.3.0, released January 21, 2025.

Warnings

breaking Google frequently updates its search page's HTML structure, which can break the library's scraping logic, leading to empty results or parsing failures.
Fix: Upgrade to the latest version (`1.3.0` or newer). Version `1.3.0` specifically addressed issues by updating the parsing logic and using a 'Lynx' user-agent to bypass Google's changes. Regular updates are recommended as Google's layout can change without notice.
gotcha Automated searches are often detected and throttled or blocked by Google, leading to HTTP 429 (Too Many Requests) errors, captchas, or empty results.
Fix: Use the `pause` parameter in the `search()` function to introduce delays between requests (e.g., `search(query, pause=2)` for a 2-second delay). For high-volume or commercial scraping, consider rotating proxies or Google's official Custom Search API.
gotcha There are multiple Python packages with similar names (`google`, `python-googlesearch`, `googlesearch-python`), leading to `ModuleNotFoundError` if the wrong one is installed or imported.
Fix: Ensure you install the correct package using `pip install googlesearch-python` and import it with `from googlesearch import search`. Verify the installed package using `pip show googlesearch-python`.
gotcha By default, the `search()` function yields only URLs. Users expecting titles or descriptions will find these missing from the results.
Fix: To retrieve more detailed information (title, URL, description), pass `advanced=True` to the `search()` function. This will yield `SearchResult` objects with the desired attributes.

Install

pip install googlesearch-python Install stable release

Imports

search
```
from googlesearch import search
```
The `search` function is the primary entry point for performing Google searches. Directly importing `googlesearch` as a module or attempting to import from a package named `google` (which is a different library) will lead to `ModuleNotFoundError` or incorrect functionality.

Quickstart

Performs a Google search for a given query and prints the top 5 unique URLs. It demonstrates how to use the `pause` parameter to prevent IP blocking and includes a commented section for retrieving `advanced` search results with titles and descriptions.

from googlesearch import search

query = "latest Python news"

# The 'pause' parameter helps avoid IP blocks from Google by adding a delay between requests.
# 'num_results' specifies how many unique URLs to return.
results = list(search(query, num_results=5, lang="en", pause=2))

if results:
    print(f"Top 5 results for '{query}':")
    for i, url in enumerate(results):
        print(f"{i+1}. {url}")
else:
    print(f"No results found for '{query}'.")

# To get more detailed information (title, URL, description), use 'advanced=True'
# from googlesearch import search, SearchResult
# adv_results = list(search(query, advanced=True, num_results=3, pause=2))
# if adv_results:
#     print("\nAdvanced search results:")
#     for i, res in enumerate(adv_results):
#         print(f"{i+1}. Title: {res.title}")
#         print(f"   URL: {res.url}")
#         print(f"   Description: {res.description}")

view raw JSON →