# Geckodriver: W3C WebDriver proxy for Firefox automation

> A proxy server that translates standard WebDriver protocol calls into Firefox's Marionette remote protocol. Use it when you need to automate Firefox through any WebDriver-compatible client library, from Python to Java to JavaScript.

**mozilla/geckodriver** — WebDriver Classic proxy for automating Firefox through Marionette

- Repository: https://github.com/mozilla/geckodriver
- Website: https://firefox-source-docs.mozilla.org/testing/geckodriver/
- Stars: 7,478 · Forks: 1,515
- Language: Unknown
- License: MPL-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/mozilla-geckodriver

## Geckodriver translates WebDriver calls to Marionette protocol

Geckodriver sits between a WebDriver client and Firefox. A WebDriver client, such as Selenium Python, sends HTTP requests in the W3C WebDriver protocol format. Geckodriver parses these requests and converts them into calls to the Marionette remote protocol, which is the wire format Firefox's testing harness understands. This proxy architecture means any WebDriver-compatible library can control Firefox without knowing about Marionette internals.

The README explains that geckodriver acts as a proxy between local and remote ends, translating the HTTP API into Marionette calls. W3C WebDriver is a standard protocol defined by the World Wide Web Consortium, so any tool that implements it as a client can drive Firefox through geckodriver. This includes not only Selenium but also custom test frameworks that speak WebDriver. The separation of concerns, with geckodriver handling protocol translation, allows Firefox's testing infrastructure to evolve independently of WebDriver clients.

## Installing geckodriver from pre-built binaries or source

According to the README, three installation paths are available. Most users should download pre-built binaries from the Releases page on GitHub; binaries exist for common platforms including Linux, Windows and macOS. For platforms without a pre-built binary, build from source using the Rust toolchain.

For development workflows, cargo install geckodriver installs the latest version from crates.io without needing to clone or build manually. For reproducible builds pinned to a specific version, clone the repository, checkout the release branch or a specific tag, and run cargo build. All releases include a CHANGES.md file on the release branch documenting what was fixed and added.

Once installed, geckodriver becomes a standalone executable. Most users place it in a directory on their PATH, though test frameworks can also specify its full path explicitly. No configuration is required beyond having Firefox installed; geckodriver launches Firefox automatically when a test connects to it.

## Connecting Selenium to geckodriver

Selenium and geckodriver work together: Selenium is the test client, geckodriver is the browser control server. When you use the Selenium Python API (or Java, JavaScript, etc.), you import the webdriver module and create an instance for Firefox. Selenium will look for geckodriver in your PATH and spawn it as a subprocess, then send WebDriver protocol requests to it.

The README links to Selenium's documentation for all language bindings (Python, Java, C#, JavaScript, Ruby, Perl) and geckodriver's usage guide. These documents cover passing Firefox-specific capabilities, such as headless mode, proxy settings, and custom arguments. If geckodriver is not found on your PATH, you pass the absolute path to the Firefox webdriver constructor in your language of choice.

No additional setup is required beyond ensuring Firefox and geckodriver are both installed. Geckodriver handles all communication with Firefox's Marionette protocol internally; your test code never sees it.

## Geckodriver automates Firefox only; use other drivers for other browsers

Scope is narrow by design. Geckodriver only works with Firefox and other Gecko-based browsers such as Thunderbird. If your test suite must run across multiple browsers, you use different WebDriver servers for each: chromedriver for Chrome, EdgeDriver for Edge, geckodriver for Firefox. Your test code stays the same across browsers; only the driver executable changes.

This is not a limitation in practice for Firefox-focused teams, but it is a decision point for cross-browser testing. Many organizations manage this by parameterizing their test setup to select the correct driver per browser. Other approaches include using higher-level test frameworks that abstract away the driver choice, though these frameworks eventually rely on the same underlying WebDriver servers.

Additionally, Marionette and the W3C WebDriver specification are both evolving standards. The README's documentation notes that WebDriver is marked as work in progress on MDN. Recent browser features may not be exposed through the WebDriver API, and incompatibilities can appear when Firefox or WebDriver specifications change.

## How geckodriver relates to other WebDriver servers

Selenium is a client-side library that sends HTTP requests to a WebDriver-compatible server. Geckodriver is one such server; it implements the WebDriver protocol for Firefox. Chromedriver does the same for Chrome, EdgeDriver for Edge, and SafariDriver for Safari.

