ScreenshotNeo
Sign in Get a free key

BlogEngineering

What’s New in Selenium Manager 0.4.12

Selenium Manager 0.4.12 added automatic Firefox management, configurable caching, and a universal macOS binary. Here’s what changed and how to use it.

By the ScreenshotNeo team4 October 20268 min read

Selenium Manager 0.4.12, shipped with Selenium 4.12.0, made Firefox the headline: when Firefox is missing, the manager can discover, download, and cache it. The release also introduced a configurable cache path, unified browser and driver metadata time-to-live (TTL) settings, renamed its configuration and metadata files, and shipped a universal macOS binary for Intel and Apple silicon. This is a historical release guide; 0.4.12 does not identify the current Selenium Manager version.

For most users, the practical change is less manual browser setup. Selenium Manager can obtain Firefox when needed, while options let you choose a browser version or channel and control where downloaded assets and metadata live. The release’s stated default metadata TTL is 3600 seconds (one hour). Selenium’s 0.4.12 release article and its versioned changelog document the changes.

What Selenium Manager 0.4.12 changed

Change What it means
Automatic Firefox management Firefox can be discovered, downloaded, and cached when it is not already available. Stable is the default when no version is requested; a version or channel can be selected.
Configurable asset cache --cache-path, the configuration file, or SE_CACHE_PATH can select the directory for browser and driver assets. The stated default is ~/.cache/selenium.
New configuration and metadata filenames se-config.toml and se-metadata.json are stored at the cache root.
Unified TTL The former browser and driver TTL controls became ttl, with a documented default of 3600 seconds.
Universal macOS binary The manager binary supports x64 and arm64 Macs; Rosetta is no longer mandatory to run the manager on arm64.
Stability fixes The release work also covered driver management, caching, browser-path discovery, metadata, executable permissions, and downloaded binary defaults.

Selenium 4.12.0 was announced on August 31, 2023, after the manager release article was published on August 28. The Selenium release included bindings for Java, .NET, Ruby, Python, and JavaScript, as well as Grid. See the Selenium 4.12.0 announcement.

Firefox management: discovery, versions, and channels

When a Selenium session needs Firefox and no suitable local installation is available, Selenium Manager 0.4.12 can locate a release, download it, and keep it in its cache. With no requested version, the release article describes the manager selecting the latest stable Firefox. The article says this management covers Windows, Linux, and macOS.

A binding’s browserVersion option can request a particular release. The labels stable, beta, dev, and nightly select release channels. Use a fixed version when repeatability matters; use a channel label when following a moving channel is intentional. Channel availability and exact behavior should be checked against the Selenium binding and release in use.

The release credits Mozilla’s public release repository and product-details JSON API as sources that enabled Firefox version discovery. Selenium Manager handles the management flow; it does not mean every machine begins with Firefox preinstalled.

Python example with Firefox

This is a runnable Selenium 4.12-era example. Install the binding with python -m pip install selenium, then save as firefox_example.py and run python firefox_example.py. With no explicit version, the manager can manage stable Firefox when necessary.

from selenium import webdriver
from selenium.webdriver.firefox.options import Options

options = Options()
# To request a channel or version, set the binding's browserVersion capability:
# options.set_capability("browserVersion", "stable")
# options.set_capability("browserVersion", "beta")
# options.set_capability("browserVersion", "120.0")

driver = webdriver.Firefox(options=options)
try:
    driver.get("https://example.com")
    print(driver.title)
finally:
    driver.quit()

The commented capability lines are alternatives: uncomment only the value you want to request. A pinned version may no longer be available from upstream repositories indefinitely; for long-lived reproducibility, control the environment and cache as well as the requested version.

JavaScript example

Install a Selenium 4.12-compatible package with npm install selenium-webdriver, then run this file with Node.js. The browser version capability is optional.

const { Builder, Browser } = require('selenium-webdriver');

(async function main() {
  const driver = await new Builder()
    .forBrowser(Browser.FIREFOX)
    // Optional: request a channel or version, for example:
    // .setFirefoxOptions(new (require('selenium-webdriver/firefox').Options)()
    //   .setBrowserVersion('stable'))
    .build();
  try {
    await driver.get('https://example.com');
    console.log(await driver.getTitle());
  } finally {
    await driver.quit();
  }
})().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Cache path, configuration, and metadata

The default cache directory documented for this release is ~/.cache/selenium. Set --cache-path to relocate it for a particular manager invocation, or configure the path through se-config.toml or SE_CACHE_PATH. A custom path is useful when a CI runner has a persistent workspace or when the default home directory is ephemeral.

The configuration filename became se-config.toml; the metadata filename became se-metadata.json. Both belong at the root of the cache folder. Metadata records versions discovered through network requests and how long those records remain valid. The release unified the old browser_ttl and driver_ttl controls as ttl; its stated default is 3600 seconds.

For a custom directory, create it with permissions that allow the Selenium process to write downloaded binaries and metadata. In containers and CI, make the same path available to later jobs if you expect cache reuse. Keep configuration and metadata together at the cache root so the manager finds the intended state.

