geckodriver: the WebDriver proxy that drives Firefox

What geckodriver actually sits between

geckodriver drives Firefox through Marionette, Mozilla's own remote protocol, and the README describes geckodriver as a proxy that "translates calls into the Marionette remote protocol by acting as a proxy between the local- and remote ends." That sentence is the whole architecture. Your test client sends HTTP requests shaped by the W3C WebDriver spec to a local geckodriver process, and geckodriver forwards the equivalent Marionette commands to the browser.

The audience is narrow and worth stating plainly. This is for people who already have a WebDriver client (Selenium in Python, Java, C#, Ruby, Perl or JavaScript, all linked from the README) and need a Firefox endpoint for it. If you are writing a test suite against Chrome, geckodriver does nothing for you. If you are driving Firefox through a lower-level interface directly, you are bypassing the layer geckodriver exists to provide.

The protocol boundary is the design decision

Putting translation in a separate process rather than inside Firefox has consequences. The driver can be updated independently of the browser, which is why the release cadence does not have to match Firefox's. It also means the driver is a real network hop: your client talks HTTP to localhost, and geckodriver talks Marionette to the browser. When something fails, there are two places to look, and the README links a dedicated page on enabling trace logs for exactly that reason.

The second consequence is version coupling. geckodriver is a Rust program distributed as a standalone binary, and Firefox is a separate download with its own release train. The README does not promise any compatibility matrix between the two; it points to the change log for a detailed list of changes per release. In practice that means the pairing is something you verify, not something the project guarantees on the README page.

Installing geckodriver and running a first session

The README lists two installation routes: pre-built binaries from the Releases page for the most common platforms, or compiling it yourself. The self-compile options are `cargo install geckodriver` or checking out the `release` branch or a specific tag. For a machine where no binary exists, the README's custom build section says to check out the release tag for the version of interest and run `cargo build`.

The README gives this example for the crates.io route:

cargo install geckodriver

That installs the driver from crates.io. The README also gives the alternative for a custom build, checking out the release tag and running:

cargo build

After either, the binary needs to be on your PATH, or your client needs to be told where it is. The README points to the geckodriver usage page and the supported platforms page for the details it does not repeat.

Once the binary is reachable, a Selenium session is short. The README links the Selenium Python API documentation and the capabilities example on the Firefox capabilities page, which is where the Firefox-specific options are documented. If a session fails, the first thing to check is whether Selenium found the driver binary at all, because a missing driver produces an error before any browser starts. The README's trace log page is the documented next step when the browser starts but a command fails.

Where geckodriver is the wrong tool

The clearest limitation is in the name of the protocol it implements. geckodriver is a WebDriver Classic proxy. If your testing strategy has moved to WebDriver BiDi for event streams, network interception or console log capture, the README does not present a BiDi surface; it links the W3C WebDriver protocol and the MDN command, error and type references, all of which are the Classic model. Treat BiDi support as something to confirm against the release notes for the version you install, not something to assume.

The second limitation is scope. One driver, one browser family. Teams running a matrix across Chrome, Edge and Firefox end up managing multiple driver binaries with different download pages, different version schemes and different failure messages. geckodriver does not abstract that away, and no amount of configuration makes it do so.

The third is the distribution model. The README states that the GitHub repository is only used for issue tracking and making releases, and that the source lives in mozilla-central under testing/geckodriver. If you file a pull request against the GitHub repo expecting it to be merged there, you have misread the layout. Development happens in the Mercurial tree.

How it compares to a Selenium Manager style approach

The alternative most people actually weigh is not another Firefox driver but letting the client library resolve drivers for you. Selenium's own tooling downloads and caches the correct driver binary automatically, which removes the manual step of visiting the Releases page. That approach is not a different protocol implementation; it is a different answer to the question of who owns driver provisioning.

The trade-off is control against convenience. With automatic resolution you get less visibility into which driver version is on disk and when it changed. With a manual `cargo install geckodriver` or a pinned binary you know exactly what is running, which matters when you are debugging a failure that only appears on one CI machine. Neither approach changes what geckodriver does once it starts; both end up executing the same Rust binary.

For platforms without a pre-built binary, the README's ARM page documents self-serving a build, which is the path that automatic resolution cannot take for you.

Licence, maintenance and the cost of upgrading

geckodriver is released under the Mozilla Public License 2.0, the LICENSE file at the repository root. MPL-2.0 is a file-level copyleft licence: modifications to MPL-covered files must be made available under the same licence, while larger works that combine it with other code can be licensed differently. If you redistribute a modified geckodriver, read the licence text rather than relying on that summary, and get legal advice if the distinction matters to your product.

The maintenance picture is concrete. The last push to the repository was on 2026-08-25. The most recent release is v0.37.1 from 2026-07-20, following v0.37.0 on 2026-06-03 and v0.36.0 on 2025-02-25. That gap between v0.36.0 and v0.37.0 is over a year, so release timing is not something to plan around; the version you need may simply not exist yet.

Upgrade cost is mostly about the browser pairing. Because geckodriver is a proxy and Firefox ships separately, a driver upgrade and a browser upgrade are two events. The change log is the document to read before either, and the trace log page is where you go when the pairing breaks.

Editorial conclusion

Adopt geckodriver if you are automating Firefox and your client already speaks W3C WebDriver, since geckodriver is the proxy that lets W3C WebDriver clients interact with Gecko-based browsers. Do not adopt it if you need one driver for Chrome, Safari and Firefox at once, or if you want a modern WebDriver BiDi-only stack, because geckodriver is a Classic proxy and the README points to the WebDriver protocol page rather than a BiDi surface. Before committing, verify that a pre-built binary exists for your platform on the Releases page, that your Firefox version is covered by the release notes for the tag you pick, and that your client library can locate the driver without you hard-coding a path.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. mozilla/geckodriver on GitHub
3. Project website
4. README
5. Releases