Install & Compatibility
Where this runs
tested against v2.1.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.007s · 65.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.9s · import 0.007s · 66MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Axe
✓ from axe_selenium_python import Axe
webdriver
✓ from selenium import webdriver
Standard Selenium import, not part of axe-selenium-python directly.
This quickstart demonstrates how to initialize a Selenium WebDriver, inject the axe-core script using `Axe().inject()`, run accessibility checks with `Axe().run()`, and optionally save the results to a JSON file and report violations. It's crucial to have a compatible browser driver (like geckodriver or chromedriver) installed and accessible in your system's PATH.
import os
from selenium import webdriver
from axe_selenium_python import Axe
# Configure a browser (e.g., Firefox or Chrome)
# Ensure the appropriate WebDriver (e.g., geckodriver, chromedriver) is in your PATH
# For Chrome, you might need: driver = webdriver.Chrome()
driver = webdriver.Firefox()
try:
driver.get("http://www.google.com")
axe = Axe(driver)
# Inject axe-core javascript into the page
axe.inject()
# Run axe accessibility checks
results = axe.run()
# Write results to a JSON file
output_dir = "a11y_reports"
os.makedirs(output_dir, exist_ok=True)
axe.write_results(results, os.path.join(output_dir, 'google_a11y.json'))
# Assert no violations are found (optional)
if len(results["violations"]) > 0:
print("Accessibility Violations Found:")
print(axe.report(results["violations"]))
# assert False, "Accessibility violations found!"
else:
print("No accessibility violations found.")
finally:
driver.quit()
Debug
Known issues
breakingThe `Axe` class method `execute` was renamed to `run` in version 2.1.5 (or a direct pre-cursor to 2.1.6) to align with the axe-core API. Code using `axe.execute()` will fail.fixReplace calls to `axe.execute()` with `axe.run()`.
affects: >=2.1.5
gotchaThe `axe-selenium-python` package on PyPI, specifically version 2.1.6, is considered to be in maintenance mode, with its last significant update in 2018. For active development, newer Python/Selenium compatibility, and up-to-date axe-core integration (e.g., axe-core@4.x), consider using community-maintained forks like `django-commons/axe-selenium-python` which is more current (e.g., version 3.0+).fixFor new projects or if encountering compatibility issues with modern Python/Selenium, evaluate using `pip install django-commons-axe-selenium-python` (check the exact package name as forks might vary) and adjust imports if necessary (e.g., `from django_commons_axe_selenium_python import Axe`). Always refer to the latest fork's documentation.
affects: All 2.x versions
gotchaSome functionalities, such as specific helper methods and advanced reporting, were moved to a separate package `pytest-axe` starting from version 2.0.0. If you rely on these features, you will need to install and use `pytest-axe` in conjunction with `axe-selenium-python`.fixInstall `pytest-axe` (`pip install pytest-axe`) and consult its documentation for moved functionalities.
affects: >=2.0.0
gotchaThe `axe-selenium-python` library requires a compatible browser WebDriver (e.g., Chromedriver for Chrome, Geckodriver for Firefox) to be installed on your system and available in your system's PATH environment variable. Failure to do so will result in Selenium not being able to launch the browser.fixDownload the appropriate WebDriver for your browser and operating system (e.g., from `chromedriver.chromium.org` or `github.com/mozilla/geckodriver/releases`), place the executable in a directory, and add that directory to your system's PATH.
affects: All versions
Errors
Common errors & fixes
WebDriverException: Message: 'chromedriver' executable needs to be in PATH.
Selenium cannot find the executable for the Chrome browser driver because it's not in the system's PATH.
fixDownload `chromedriver` from `chromedriver.chromium.org` and place the executable in a directory that is included in your system's PATH environment variable. Alternatively, specify the `executable_path` when initializing the Chrome driver: `webdriver.Chrome(executable_path='/path/to/chromedriver')`.
Getting empty results even though there are violations on the page
Axe-core might not be able to detect violations for elements that are hidden or not fully rendered when `axe.inject()` or `axe.run()` is called. This can also happen if the `context` or `options` parameters are too restrictive.
fixEnsure that the elements you wish to test are visible and fully loaded on the page before calling `axe.inject()` and `axe.run()`. Use Selenium's explicit waits (`WebDriverWait`) to ensure elements are present and visible. Review the `context` and `options` passed to `axe.run()` to ensure they are not inadvertently excluding relevant parts of the page.
AttributeError: 'Axe' object has no attribute 'execute'
Attempting to call the `execute` method on the `Axe` object, which was renamed to `run`.
fixUpdate your code to use `axe.run()` instead of `axe.execute()`.
Upgrade
Version history
3.0.0latest on PyPI · released Apr 19, 2026
Audit
Dependencies
seleniumrequiredRequired for browser automation.
web browser driver (e.g., chromedriver, geckodriver)requiredWebDriver executable for the target browser must be installed and available in system PATH or specified explicitly.