Installation

gsearch is a Python package that drives a real browser. Installing it is two steps: the package itself, and a Chrome or Chromium build for patchright to drive.

With uv

The fastest way to run gsearch is with uv:

uv tool install gsearch

That puts gsearch on your PATH in an isolated environment. If you have an existing Google Chrome install, gsearch can drive it directly; otherwise install the private Chromium build patchright uses:

patchright install chromium

From source

git clone https://github.com/tamnd/gsearch
cd gsearch
make sync          # create .venv and install the project
make browser       # download the Chromium build patchright drives (once)
uv run gsearch search "epl"

make sync creates the virtualenv and installs the project with its dependencies. make browser runs uv run patchright install chromium to download the browser build, which you only need to do once.

The browser requirement

The one runtime requirement beyond the Python dependencies is a Chrome or Chromium build for patchright to drive. You have two options:

• Private Chromium. make browser, or patchright install chromium, downloads a private copy that gsearch uses by default. This is the simplest path and does not touch any Chrome you already have.
• System Google Chrome. If Google Chrome is already installed, gsearch can use it through the chrome channel instead of the private build.

Either way, the browser runs headlessly by default. Add --no-headless to any search or capture command to watch the window, which is useful the first time you run gsearch from a new machine or IP. See the introduction for why.

Requirements

• Python 3.11 or later.
• A Chrome or Chromium build for patchright (installed by make browser / patchright install chromium, or an existing Google Chrome).

That is the whole list. There is no config file to write, no database to provision, and no API key to register.

Checking the install

gsearch --help

prints the command tree and exits. Then run a first real search:

gsearch search "weather london"

If you see a rendered summary with a weather card, the browser is installed and gsearch can reach Google. If Google shows a consent or CAPTCHA page instead, run it once with --no-headless, solve it by hand, and the persistent profile remembers the session for next time. You are then ready for the quick start.