The key difference in architecture is that geckodriver is a separate process you run before your tests start. Chrome and Safari drivers are sometimes bundled with the Selenium client for convenience, but geckodriver requires explicit setup. This visibility is an advantage when debugging: you can inspect geckodriver's log output directly, configure its verbosity, and see exactly what it is sending to Firefox.

Both geckodriver and chromedriver follow the same W3C WebDriver standard, so swapping one for the other requires only changing which binary you invoke and potentially a few browser-specific capability names. Your test code itself usually stays identical.

## Building geckodriver from mozilla-central

Geckodriver's source code lives in mozilla-central, Mozilla's main Firefox repository, under testing/geckodriver. The GitHub repository is used only for issue tracking and releases; it is not the primary development location. The README includes a link to the contributing guide on the Mozilla Firefox documentation site.

For developers who need a custom build, the README documents the process: check out the Rust repository, install the Rust toolchain via rustup.rs, and run cargo build. The project includes build instructions for specific platforms, including self-serving ARM builds. Each release is tagged in the repository, and you can checkout a specific tag to rebuild an older version if needed.

Development is active. The last push to the repository was on 2026-08-25. Recent releases include v0.37.1 published on 2026-07-20, v0.37.0 on 2026-06-03, and v0.36.0 on 2025-02-25, showing regular updates.

## Contributing through mozilla-central, not GitHub pull requests

Geckodriver is licensed under the Mozilla Public License 2.0, the same license as Firefox itself. Developers and users can discuss geckodriver and WebDriver on the dev-webdriver mailing list at groups.google.com/a/mozilla.org/g/dev-webdriver, or in the #webdriver Matrix channel on chat.mozilla.org. The repository includes a CONTRIBUTING.md file and CODE_OF_CONDUCT.md documenting community standards.

Because the canonical source is in mozilla-central rather than on GitHub, contributing usually means working through Mozilla's development process. The GitHub issue tracker is the appropriate place to report bugs and feature requests, but patches typically go through Mozilla's code review infrastructure. This structure reflects geckodriver's position as a core part of Firefox's testing infrastructure.

## Conclusion

Use geckodriver if you automate Firefox with Selenium, WebDriver or any W3C-compatible client that expects a WebDriver HTTP server. Skip it if you need to automate Chrome or Edge, or if you use Firefox's DevTools protocol directly. Start by installing a pre-built binary and confirming Firefox launches when your test suite runs.

## FAQ

### What is the relationship between geckodriver and Selenium?

Selenium is a client library for writing tests in Python, Java, JavaScript or other languages. Geckodriver is the server that Selenium connects to for Firefox automation. Selenium sends WebDriver protocol requests to geckodriver over HTTP; geckodriver translates them to Marionette calls. Other browsers use equivalent drivers: Selenium plus chromedriver for Chrome, Selenium plus EdgeDriver for Edge.

### How do I install geckodriver on Windows?

Download the Windows binary from the Releases page on GitHub, place it in a folder on your PATH (or specify its full path in your test code), and ensure Firefox is installed. The README states that pre-built binaries are available for common platforms including Windows.

### Can I use geckodriver to automate Chrome or Edge?

No. Geckodriver only works with Firefox and other Gecko-based browsers. For Chrome, use chromedriver; for Edge, use EdgeDriver. These are separate WebDriver server implementations that follow the same protocol.

### How do I set up geckodriver with Selenium Python?

Install geckodriver and Firefox, then import webdriver from selenium and create a Firefox driver instance. Selenium will look for geckodriver in your PATH. The README links to Selenium's Python API documentation for configuration examples and capability handling.

### Is geckodriver still maintained?

Yes. The last push was on 2026-08-25, and recent releases include v0.37.1 from 2026-07-20. Development takes place in mozilla-central; the GitHub repository is used for releases and issue tracking.

### What platforms does geckodriver support?

Pre-built binaries are available for common platforms including Windows, macOS and Linux. For less common platforms, the README documents building from source using the Rust toolchain, including custom ARM builds.

## Sources

- [License: MPL-2.0](https://github.com/mozilla/geckodriver/blob/master/LICENSE)
- [mozilla/geckodriver on GitHub](https://github.com/mozilla/geckodriver)
- [Project website](https://firefox-source-docs.mozilla.org/testing/geckodriver/)
- [README](https://github.com/mozilla/geckodriver/blob/master/README.md)
- [Releases](https://github.com/mozilla/geckodriver/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mozilla-geckodriver