SeleniumHQ/selenium installation guide

Installing Selenium on macOS Tahoe with Apple silicon

What this repository is

[SeleniumHQ/selenium](https://github.com/SeleniumHQ/selenium) is the source repository for Selenium, an Apache-2.0 browser-automation framework and ecosystem. It provides infrastructure for the W3C WebDriver standard and contains language bindings, Selenium Grid, Selenium Manager, tests, documentation, and contributor tooling.

**Claude Code classification: unclassified.** The supplied first-party files do not document a Claude Code plugin, hook, MCP server, skill, or other reliable Claude-specific integration mechanism. The repository is browser-automation infrastructure that Claude Code could potentially help you edit or invoke like ordinary project code, but that is not evidence that Selenium extends Claude Code.

This guide covers the repository’s documented **contributor installation**: preparing a Mac, cloning the source, configuring Apple-silicon builds, and confirming that the build works. The repository README directs ordinary Selenium users to the [Selenium User Manual](https://selenium.dev/documentation/); building this large repository is primarily for people who want to inspect, change, test, or contribute to Selenium itself.

Before you begin

These instructions are specifically adapted to **macOS Tahoe on an Apple-silicon Mac**. The supplied README documents macOS generally and explicitly has an extra Rosetta configuration for Apple silicon, but it does not claim that macOS Tahoe itself has been tested. Expect the first build to download dependencies and take time. The repository metadata reports a large source tree, so make sure you have ample free disk space and a reliable internet connection.

You will need:

1. Xcode and its command-line tools.
2. Rosetta, because the repository currently says it is required for Apple-silicon Macs.
3. A full Java JDK version 17 or newer for the contributor environment.
4. Bazelisk, which reads the repository’s `.bazelversion` and obtains the matching Bazel version.
5. Git so you can clone the public repository.

Do not substitute undocumented package-manager commands in this walkthrough. The supplied files name the required software but do not provide Homebrew, MacPorts, SDKMAN, or other third-party installation commands.

1. Open Terminal

Open **Terminal** from Applications → Utilities. Commands in this guide are entered there one at a time. If macOS displays a permission prompt, read it before approving it. Lines shown as configuration contents are not Terminal commands; they belong in the named file.

2. Install Xcode command-line tools

The Selenium README gives this macOS command:

xcode-select --install

A macOS installer window should appear. Follow its prompts and wait for completion. The repository says Xcode, including its command-line tools, is required and recommends the latest version. If you need the full Xcode application in addition to the command-line tools, obtain the latest version through Apple’s normal interface; no other Xcode installation command is supplied in the repository files.

3. Install Rosetta

The repository explicitly requires **Rosetta for Apple Silicon Macs**, while noting that the project is working to remove this requirement in the future. However, the supplied files do not provide a Rosetta installation command. Install Rosetta using Apple’s normal macOS prompt or interface rather than copying an undocumented command from elsewhere.

Rosetta alone is not the complete repository configuration. After cloning Selenium, you will also create a local Bazel settings file as described below.

4. Install a Java JDK

Install a complete **Java Development Kit version 17 or newer**. The README points to [Java 17 Temurin](https://adoptium.net/temurin/releases/?version=17) as an example. On the download page, select a macOS build appropriate for Apple silicon and follow the vendor’s installer.

The contributor README requires `JAVA_HOME` to point to the JDK rather than a Java Runtime Environment. It does not provide a safe universal command for setting that variable on macOS, because the correct path depends on which JDK package and version you install. Use the JDK installer’s documented macOS setup and ensure `JAVA_HOME` identifies that JDK.

Test whether the Java compiler is available:

javac

This check is successful for the purpose described by Selenium if it prints a list of compiler options. If Terminal says the command does not exist, you either installed only a runtime or the JDK is not configured correctly. Fix that before proceeding.

Although `java/README.md` says the published Java bindings require Java 11 or newer, the top-level contributor environment has the stricter requirement of **JDK 17 or newer**. Use the stricter version when building this repository.

5. Install Bazelisk

Install [Bazelisk](https://github.com/bazelbuild/bazelisk). Selenium describes it as a Bazel wrapper that automatically downloads the version specified by the repository’s `.bazelversion` file and forwards command-line arguments to Bazel.

The supplied Selenium files do not include a macOS Bazelisk installation command, so use Bazelisk’s first-party installation instructions rather than an unsourced command. Once installed, later `bazel` commands should use the repository-selected Bazel version.

6. Clone the public repository

Choose a parent folder in which you are comfortable storing a large development project. In Terminal, move to that folder using normal Finder and Terminal navigation, then clone the HTTPS URL supplied by the GitHub metadata:

git clone https://github.com/SeleniumHQ/selenium.git

Enter the newly created checkout:

cd selenium

The default branch in the supplied metadata is `trunk`. No account credentials should be necessary merely to clone this public repository over HTTPS.

7. Add the Apple-silicon Bazel setting

In the repository’s top-level folder, create or open a file named `.bazelrc.local` with a plain-text editor. Add exactly this source-documented line:

build --host_platform=//:rosetta

Save the file at the repository root—the same directory that contains the top-level build files. This setting tells Bazel builds to use the repository’s Rosetta host platform. Do not enter the line directly into Terminal; it is Bazel configuration-file content.

The repository also documents optional cache settings and worktree-specific output locations, but those are not required for a first checkout. Its cache examples contain placeholder paths, so they are intentionally omitted from the copy-paste steps here.

8. Confirm the build environment

Selenium uses Bazel to download dependencies, compile source, generate artifacts, and run tests. A focused first build is more approachable than building every language binding.

From the repository root, build Selenium Grid using the documented alias:

bazel build grid

The first run may be slow because Bazelisk may obtain the selected Bazel release and Bazel may download project dependencies. The log should report where the resulting Grid JAR is located. A completed build is the clearest supplied confirmation that Xcode tools, Rosetta configuration, Java, Bazelisk, networking, and the checkout are working together.

If you intend to work on a particular language, Selenium documents this build form:

./go <language>:build

Here, `<language>` is a placeholder and must be replaced with the binding you are actually developing. Because a command containing that placeholder is not directly runnable, do not paste it unchanged. Consult the relevant language directory and Selenium contributor documentation before choosing a target.

9. Optional, documented checks

For a smaller test category, Selenium documents Bazel test filtering by language and size. Its examples contain a `<language>` placeholder, so this guide does not turn them into an invented language-specific command. Read the applicable directory’s `TESTING.md` before running browser tests; large tests may open and control a real browser.

If your goal is Python development from this checkout, the repository documents installing its locked Python dependencies and generating local files, but it also recommends a virtual environment because local installation can otherwise target global site-packages. The supplied files do not provide the virtual-environment creation commands, so that workflow is best followed only after reading the linked Python Packaging guidance.

For Ruby users who do **not** need the source checkout, the first-party Ruby README offers a simpler published-package installation. It requires MRI Ruby 3.3 or newer:

gem install selenium-webdriver

That package uses Selenium Manager to handle browser-driver installation automatically. This is separate from preparing the full contributor repository above.

10. What success looks like

Your source setup is ready when all of the following are true:

• `javac` is found and prints compiler options.
• The repository is present in a local `selenium` folder.
• `.bazelrc.local` contains the Rosetta host-platform line.
• `bazel build grid` finishes successfully and reports the built output.

For usage examples, language APIs, browser automation concepts, and Selenium Manager behavior, continue with the [Getting Started documentation](https://www.selenium.dev/documentation/webdriver/getting_started/). For project-specific help, use the [official support page](https://www.selenium.dev/support/) or the repository’s [GitHub Issues](https://github.com/SeleniumHQ/selenium/issues). Before submitting changes, read the repository’s linked `CONTRIBUTING.md`.