# Helium for Python: a lighter wrapper around Selenium

> Helium is a Python library that sits on top of Selenium and lets you address page elements by their visible labels instead of IDs and XPaths. It is a good fit for small automation scripts and a poor fit for anyone who needs a maintained, supported tool.

**mherrmann/helium** — Lighter web automation with Python

- Repository: https://github.com/mherrmann/helium
- Stars: 8,326 · Forks: 512
- Language: Python
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/mherrmann-helium

## The problem Helium solves for Python automation scripts

Selenium drives browsers reliably, but its element lookup is written in the vocabulary of the page source: HTML IDs, XPaths and CSS selectors. Helium keeps Selenium underneath and changes the vocabulary. The README states that Helium lets you refer to elements by user-visible labels, and that scripts written this way are typically 30 to 50 percent shorter than equivalent Selenium scripts. The second claim matters more than the first: a label like Download is tied to what a person sees, while an XPath tied to a generated class name breaks the next time the front end is rebuilt.

The audience is narrow and clear. This is for people writing Python scripts that click through a web application: internal tools, form filling, smoke checks, scraping pages that need a real browser. It is not a test framework, it has no assertion library, and it does not manage test suites. You bring those yourself, or you use it as the driving layer inside one.

## How Helium wraps Selenium, and what that costs

Every Helium call is forwarded to Selenium. That is the whole architecture, and it has a practical consequence: the Selenium driver object you get back from start_chrome() is a normal Selenium object. The README shows the mix directly, calling a Helium function and then driver.execute_script on the result. Nothing is hidden behind a custom transport, so anything Selenium can do to that object still works.

On top of the forwarding, Helium adds four conveniences the README calls out. It interacts with elements inside nested iFrames without an explicit switch. It notices popups opening and closing and moves focus the way a user would, and lets you switch windows by part of the title. It applies an implicit wait of up to 10 seconds by default when you click an element that has not appeared yet. And it replaces Selenium's WebDriverWait plus expected-conditions idiom with a condition object, so wait_until(Button('Download').exists) is the entire expression.

Those conveniences are also the cost. An implicit 10 second wait is a default you did not choose, and in a script that is supposed to fail fast it turns a missing element into a ten second pause. The iFrame handling and the window focus behaviour are the parts most dependent on page structure, so they are the parts most likely to surprise you on an unusual site. The README does not document how to turn the implicit wait off.

## Installing Helium and running a first script

Helium needs Python 3 and Chrome or Firefox. The README recommends a virtual environment so the package stays with the current project. The commands below create one and activate it on macOS or Linux; the README gives call venv\scripts\activate.bat for Windows instead.

```bash
python3 -m venv venv
source venv/bin/activate
python -m pip install helium
```

After that, the README says to enter python at the prompt and run the commands from the animation at the top of the page, starting with the wildcard import. The pattern below is the one the README uses to demonstrate the API shape: start a browser, act on a labelled element, then wait for a condition. Note that start_chrome() returns the Selenium driver, which is why the second line works.

```python
from helium import *

driver = start_chrome()
click(Button('Download'))
wait_until(Button('Download').exists)
driver.execute_script("alert('Hi!');")
```

The README points to docs/cheatsheet.md for a quick tour and to the Read the Docs site for the full reference. It does not walk through a complete worked example in the README itself, so the cheatsheet is where a new user should go next.

## Where Helium is the wrong tool

The README is unusually direct about maintenance. The author writes that he has too little spare time to maintain the project for free, that unless a request is very easy he will usually not respond to emails or issues on the issue tracker, and that he will accept and merge pull requests. That is a workable arrangement for a library whose behaviour you can read in the source. It is a bad arrangement if your team needs a support channel, a release schedule, or someone to fix a break caused by a browser update on a deadline.

There are also scope limits stated in the history section. Helium once had a Java implementation and once supported Internet Explorer; both were dropped, the Java one because the author only uses it from Python, the IE one because he has no need for it. So the supported surface is Python, Chrome and Firefox. If your requirement is a browser outside that pair, this is not the project for it.

