Installation

Browser is a Python library that drives Playwright running in Node.js, so something has to supply that Node.js. There are two ways to do it, and the only real decision at install time is which.

Both need Python 3.10 or newer, and both should be done in a virtual environment.

Choose a route

Start on the left. It is fewer moving parts, and in an environment where installing Node.js means a ticket and a wait, it removes the whole conversation.

Go right when something in that column is yours: a platform with no wheel, a JavaScript extension that needs npm packages Browser does not ship, or an existing Node toolchain you would rather Browser used.

The two are not exclusive and not a one-way door. They differ only in where the Node.js comes from — the keywords, the arguments and the behaviour are the same either way — so switching later costs an uninstall and a reinstall, not a rewrite.

Without Node.js

Install

The [bb] extra pulls in robotframework-browser-batteries, a platform-specific wheel carrying an unmodified official Node.js build, the gRPC wrapper and its production Node dependencies. It is not a single packed binary: it is a real node and a real node_modules, installed into site-packages/BrowserBatteries/bin/.

Which Node.js that is moves with the library, so it is a fact about a release rather than about the package. The release notes say which Node.js the BrowserBatteries wheel was built with — check there for the release you are installing.

The quotes are for zsh, which is the default shell on macOS and treats bare square brackets as a glob. bash and PowerShell do not need them and do not mind them.

The two packages are tied to one version and having them differ is not supported. That is what the extra buys beyond a shorter line: pip resolves both from a single constraint, so they cannot drift apart.

Where there is a wheel

A wheel is published for each of these, and tagged so that pip declines to install it where the bundled Node.js could not start:

There is no musl wheel, and none for Windows on arm. Anywhere else, pip reports that it found no matching distribution — which is the wheel tags doing their job, and the signal to use the other route.

Browser binaries

Playwright's browser builds are downloaded separately, because they are not in the wheel:

Three engines, a few hundred megabytes, once per environment. Name one to get only that one — rfbrowser install firefox.

You can also skip this step entirely. If you already have a Chromium-based browser — Chrome or Edge — you can drive that instead by passing a channel to New Browser, and download nothing:

New Browser    chromium    channel=chrome

That combination — wheels only, no binary download — is what makes this route work on a machine with no route to the public internet at all.

Verify

It reports the Playwright as Required rather than Installed here, because reading the installed version means asking npm, and there is no npm on this route. The number is the one that ships in the wheel either way.

Note what it does not report: the browser binaries. rfbrowser --version staying green says nothing about whether rfbrowser install ever ran.

Upgrading

Upgrade both packages together, then rebuild the Node side:

clean-node removes the old Node dependencies and browser binaries. Skipping it leaves the previous release's binaries behind, and a Playwright that has moved on does not necessarily drive them.

Uninstalling

clean-node first, and in that order: it is what deletes the browser binaries, and once pip has removed the package there is nothing left that knows where they were.

With Node.js

Install

Install Node.js first — at the time of writing that is 22, 24 or 26, and each release states the lines it supports in its release notes. Make sure npm is on your PATH. Then:

Node dependencies and browser binaries

One command does both, and the library does not work until it has run:

init runs npm ci --omit=dev against the lockfile shipped in the package, then downloads the browsers. Name engines to narrow the download — rfbrowser init chromium firefox — or pass --skip-browsers to install the Node dependencies alone and take responsibility for the binaries yourself.

Do not add npm packages to Browser/wrapper by hand either. init runs npm ci there, which deletes node_modules and reinstalls exactly the shipped production dependencies, so anything you put there disappears at the next init or upgrade. Extensions that need their own packages are covered in JavaScript extensions.

Verify

Installed rather than Required means the number came from npm list in the wrapper directory — so a line reading Installed is also evidence that init got as far as writing node_modules. It still says nothing about the browser binaries.

Upgrading

clean-node between the two is not optional housekeeping. npm ci reinstalls from the new lockfile, but the browser binaries from the previous release are outside its reach and stay until something deletes them.

Uninstalling

Behind a proxy, or offline

Both routes reach the network, but for different things, and that is the whole of what changes here.

Without Node.js there is one download — the browser binaries — and it can be avoided altogether by driving an installed Chrome or Edge through channel. Wheels themselves can travel by hand: pip download robotframework-browser-batteries on a connected machine gets you the pair, and they install from a directory on the target with no index at all.

With Node.js there are two: npm resolving the wrapper's dependencies, and Playwright fetching the binaries. Both have to work, and an internal npm registry usually has to be configured before the first init.

The browser download itself is Playwright's, and so are the variables that steer it through a proxy, a custom certificate authority or an internal mirror. They reach Playwright unchanged from either route, and Playwright documents them — we deliberately do not copy the list, because a copy is wrong the day it changes.

Never install into the system Python

For Node.js on the second route, use a version manager for the same reason: n or nvm on Linux and macOS, nvm-windows or nodist on Windows.

Where the files actually land, and what the two halves do at run time, is how Browser works.