Building and installing

How to build seleniumbase-rs from source, which features cost what, and how to run it in a container. For writing and running tests with it, start with Getting started; for working on the crate, see CONTRIBUTING.md.

What you need#

Pick your system below and paste its box into a terminal. Each box installs what every build needs: Rust 1.99 (the repository’s rust-toolchain.toml selects it), a C compiler, and Google Chrome. The extras for single features come after. Nothing here needs Python.

Let an AI assistant do it#

Paste this into an AI coding assistant that can run commands on your machine (Claude Code, Cursor, Copilot and the like):

xcode-select --installcurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -ybrew install --cask google-chrome

brew install --cask microsoft-edge firefoxbrew install chromedriver geckodriver

sudo safaridriver --enable

sudo apt-get updatesudo apt-get install -y build-essential pkg-config curlcurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.debsudo apt-get install -y ./google-chrome-stable_current_amd64.deb

sudo apt-get install -y chromium firefox-esr

sudo apt-get install -y xvfb

sudo dnf install -y gcc gcc-c++ make pkgconf-pkg-config curl chromiumcurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

winget install Rustlang.Rustupwinget install Microsoft.VisualStudio.2022.BuildTools --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"winget install Google.Chrome

winget install Mozilla.Firefox

Check it worked#

git clone https://github.com/MustCodeAl/seleniumbase-rs.gitcd seleniumbase-rscargo build --bin sbrs./target/debug/sbrs doctor

git clone https://github.com/MustCodeAl/seleniumbase-rs.gitcd seleniumbase-rscargo build --bin sbrs.\target\debug\sbrs.exe doctor

Extras for single features#

Most features need nothing more: tui, mcp-server, turso, playwright, azure, gcp, full-tracing, test-util, ocr, visual, plugins and the built-in plugins (plugin-shield, plugin-block-resources, plugin-crx, or plugins-builtin for all of them). The rest:

sudo apt-get install -y libssl-dev pkg-config

sudo apt-get install -y libgtk-3-dev libx11-dev libxdo-dev libxkbcommon-dev libxtst-dev libssl-dev pkg-config

sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libgtk-3-dev libssl-dev libx11-dev libxdo-dev

What has been built where#

The Linux gui and Tauri package lists come from the CI configuration, which has not been able to run (see Operating systems).

Build#

git clone https://github.com/MustCodeAl/seleniumbase-rs.gitcd seleniumbase-rscargo build --release --locked --bin sbrs        # the CLIcargo build --release --locked --bin sbrs-mcp    # the MCP server

The repository is a Cargo workspace of two packages: the library seleniumbase-rs at the root, and the command line seleniumbase-rs-cli in crates/cli, which holds both binaries. A project that depends on the library compiles none of the command-line crates. sbrs is always built; sbrs-mcp needs the mcp-server feature, which the command-line package turns on by default together with pdf. To put the binaries on your PATH:

cargo install --path crates/cli                       # sbrs and sbrs-mcpcargo install --path crates/cli --features tui        # and the terminal UI

Neither package is published to crates.io, so cargo install seleniumbase-rs-cli does not work; build from a checkout, install from git as below, or add the library as a git dependency.

Install without a checkout#

Three ways to get sbrs and sbrs-mcp (the package seleniumbase-rs-cli) onto your PATH without cloning the repository. None of them uses crates.io.

Each release archive (seleniumbase-rs-v<version>-<target>.tgz, .zip on Windows) holds these at its root:

SHA256SUMS lists the checksum of every archive.

cargo binstall#

cargo-binstall downloads the release archive for your system instead of compiling. crates/cli/Cargo.toml tells it where the archives are ([package.metadata.binstall]). With --git it reads that manifest from the repository, so no crates.io entry is needed:

cargo binstall --git https://github.com/MustCodeAl/seleniumbase-rs seleniumbase-rs-cli

It installs both binaries. Two things to know: --git takes the default branch, so it fetches the release whose version the branch’s Cargo.toml names, and that release must have its archives; and the metadata turns off the compile fallback, because cargo-binstall would compile from crates.io, where the crate is not. cargo-binstall installs no completions: write them with sbrs completions <shell> (see the CLI page).

mise#

mise has two backends that fit.

mise use -g github:MustCodeAl/seleniumbase-rs

[tools."github:MustCodeAl/seleniumbase-rs"]version = "latest"

mise use -g 'cargo:https://github.com/MustCodeAl/seleniumbase-rs@tag:v0.2.0'

[tools."cargo:https://github.com/MustCodeAl/seleniumbase-rs"]version = "tag:v0.2.0"