Choosing a cache strategy

Environment Practical choice Trade-off
Developer workstation Use the default unless disk layout or permissions require a custom path. Simple setup; cache follows the user’s home directory.
Ephemeral CI worker Use a known writable cache path and persist it between jobs if cache reuse is desired. Persistence reduces repeat downloads but needs cache lifecycle management.
Reproducible test run Request a specific browser version and control the cache/environment. Version pinning improves repeatability, but pinned releases can age out of upstream availability.
Track latest channel Request stable, beta, dev, or nightly as appropriate. Channel contents move over time, so results can change between runs.

macOS architecture support

The 0.4.12 macOS Selenium Manager binary became universal for x64 and arm64. On arm64 Macs, Rosetta was no longer mandatory just to run the manager. This concerns the manager binary; it does not by itself guarantee that every browser, driver, dependency, or test application in a given environment has the desired architecture or compatibility.

How to decide which changes matter

  1. Identify the browser and requested release. Firefox can now be automatically managed; choose stable, a named channel, or a version according to whether you value current behavior or repeatability.
  2. Check the operating system and architecture. The release covers Firefox management on Windows, Linux, and macOS and provides a universal macOS manager binary.
  3. Check where your process can write. If the default home cache is unavailable or transient, set a custom cache path and ensure it is writable.
  4. Decide how much discovery metadata can age. The unified ttl default is one hour. Adjust it only when your environment needs different discovery freshness behavior.
  5. Confirm the actual Selenium release. The 0.4.12 changes shipped with Selenium 4.12.0; do not assume an installation uses this manager version just because it uses Selenium today.

Troubleshooting Selenium Manager 0.4.12

Symptom Likely cause What to check or do
Firefox is not found or downloaded The runtime cannot reach the release metadata or download source, or the cache is not writable. Check network and proxy access, confirm the process can write to the cache, and verify the requested version/channel is valid for the Selenium release.
Unexpected browser version No explicit version was requested, so stable was selected, or a moving channel changed. Set the binding’s browserVersion capability to the desired release or channel and inspect the browser actually launched.
Cache appears ignored The environment variable or command-line option points to a different directory than expected, or the process runs as another user. Check the effective SE_CACHE_PATH/--cache-path, user identity, and whether se-config.toml and se-metadata.json are at the cache root.
Permission denied during setup The selected cache folder or downloaded binary is not writable/executable for the process. Use a directory owned by the runtime user and preserve executable permissions when moving cached binaries.
Repeated network lookups or downloads in CI The worker is ephemeral, or the cache path is not persisted across jobs. Persist the chosen cache directory between jobs when appropriate; otherwise expect a fresh manager setup on each worker.
Different results between runs A channel such as stable or nightly can move, or metadata can be refreshed. Pin a browser version and preserve a controlled cache/environment for repeatable runs.
Arm Mac still has an architecture error The manager is universal, but another component in the browser automation stack may have an architecture constraint. Identify which executable fails and verify that component’s architecture and compatibility separately.

Performance, reliability, and cost

The release notes do not publish performance benchmarks, uptime figures, or cost statistics. Operationally, a populated cache can avoid downloading assets that are already present, while a fresh environment may need network access to discover and download a browser. A custom persistent cache can reduce repeated setup work in CI, but it introduces storage and cache invalidation considerations.

The 3600-second TTL controls how long discovered-version metadata is considered valid; it is not a runtime speed guarantee. Shorter metadata validity can trigger more frequent discovery requests, while longer validity can leave discovery information stale for longer. Browser channel selection also affects reliability: a pinned release offers a steadier target, while a moving channel is useful when the goal is to follow ongoing releases.

Selenium Manager and its browser/driver downloads are software assets. The cited release materials provide no pricing or monetization figures.

Or skip the browser setup

If your task is to save a page image or PDF rather than run an interactive browser test, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before taking the shot; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. AI agents can use its MCP server tools: take_screenshot, get_page_info, and capture_pdf.

For setup and options, see the ScreenshotNeo documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

The free plan includes 1,000 screenshots per month without a card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan.

Sign up for ScreenshotNeo’s 1,000 free monthly screenshots with no card.

FAQ

Is Selenium Manager 0.4.12 the current version?

No. It is the manager version associated with Selenium 4.12.0, a 2023 release. Check the Selenium version installed in your project and its release notes.

Does 0.4.12 manage browsers besides Firefox?

The notable addition in this release was automated Firefox management. The article’s release highlights focus on Firefox and stabilization work.

Does the one-hour TTL expire downloaded browsers?

The release describes metadata validity for versions discovered through network requests. The 3600-second TTL is not described as deleting cached browser binaries after an hour.

Can I use a custom cache directory in CI?

Yes. The release documents --cache-path and SE_CACHE_PATH, along with configuration-file support. Ensure the process can write there and persist it if later jobs should reuse it.

Does a universal macOS manager mean all Selenium components are universal?

No. The release specifically says the Selenium Manager macOS binary supports x64 and arm64. Other components should be checked independently.

Keep reading