One more boundary: Helium is a driver, not a test runner. There is no reporting, no parallel execution, no fixture model. Teams that want those will end up pairing it with something else or choosing a different layer entirely.

## Helium against Playwright and raw Selenium

The honest alternative to Helium is Playwright for Python, and the difference is architectural rather than cosmetic. Playwright ships its own browser builds and its own protocol layer, so it does not depend on the Selenium package or on a separately installed WebDriver. Helium keeps Selenium as the transport and requires selenium>=4.16.0 as declared in setup.py, which means the browser and driver versions on your machine are your problem. In exchange, Helium scripts stay inside the Selenium object model, so existing Selenium code and Selenium knowledge transfer without a rewrite.

The other alternative is plain Selenium, and the README argues against it on length and stability rather than on capability. That argument holds for label-driven pages. It holds less well for pages built from generated markup with no stable visible text, where an explicit selector is the more precise tool and Helium's label lookup gives you nothing to hold on to.

## Licence, releases and the cost of upgrading

Helium is MIT licensed, and setup.py declares the same classifier. The practical effect is that you can use it in closed-source and commercial projects, keep the copyright notice, and not worry about copyleft reaching your own code. This is a description of the licence terms, not legal advice; have your own counsel review anything that matters.

Upgrade cost is low by design. The package has exactly one runtime dependency, selenium>=4.16.0, and the recent release notes describe small, contained changes: v7.0.1 improved a LookupError, v7.0.2 added support for hidden file input elements, and v7.0.3 made select(...) support prefix matches as well. The last push to the repository was on 2026-08-10, so the code has moved recently even though the README asks users not to expect issue replies.

If you contribute, the README sets two concrete rules: follow the existing coding conventions, in particular tabs over spaces, and run the test suite before submitting. The commands below run the tests against Chrome, which is the default; setting TEST_BROWSER to firefox switches the target.

```bash
pip install -Ur requirements/test.txt
python setup.py test
TEST_BROWSER=firefox python setup.py test
```

A note on those commands: they come from the contributing section and use python setup.py test, which is the older setuptools invocation. If your environment has moved past it, that is a place where the README has not kept up.

## Conclusion

Adopt Helium if you want short, readable Python scripts against Chrome or Firefox and you are comfortable reading the source when the documentation is thin. Do not adopt it if you need vendor support, a broad browser matrix, or a maintainer who answers issues. Before committing, check that pip install helium pulls a Selenium version at or above 4.16.0 in your environment, and confirm which browser binary your machine actually has.

## FAQ

### How do I install Helium for Python?

Create a virtual environment with python3 -m venv venv, activate it, then run python -m pip install helium. You need Python 3 and Chrome or Firefox installed.

### Does Helium replace Selenium?

No. The README states that Helium forwards each call to Selenium and that the two libraries can be mixed freely, so you can call Selenium APIs on the driver object Helium returns.

### Which browsers does Helium support?

Chrome and Firefox. The README's history section says the old Internet Explorer implementation was removed, and the Java version was dropped as well.

### Is Helium actively maintained?

The last push to the repository was on 2026-08-10 and it is not archived, but the README states the author has too little spare time to maintain the project for free and will usually not respond to issues unless a request is very easy. He does accept and merge pull requests.

### How do I wait for an element to appear in Helium?

Use wait_until with a condition object, for example wait_until(Button('Download').exists). Helium also applies an implicit wait of up to 10 seconds by default when clicking an element that is not yet present.

### What licence is Helium released under?

MIT. The repository contains a LICENSE.txt file and setup.py declares the MIT License classifier.

## Sources

- [Issues](https://github.com/mherrmann/helium/issues)
- [License: MIT](https://github.com/mherrmann/helium/blob/master/LICENSE)
- [mherrmann/helium on GitHub](https://github.com/mherrmann/helium)
- [README](https://github.com/mherrmann/helium/blob/master/README.md)
- [Releases](https://github.com/mherrmann/helium/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mherrmann-helium