mise installs no completions for these backends either; its per-tool postinstall option can run sbrs completions zsh into your completions folder.

Homebrew#

The tap builds from the release’s source and installs the completions and the Warp workflows as well (macOS and Linux):

brew install mustcodeal/tap/sbrs

cargo install from git#

What the methods above do when there is no archive, by hand:

cargo install --git https://github.com/MustCodeAl/seleniumbase-rs seleniumbase-rs-cli --locked

That builds sbrs and sbrs-mcp; add --no-default-features for sbrs alone, without PDF text extraction. For a tag up to v0.4.0 the binaries are in the package seleniumbase-rs: cargo install --git https://github.com/MustCodeAl/seleniumbase-rs --tag v0.4.0 --features mcp-server --locked.

Features#

No feature of the library is on by default, so a plain build is small and pulls in none of the desktop or cloud stacks. The command-line package seleniumbase-rs-cli turns pdf and mcp-server on by default and forwards tui, gui and turso to the library; the rest of the features below belong to the library. Build the library alone, with its own defaults, with cargo build -p seleniumbase-rs.

Combine them with --features "mcp-server tui". The features scrape and impersonate were removed in 0.3.0; see Stealth Scraping.

Check your build#

sbrs --helpsbrs doctor          # compares the chromedriver version with Chrome'ssbrs install         # fetches the chromedriver that matches your Chrome

Container#

The Dockerfile builds sbrs with locked dependencies in a Rust 1.99 stage and copies it into a debian:bookworm-slim image with Chromium and its driver. It runs as a non-root user (sbrs) and has no EXPOSE, because sbrs is a command-line tool. The driver in /usr/bin is linked as downloaded_drivers/chromedriver in the working directory, which is where the WebDriver engine looks first, so the image needs no network to start a browser.

docker build -t seleniumbase-rs .docker run --rm seleniumbase-rs --helpdocker run --rm seleniumbase-rs doctordocker run --rm --network none --shm-size=1g seleniumbase-rs --headless smoke \    'data:text/html,<title>Smoke</title><h1>hi</h1>' --title-contains Smoke

• On a machine with little memory, limit Cargo’s parallelism in the build: docker build --build-arg CARGO_BUILD_JOBS=2 -t seleniumbase-rs .
• The arguments after the image name are sbrs arguments. --headless comes before the subcommand. sbrs open and smoke also read SB_HEADLESS (and the other SB_* variables; --headless beats the variable), and without one of them Chromium fails in a container for lack of a display.
• Drop chromium-driver from the Dockerfile if you only use the pure CDP engine (and then drop the ln -s step that links it).

Run the tests in a container#

docker/Dockerfile.verify is a throwaway image for the test suite: the Rust toolchain, Debian’s Chromium and chromedriver, and Xvfb. docker/verify-linux.sh is its entry point: it copies the read-only checkout mounted at /src to /work, so tests that write beside their sources cannot touch your tree, and then runs your command there. The build output lives in a named volume (about 4.4 GB when these runs still built the stealth layer too), and the Cargo registry in another.

docker build -f docker/Dockerfile.verify -t seleniumbase-rs:verify-tools .docker volume create sbrs-verify-targetdocker volume create sbrs-verify-registry# Run a command on a copy of this checkout. 4 GB and two Cargo jobs fit an 8 GB machine.run() {  docker run --rm --memory=4g --memory-swap=4g --shm-size=1g -e CARGO_BUILD_JOBS=2 \    -v "$PWD":/src:ro -v sbrs-verify-target:/target \    -v sbrs-verify-registry:/usr/local/cargo/registry \    seleniumbase-rs:verify-tools "$@"}run cargo test --locked --features "mcp-server test-util" --no-fail-fast --lib --testsrun cargo test --locked --features "mcp-server test-util" --no-fail-fast --doc \    -- --test-threads=2# A real-browser binary, one at a time:run cargo test --locked --features "mcp-server test-util" --test sb_cdp_chrome \    -- --ignored --test-threads=1# A test that needs a headed Chrome gets a virtual display:docker run --rm --memory=4g --memory-swap=4g --shm-size=1g -e SBRS_XVFB=1 \    -e CARGO_BUILD_JOBS=2 -v "$PWD":/src:ro -v sbrs-verify-target:/target \    -v sbrs-verify-registry:/usr/local/cargo/registry seleniumbase-rs:verify-tools \    cargo test --locked --features "mcp-server test-util" --test NAME_chrome \    -- --ignored --test-threads=1

