Installation

gfly is a Python package published to PyPI as gfly (v0.1.0). The default google backend needs no API key and no account — install and run.

Zero-install trial

Not ready to commit? Run gfly directly without installing anything:

uvx gfly search JFK LHR --depart 2026-08-15

uvx spins up a disposable virtual environment, runs the command, and discards it. Nothing persists on your machine. Great for a quick sanity check before adding gfly to a project.

Recommended: uv tool install

uv tool install gfly

This installs gfly into an isolated environment managed by uv and puts the gfly binary on your PATH. It is the fastest, cleanest option and keeps gfly’s dependencies off your project’s lockfile.

To upgrade later:

uv tool upgrade gfly

Other install methods

Method	Command	Best for
uvx (no install)	uvx gfly search JFK LHR --depart 2026-08-15	Try it once
uv tool install (recommended)	uv tool install gfly	Persistent, isolated
pipx	pipx install gfly	pipx users
pip	pip install gfly	Scripts, venvs, CI

Note

Python ≥ 3.10 is required. Check with python --version or python3 --version.

pip inside a virtual environment

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install gfly

What ships in the box

The default install pulls exactly these runtime dependencies (from pyproject.toml):

Package	Version	Purpose
click	≥ 8.4	CLI framework
fast-flights	≥ 3.0.2	google backend — reverse-engineered Flights endpoint
typing-extensions	≥ 4.15	Transitive dependency of fast-flights
keyring	≥ 25	Credential storage for the serpapi backend
airportsdata	≥ 20260315	Offline IATA resolution (~7 900 airports)

The serpapi backend uses Python’s standard-library urllib — no extra dependency required. You only need to supply an API key to use it. See Backends for details.

Tip

fast-flights’ optional Playwright browser fallback is intentionally not installed. The default install stays light and works fully headless.

Verify the installation

Run these three commands after installing:

gfly --version          # prints the version string (e.g. 0.1.0)
gfly doctor             # checks auth, keyring, connectivity, and throttle state
gfly schema             # machine-readable command tree + exit codes + env vars

If gfly is not found after pip install, your Python bin directory may not be on PATH. With uv tool install, run uv tool list to confirm the binary path.

Supply-chain verification

Every release artifact is accompanied by a SHA256SUMS file and a build-provenance attestation generated by GitHub Actions. You can verify the wheel before installing:

# Download the wheel from PyPI first, then verify:
gh attestation verify gfly-0.1.0-py3-none-any.whl --repo rnwolfe/gfly

The attestation links the artifact back to the exact commit and workflow run that built it. Source is at github.com/rnwolfe/gfly.

Next steps

• Quickstart — search flights and pipe results into jq in under a minute.
• Searching flights — full flag reference: dates, cabin, stops, sort, pagination.
• Backends — when to switch from google to serpapi and how to configure it.