Registry / http-networking / googlesearch-python

googlesearch-python

library1.3.0pypypi✓ verified 22d ago

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.

http-networking data

pip install googlesearch-python

github ↗package ↗

INSTALL

IMPORT

SIG · GOOGLESEARCH-PYTHO

googlesearch-python

http-networkingpythonv1.3.0

Install

2.4s avg

Import

508ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.526s · 22.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.490s · 23MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ from googlesearch import search

✗ from google 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.

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}")

googlesearch --version

Debug

Known issues

breakingGoogle 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.

affects: <1.3.0

gotchaAutomated 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.

affects: All versions

gotchaThere 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`.

affects: All versions

gotchaBy 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'googlesearch'

This error occurs when the `googlesearch-python` library is not installed or the installed package has a different name than what is being imported, often due to confusion with other 'google' related packages.

fix

Ensure you have installed the correct package using `pip install googlesearch-python`. If you previously installed `google` or `google-search`, uninstall them first and then install `googlesearch-python`. Also, verify you are running your script in the Python environment where the library was installed.

urllib.error.HTTPError: HTTP Error 429: Too Many Requests

Google detects automated requests from your IP address and temporarily blocks or rate-limits access, indicating you have sent too many requests in a given amount of time.

fix

Implement delays between your search queries using the `pause` parameter in the `search()` function (e.g., `pause=2` for a 2-second delay). For extensive scraping, consider using rotating proxies and user-agents, or exploring official Google APIs if your use case allows.

ImportError: cannot import name 'search' from 'googlesearch'

This error often happens when an older or conflicting package named `google` (which does not expose a `search` function directly) is installed, or if there's a local file named `google.py` that shadows the intended `googlesearch` module.

fix

Verify that `googlesearch-python` is correctly installed. If issues persist, try uninstalling potentially conflicting packages like `google` or `google-search` (`pip uninstall google google-search`) and then reinstall `googlesearch-python`. Also, check your project directory for any files named `google.py`.

TypeError: search() got an unexpected keyword argument 'tld'

This error indicates that the `search` function being called does not recognize the `tld` (top-level domain) parameter, which typically means you are using an incompatible version or a different 'google' related package that does not support this specific argument found in `googlesearch-python`.

fix

Ensure that `googlesearch-python` is the only relevant Google search library installed and that it is up to date (`pip install --upgrade googlesearch-python`). This error often points to a conflict with the `google` package which might have been installed instead of `googlesearch-python`.

Upgrade

Version history

1.3.0latest on PyPI · released Jan 21, 2025

Audit

Dependencies

requestsrequiredUsed for making HTTP requests to Google's search engine.

BeautifulSoup4requiredUsed for parsing the HTML content of Google's search results.

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/Nv7-GitHub/googlesearch ↗

packagehttps://pypi.org/project/googlesearch-python/ ↗