The image sets CI=true and SB_NO_SANDBOX=1 (Chromium cannot start its sandbox as root in a container, and the real-browser tests read CI) and SB_HEADLESS=true. The results, and what they showed, are under Verified on Linux. Remove everything when you are done:

docker rmi seleniumbase-rs:verify-tools seleniumbase-rsdocker volume rm sbrs-verify-target sbrs-verify-registry

Adding a [[bin]], [[example]], [[bench]] or [[test]] to Cargo.toml also needs a line in the Dockerfile skeleton step, or the image build fails; tests/dockerfile_skeleton.rs checks it.

Build time and disk#

A cold build compiles a large dependency tree, and a development target/ directory with the test, bench and check artifacts grows past 10 GB. To keep rebuilds cheap:

export CARGO_BUILD_JOBS=2 CARGO_INCREMENTAL=0 CARGO_PROFILE_DEV_DEBUG=0

• Install sccache and set [build] rustc-wrapper = "sccache" in ~/.cargo/config.toml; it needs CARGO_INCREMENTAL=0 to cache anything. It adds its own cache directory (limit its size) and does not shrink target/.
• On a machine with little memory, keep CARGO_BUILD_JOBS low and run one cargo command at a time; cargo serialises builds in the same target directory.

Build the documentation#

cargo install mdbook

mdbook build           # writes the book to book/

mdbook serve --open    # live preview while editing

The generated docs/parity.md is not edited by hand: just parity-docs rebuilds it from parity/api.toml.

The Docs7 site#

The same pages also publish as a Docs7 site. docs/docs.json is its configuration, and its navigation follows docs/SUMMARY.md.

python3 -I tools/docs7_nav.py

npx --yes @upstash/docs7 dev ./docs --port 4317

Operating systems#

What differs between macOS, Linux and Windows when you build and run seleniumbase-rs. The CI workflow (.github/workflows/ci.yml) is set up to build and test on all three, but has not been able to run yet; day-to-day development and the project’s own checks run on macOS (Apple silicon), so macOS is the best-trodden path, and Windows 11 was checked by hand (see Windows). The test suite was also run on Linux (arm64, Debian 12, Chromium 154) in a container; what passed, and what was not run, is under Verified on Linux.

The packages each system and each feature needs, with the commands that install them (Homebrew, apt, dnf, winget), are in Building and installing.

Which Chrome it finds#

The library looks in the usual install locations, and you can always name one:

For the WebDriver engine, sbrs install downloads the chromedriver that matches your Chrome’s major version, and CHROMEDRIVER_PATH points at one you already have. The pure CDP engine (sb_cdp) needs no chromedriver on any system.

The WebDriver engine looks for downloaded_drivers/chromedriver in the working directory first and uses it when its major version fits the browser; otherwise it downloads the matching Chrome for Testing driver. That download is linux64 on x86-64 Linux and linux-arm64 on arm64 Linux, which Chrome for Testing publishes from Chrome 153 on; for an older Chrome on arm64, or any other Linux architecture, the error says that no build is published and where to put a driver. A driver from your distribution works the same way: link it into that folder, as the repository’s Dockerfile does, and no network is needed:

mkdir -p downloaded_drivers && ln -s /usr/bin/chromedriver downloaded_drivers/chromedriver

Firefox and Edge#

A Firefox session starts geckodriver and an Edge session msedgedriver, as Python SeleniumBase does. Each is looked for in downloaded_drivers/ (right in it, or in the newest geckodriver-v<version>/ or msedgedriver-<version>/ folder there) and then on the PATH, so a Homebrew or distribution geckodriver is used as it is. When none is found:

The archives (tar.gz for geckodriver on Linux and macOS, zip otherwise) are capped at 64 MB, unpacked without writing outside their folder, and made runnable the way chromedriver is: the execute bit, and on macOS no quarantine flag and, if the system kills the driver as it starts, a new ad-hoc signature. Edge is looked for at /Applications/Microsoft Edge.app on macOS, Microsoft\Edge\Application\msedge.exe under Program Files, Program Files (x86) and the per-user folder on Windows, and microsoft-edge, microsoft-edge-stable or /opt/microsoft/msedge/msedge on Linux. Microsoft publishes no msedgedriver for arm64 Linux.

The session’s options go in moz:firefoxOptions (headless, arguments, preferences, the user agent and locale as preferences, browser_binary_path as the Firefox program and user_data_dir as -profile) and ms:edgeOptions (the same options Chrome gets). Chrome-only settings such as extensions, mobile emulation and the CDP and UC modes have no Firefox equivalent and are not sent; the session proxy is not passed to Firefox either.

