Find Flights

Quick Start

Agent setup rule:

• If uv exists (command -v uv succeeds), use uv commands.
• If uv is unavailable, fall back to python3 -m venv + pip.

Preferred path (uv available):

uv run --with "fast-flights[local]" playwright install chromium
uv run --with "fast-flights[local]" python scripts/search_airports.py "Portland"
uv run --with "fast-flights[local]" python scripts/search_flights.py --from PDX --to LAX --date 2026-03-10 --fetch-mode local

Fallback path (uv unavailable):

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install "fast-flights[local]"
playwright install chromium
python3 scripts/search_airports.py "Portland"
python3 scripts/search_flights.py --from PDX --to LAX --date 2026-03-10 --fetch-mode local

Fallback note: if python3 -m venv fails with ensurepip is not available, install the system venv package first (for example on Ubuntu/Debian: sudo apt install python3-venv) or install fast-flights[local] into the active Python environment.

Search airports (returns enum matches and IATA codes):

uv run --with "fast-flights[local]" python scripts/search_airports.py "Portland"
uv run --with "fast-flights[local]" python scripts/search_airports.py "Berlin"

Search flights:

# One-way
uv run --with "fast-flights[local]" python scripts/search_flights.py --from PDX --to LAX --date 2026-03-10 --seat economy --adults 1 --fetch-mode local

# Round-trip (return leg is auto-added as TO -> FROM)
uv run --with "fast-flights[local]" python scripts/search_flights.py --from PDX --to LAX --date 2026-03-10 --return-date 2026-03-17 --max-stops 0 --fetch-mode local

Troubleshooting

If Google Flights blocks the request or returns no results, retry with:

uv run --with "fast-flights[local]" python scripts/search_flights.py ... --fetch-mode local
uv run --with fast-flights python scripts/search_flights.py ... --fetch-mode fallback
uv run --with fast-flights python scripts/search_flights.py ... --data-source js

Notes:

• --data-source js and --airlines ... may be ignored depending on the installed fast-flights version.
• If you see a Google consent page (e.g., "Before you continue to Google"), prefer --fetch-mode local.
• --fetch-mode fallback may rely on a hosted Playwright service in some environments; if it fails, use --fetch-mode local.

Recommended local Playwright setup with uv:

uv run --with "fast-flights[local]" playwright install chromium
uv run --with "fast-flights[local]" python scripts/search_flights.py ... --fetch-mode local

Alternative with pip/venv:

python3 -m pip install "fast-flights[local]"
playwright install chromium
python3 scripts/search_flights.py ... --fetch-mode local

References

• See references/fast_flights_api.md for the underlying API and fetch-mode notes.

Runtime lessons learned

• For first run, uv run --with "fast-flights[local]" ... --fetch-mode local is the most reliable path and avoids global installs.
• Start with --fetch-mode local when the environment has Playwright installed. The common and fallback modes can fail with consent screens or upstream timeouts.
• Some installs throw No module named 'playwright' if fast-flights[local] is not installed.
• The same route/date can return duplicates or malformed rows (price: 0, stops: Unknown), so use post-filters to keep only valid positive prices.
• --airlines and --data-source are version-dependent; keep these as optional inputs and fall back cleanly when unsupported.
• Use one-way legs when you need custom constraints (time-window filtering, minimum layover/ground-time, route shape), then combine legs manually to enforce exact rules.
• Airport-name lookups can be ambiguous. Run search_airports.py first and pick the exact IATA code you want before searching flights.

Output formatting preference

• Always include the day of week when reporting dates (example: Sat, Feb 21, Mon, Feb 23) so dates remain explicit.