How to Install Firefox and geckodriver in CI

Firefox automation needs both the browser and a matching geckodriver on PATH. Version skew between them is the classic CI failure.

geckodriver is the WebDriver bridge to Firefox. In CI you install Firefox, put a compatible geckodriver on PATH, and run headless. Snap-packaged Firefox on Ubuntu is a common gotcha.

Why it fails in CI

geckodriver is not on PATH → "geckodriver executable needs to be in PATH".
A geckodriver too old/new for the installed Firefox → session-create errors.
Snap-packaged Firefox sandboxing conflicts with WebDriver in containers.

Install it reliably

Install Firefox and a pinned geckodriver, place the driver on PATH, and run headless. Prefer a non-snap Firefox in CI to avoid sandbox surprises.

Terminal

apt-get update && apt-get install -y firefox-esr

# pinned geckodriver on PATH
GV=v0.34.0
curl -L -o /tmp/gd.tar.gz \
  https://github.com/mozilla/geckodriver/releases/download/${GV}/geckodriver-${GV}-linux64.tar.gz
tar -xzf /tmp/gd.tar.gz -C /usr/local/bin
geckodriver --version

Cache & speed

Bake Firefox + geckodriver into a custom image, or cache the pinned geckodriver download keyed on its version. Run headless to avoid needing Xvfb.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: /usr/local/bin/geckodriver
    key: geckodriver-v0.34.0-${{ runner.os }}

Common errors

geckodriver executable needs to be in PATH → place it in /usr/local/bin and verify with --version.
Unable to find a matching set of capabilities → geckodriver/Firefox version skew; pin compatible versions.
Snap Firefox session timeouts → install firefox-esr instead.

Key takeaways

Install Firefox and a compatible geckodriver, both on PATH.
Prefer firefox-esr over snap Firefox in CI.
Pin and cache the geckodriver version to avoid skew.