macOS#

• A freshly written or replaced executable is slow the first time. macOS scans it on first run, which can take seconds. The library writes a replaced chromedriver as a new file because macOS kills a signed binary that is overwritten in place; if a driver is “killed” or refused, run sbrs install again and see Common problems.
• Gatekeeper and quarantine. A browser or driver downloaded by another tool can carry a quarantine flag; clear it with xattr -d com.apple.quarantine <file> if macOS refuses to open it.
• Tests that fake java or other scripts must run the script once before timing it, for the same first-run reason.
• Memory. On an 8 GB machine keep CARGO_BUILD_JOBS low and run one cargo command at a time.

Linux#

• Install a browser from your distribution (chromium and, for the WebDriver engine, chromium-driver on Debian and Ubuntu) or use Google Chrome’s own package. The repository’s Dockerfile shows the Debian setup.

• Running as root or in a container usually needs --no-sandbox. The WebDriver engine always passes it on Linux. For the pure CDP engine set SB_NO_SANDBOX (it is read as set or not set: SB_NO_SANDBOX=0 also turns the sandbox off), or call LaunchOptionsBuilder::no_sandbox(true). The real-browser tests of this repository read CI instead and pass --no-sandbox when it is set.

  Warning

  --no-sandbox weakens Chrome’s isolation, so use it only in a container you control.

• No display. Run headless (SB_HEADLESS=true, which sbrs open and the other browser commands read, or --headless before the subcommand; see Headless and headed browsers). To see a window on a server, or to run the few tests that need a headed Chrome (the measurement tools), run under a virtual display such as Xvfb. Start Xvfb in the background and export DISPLAY; xvfb-run can wait forever for a signal that a background process ignores. The gui feature (native dialogs and GUI automation) links GTK and X11 and is off by default; the tui feature has no such requirement.

• Shared memory. In Docker, Chromium can crash under load with the default /dev/shm; start the container with --shm-size=1g (general Chromium advice).

• Wayland. The gui feature’s input automation targets X11; the project has not tested it under Wayland.

Verified on Linux#

Run on 2026-10-11 to 12 with docker/Dockerfile.verify and docker/verify-linux.sh (commands in Building and installing). The host was an Apple-silicon Mac, so the containers were linux/arm64 on Debian 12 (bookworm) with Rust 1.99 and Chromium 154.0.8037.92 from Debian’s chromium and chromium-driver packages. Cargo ran with CARGO_BUILD_JOBS=2 in a container limited to 4 GB.

What the runs showed:

• A real bug, fixed: the chromedriver download used the x86-64 linux64 build on every Linux machine, so an arm64 container failed with “chromedriver exited as it started”. It now asks for linux-arm64: sbrs install in the arm64 image fetches an aarch64 executable, and browser_smoke (7 tests) starts Chromium through a driver it downloaded that way.
• Container limits, not bugs: the doc tests need -- --test-threads=2 in 4 GB (with eight threads the linker was killed for lack of memory in 66 of them); a headed browser needs a display, which Xvfb gives; Chromium needs --no-sandbox as root.

Windows#

Status: on Windows 11 x64 (Rust 1.99, Chrome 154 and 155, Edge 155, Firefox 153) formatting, clippy, the whole test suite and the real-browser tests pass, and the Tauri example builds its .msi and setup .exe. (The stealth layer, then the impersonate feature, built and passed there too; it now lives in seleniumbase-rs-stealth with its CMake, NASM and LLVM requirements.) Install steps: Building and installing.

What works differently

• The Chrome and Edge version comes from the program file’s own version (chrome.exe --version prints nothing on Windows). While an update waits for a restart, that is still the version that runs, so the right driver is fetched.
• Download folders are given to Chrome as plain C:\... paths.
• Build in a short folder (C:\src\seleniumbase-rs) if a deep target\ path hits the 260-character limit. In Rust code, use raw strings for Windows paths.

WSL and remote machines#

Run the Linux steps inside WSL. A browser inside WSL has no display unless you use WSLg or run headless. To drive a browser on another machine, run sbrs-mcp or your tests there, or point the WebDriver engine at a Selenium Grid (sbrs grid) with BrowserConfig::webdriver_url.

Check the setup on any system#

sbrs doctor       # Chrome and chromedriver versions, and whether they matchsbrs install      # fetch the matching chromedriver

From an AI agent, the MCP tool diagnose_environment reports the same plus the platform, the redacted SB_* settings and the output directory.