mozrunner

8.4.0 verified Fri May 01 auth: no python

A library to reliably start, stop, and configure Mozilla applications (Firefox, Thunderbird, etc.). Version 8.4.0 supports Python >=3.8. It wraps Mozilla processes with geckodriver or Marionette for automation and testing.

pip install mozrunner

Common errors

error ModuleNotFoundError: No module named 'mozrunner' ↓

cause Package not installed or installed in a different virtual environment.

fix

Run pip install mozrunner in the correct environment.

error AttributeError: module 'mozrunner' has no attribute 'Runner' ↓

cause Outdated installation (version <8.0.0) where Runner was in a submodule.

fix

Upgrade: pip install -U mozrunner. Also check imports: use from mozrunner import Runner.

error OSError: [Errno 2] No such file or directory: 'firefox' ↓

cause The browser binary is not on PATH or the specified path is wrong.

fix

Pass the correct binary path: binary='/usr/bin/firefox' or use shutil.which('firefox').

Warnings

gotcha Binary path must point to a Firefox/Thunderbird executable. If not found, Runner raises an OSError or fails silently. Always verify the binary path. ↓

fix Specify the full path or ensure 'firefox' is on PATH. Use shutil.which('firefox').

deprecated The 'mozrunner.cli' module and command-line interface (CLI) are deprecated and may be removed in the future. ↓

fix Use the library API directly instead of the CLI wrapper.

gotcha The 'Runner' base class does not automatically download or update GeckoDriver. You must manage GeckoDriver separately for Firefox automation. ↓

fix Install geckodriver and ensure it's on PATH before using mozrunner with Marionette-based automation.

Imports

Runner
wrong
```
mozrunner.Runner
```
correct
```
from mozrunner import Runner
```
Most classes are top-level in the mozrunner package, not nested.
FirefoxRunner
wrong
```
from mozrunner.runners import FirefoxRunner
```
correct
```
from mozrunner import FirefoxRunner
```
FirefoxRunner is exported directly from mozrunner; no submodule needed.

Quickstart

Create a Firefox profile, start the browser, wait, then stop.

from mozrunner import FirefoxRunner
from mozprofile import FirefoxProfile

profile = FirefoxProfile()  # or use addons/prefs
runner = FirefoxRunner(binary='firefox', profile=profile)
runner.start()
print('Firefox started')
runner.wait(timeout=60)
runner.stop()