How To Scrape Google Images With A Make Target And Selenium

One image URL in, an images.csv out

The repository holds a single Python package, `google-images-scraper`, declared in `pyproject.toml` at version `0.1.0` and shipped from the `src/` directory. It answers one narrow question: given a picture that already exists on the web, which pages does Google Images associate with it. You hand the tool a direct link to an image file, it runs the reverse image search, and it leaves an `images.csv` in the directory you launched it from. Three columns make up that output contract: `title` for the page the image was found on, `image_url` for the static Google Images link, and `source_url` for the page that hosts the original. There is no database, no job queue and no retry layer anywhere in the package. That scope fits a one-off investigation of a photo that already spread somewhere, and does not fit a pipeline that another system polls.

Selenium sits behind the make scrape target

The repository description says the process is automated by sending HTTP requests, yet the dependency list tells a different story for the free path. `pyproject.toml` pins selenium at `^4.22.0` and webdriver-manager at `^4.0.1`, which is a browser automation stack rather than an HTTP client, and adds click at `^8.1.7` for the command line plus pydantic `^2.7.4` and pydantic-settings `^2.3.4` for configuration. The make target settles the question about the entry point, because it runs a module with a single option: `poetry run python -m google_images_scraper --url="$(URL)"`. So the free scraper opens a real browser session instead of posting a query string over a socket, and webdriver-manager fetches a matching driver first. Nothing in the listed dependencies is an HTTP client, which is why the HTTP wording fits the second half of the tutorial better, where requests talks to a remote endpoint.

make install pins poetry==1.8.2 before anything else

Prerequisites are narrow: Python 3.11, a terminal and a clone of the repository. One target installs everything, and it fixes the installer before using it, so whatever Poetry version already sits on your machine is not the one that resolves the lock file. Expect six dependencies to download, including the Selenium driver manager, which then needs network access on its first run to obtain a browser binary.

make install

The Makefile behind that command is only two lines of work.

pip install poetry==1.8.2
poetry install

Afterwards the query is one command, and the address has to stay inside quotation marks or the shell will split it. The example walks through a photograph taken from a Wikipedia page on cats.

make scrape URL="https://upload.wikimedia.org/wikipedia/commons/thumb/b/bb/Kittyply_edit1.jpg/440px-Kittyply_edit1.jpg"

Once the run finishes, look for `images.csv` in the working directory you typed the command from.

The make scrape target fails fast on an empty URL

The guard in the `Makefile` saves you from a stack trace, so a missing argument never reaches Python at all. With no `URL` variable set, the target prints a one line error and exits before the module loads.

echo 'Error: A URL of an image to query is required. Use make scrape URL="<image_url>"'

Double quotes around `$(URL)` are the only thing separating a long address from a broken argument, which is why the tutorial insists on them twice. The input side has its own rule: the address must point straight at an image file ending in `.jpg`, `.png` or another image format, so an article page that merely displays a picture is not accepted. Two operational gaps are worth knowing before you rely on this. The top-level entries are `.flake8`, `.gitignore`, `.pre-commit-config.yaml`, `.python-version`, `Makefile`, `README.md`, `poetry.lock`, `pyproject.toml` and `src/`, and none of them carries a timeout, proxy or rate limit setting. A run that stalls on a slow page keeps stalling.

Two Python floors: 3.11 in the tool, 3.6 in the tutorial

The same document states two Python floors that do not overlap. The free half asks for Python 3.11, and `pyproject.toml` pins `python = "^3.11"` alongside pydantic `^2.7.4` and pandas `^2.2.2`. The API half lowers the bar to Python 3.6+ and then installs its packages outside Poetry with `pip install requests pandas`, a step that pulls none of the six dependencies the free path resolves. A 3.6 interpreter sits outside the `^3.11` range the dependency file declares, and an install completed with pip leaves click, selenium, webdriver-manager, pydantic and pydantic-settings missing, so the module entry point in the make target has nothing to import. Neither the `Makefile` nor `pyproject.toml` states a supported range for the API script, and `.python-version` at the repository root pins the toolchain to one interpreter rather than the range the prose mentions.

The table of contents promises Step 5 and stops

The contents list at the top of the file promises a Step 5 for extracting data and saving it in a CSV file, and the tutorial body never reaches it. After the paragraph about the markdown option the text ends on a dangling word, `Furthermore,`, with nothing behind it, so the paid half ships no complete request sequence and no extraction step in the text you actually get. The markdown option has the same trouble: the payload example sets `source`, `query`, `geo_location`, `context`, `parse` and `pages`, while the prose names `markdown` as an extra switch without showing where it belongs or listing it beside the mandatory and optional parameters. Anyone copying the API half has to fill that gap from the vendor documentation instead of from this repository.

The paid half swaps the image input for a query

The second approach is not a variation on the first, it is a different service with a different input. Instead of an image URL you send a search term, and the payload carries it with the endpoint that switches the response to images.

# Request payload with API parameters
payload = {
    "source": "google_search",
    "query": "cute cat",
    "geo_location": "United States", # Localize results for US
    "context": [
        {"key": "tbm", "value": "isch"}, # Scrapes only Google Images
    ],
    "parse": True, # Automatically parse HTML into JSON
    "pages": 2 # Scrape as many pages as needed
}

Mandatory keys are `source`, `query` and `context`; `geo_location`, `parse` and `pages` tune the result. Advanced operators work inside the query string, so restricting results to a single site means writing `cute cats inurl: unsplash`. Access stops being free after the first week: you need a user account on the vendor dashboard, API credentials, and a subscription once the 7-day trial ends. In exchange you receive JSON and a local machine that installs no browser at all.

Version 0.1.0 with one author and a locked file

The dependency set is small enough to read on one screen and pinned tightly enough that an upgrade is real work. `pyproject.toml` lists `python = "^3.11"`, pydantic `^2.7.4`, click `^8.1.7`, pandas `^2.2.2`, selenium `^4.22.0`, webdriver-manager `^4.0.1` and pydantic-settings `^2.3.4`, builds through poetry-core and names a single author, Ignas Šimkūnas. mypy runs with `disallow_incomplete_defs` enabled, isort pins the interpreter level to 311, and a `poetry.lock` sits at the root next to `.pre-commit-config.yaml` and `.flake8`. Changing any constraint means re-resolving that lock file, because `make install` always installs the pinned Poetry build first. The last push landed on 2026-06-19 and the repository is not archived.

Editorial conclusion

Adopt the free target when you hold one direct image URL and want to see which pages reuse it, and expect Selenium plus a downloaded browser driver on your own machine. Do not adopt it for search-term queries, bulk jobs or unattended schedules, because that road ends at a paid endpoint that needs dashboard credentials. Verify three things first: your interpreter against the `^3.11` constraint, that the README's Step 5 is missing, and that no licence file ships with the repository, so reuse terms stay unstated.

Frequently asked questions

Official sources

1. Issues
2. oxylabs/how-to-scrape-google-images on GitHub
3. README