Skip to content
Get packs

Guide · Open source

How to use SeleniumBase: install, run a browser and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

SeleniumBase is an open-source Python framework for controlling web browsers. People use it to automate browser tasks, write end-to-end tests of websites, and scrape web pages. This guide shows how to install it with pip, run a short script that launches a stealth browser through CDP Mode, and decide whether it fits your project.

SeleniumBaseseleniumbase/SeleniumBase · ★ 13.2k · MIT

Quick start

  1. 1Check Python. Confirm Python is installed, since it is the prerequisite named in the source.
  2. 2Install the package. Run pip install seleniumbase to install SeleniumBase from PyPI.
  3. 3Create a script. Save the CDP Mode example in a Python file, such as one starting with raw so it runs with python.
  4. 4Run the script. Execute the file with python to launch the stealth browser and follow the steps.
  5. 5Add tests. For test files, name them starting or ending with test and run them with pytest.
  6. 6Close the browser. Call sb.quit() at the end so the browser closes before the program exits.

What SeleniumBase is and who it is for

SeleniumBase is a Python framework for controlling web browsers. Its README describes it as one framework for browser automation, web scraping, and testing.

It is a good fit for Python developers writing automated browser tests, people who already use Selenium or pytest and want a higher-level API, and developers building scrapers for sites that block standard automated browsers. Teams that want AI agents to drive a browser can use its MCP server.

Install SeleniumBase with pip

The only prerequisite named in the source is Python. Install the package from PyPI with pip.

  • Make sure Python is installed on your machine.
  • Run the install command in your terminal or command prompt.
pip install seleniumbase

Run a stealth browser with CDP Mode

CDP Mode is the feature the README highlights for bot-detection. The example below imports sb_cdp, launches a stealth browser, opens a page, checks for an element, and then quits the browser. The README notes that this example bypasses BrowserScan, Sannysoft, and Cloudflare bot-detection.

The script also shows how to type into fields, click an element, and call solve_captcha() on a login page. Always call sb.quit() before the program ends so the browser closes.

  • sb_cdp.Chrome() launches the stealth browser.
  • sb.goto() opens a URL.
  • sb.assert_element() checks that an element is present.
  • sb.quit() closes the browser.
from seleniumbase import sb_cdp sb = sb_cdp.Chrome() # Launch a stealth browser sb.goto("https://browserscan.net/bot-detection") sb.assert_element('strong:contains("Normal")') sb.sleep(1) sb.goto("https://bot.sannysoft.com/") sb.assert_element(".passed") sb.assert_element_not_visible(".failed") sb.sleep(1) sb.goto("https://www.planetminecraft.com/account") sb.type('[name="email"]', "Name123") sb.type('[name="password"]', "Pass") sb.click("input#autologin") sb.solve_captcha() # Works on different CAPTCHAs sb.assert_element('input[name="login"]') sb.assert_element_not_visible("input[disabled]") sb.sleep(1) sb.quit() # Quit browser before end-of-program

Write tests with pytest

The README says example scripts that start or end with "test" are designed to be run with pytest. Other scripts run directly with raw python, and those start with "raw" to avoid confusion.

Use this naming pattern to tell which runner a script needs. Check the examples folder in the project repository for working files.

  • Test files: name them starting or ending with "test" and run them with pytest.
  • Plain scripts: name them starting with "raw" and run them with python.

Know the limits before you rely on it

The README says CDP Mode is meant to get past bot-detection and CAPTCHAs, but it does not guarantee this. Sites change their defenses, so a script that works today may fail later.

SeleniumBase is Python-based. If you need a no-code tool or a language other than Python, it is not the right choice.

  • Expect to write Python code; it is not a no-code tool.
  • Do not treat bypassing bot-detection or CAPTCHAs as guaranteed.
  • Test your scripts again when target sites change.

What people use it for

  • Automating browser tasks such as filling in and submitting forms
  • Writing end-to-end tests of websites in Python
  • Scraping web pages that block standard automated browsers
  • Letting AI agents drive a browser through the included MCP server

Frequently asked questions

How do I install SeleniumBase?

Install it from PyPI with pip install seleniumbase. The README lists Python as the prerequisite.

Is SeleniumBase free to use?

SeleniumBase is released under the MIT licence, according to the project's README and repository metadata. Check the LICENSE file in the repository for the full terms.

Does SeleniumBase bypass CAPTCHAs?

The README says CDP Mode includes stealth options for bypassing bot-detection and CAPTCHAs and shows a solve_captcha() call. It makes no guarantee, and sites change their defenses, so results can vary.

Is SeleniumBase better than Selenium?

SeleniumBase is described as a higher-level API that builds on tools many Selenium and pytest users already know. Whether it fits better depends on your project; Selenium, Playwright, Cypress and Puppeteer are comparable projects.

Does SeleniumBase work with Playwright?

The README says it can add stealth to Playwright. The project's Stealthy Playwright example covers this.

Does SeleniumBase require coding?

Yes. The source says it requires writing Python, so it is not a no-code tool.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

SeleniumBase suits Python developers who write browser tests, scrapers or agent-driven browser tasks and want a higher-level API. Pick something else if you need a no-code tool, a language other than Python, or a guaranteed way past bot-detection, since the README makes no such guarantee.

Install options & downloads