Install & Compatibility
Where this runs
tested against v6.5.3 · 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.95 runs
installs and imports cleanly · install 0.0s · import 1.212s · 162.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.2s · import 1.140s · 162MB
162MB installed
● package 162MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Eyes
✓ from applitools.selenium import Eyes
Main class for Applitools Eyes functionality.
Target
✓ from applitools.selenium import Target
Used to define what to check in a visual test (e.g., `Target.window()`).
VisualGridRunner
✓ from applitools.selenium import VisualGridRunner
Manages multiple Eyes test sessions, especially with the Ultrafast Grid. Recommended for parallel execution.
ClassicRunner
✓ from applitools.selenium import ClassicRunner
Manages multiple Eyes test sessions without the Ultrafast Grid.
BatchInfo
✓ from applitools.common import BatchInfo
Groups related test runs together in the Applitools Test Manager.
This quickstart demonstrates a basic visual test using `eyes-selenium` with `pytest` and Selenium WebDriver. It initializes a `VisualGridRunner` for efficient test management, sets the Applitools API key, and performs visual checkpoints on a web page. The `APPLITOOLS_API_KEY` must be set as an environment variable. The example includes navigating to a demo site, logging in, and performing visual checks on both the login and dashboard pages.
import os
import pytest
from selenium import webdriver
from applitools.selenium import Eyes, Target, VisualGridRunner, BatchInfo
# Set your Applitools API key as an environment variable APPLITOOLS_API_KEY
# For example: export APPLITOOLS_API_KEY='YOUR_API_KEY'
APPLITOOLS_API_KEY = os.environ.get('APPLITOOLS_API_KEY', '')
if not APPLITOOLS_API_KEY:
raise ValueError("APPLITOOLS_API_KEY environment variable not set.")
@pytest.fixture(scope='session')
def applitools_runner():
runner = VisualGridRunner()
yield runner
# Wait for all visual tests to complete and get results
print("\nVisual test results:\n", runner.get_all_test_results(raise_exception=True))
@pytest.fixture(scope='function')
def driver():
# Ensure your ChromeDriver version matches your Chrome browser version
options = webdriver.ChromeOptions()
# options.add_argument('--headless') # Uncomment for headless execution
driver = webdriver.Chrome(options=options)
driver.implicitly_wait(10)
yield driver
driver.quit()
def test_applitools_example(driver, applitools_runner):
eyes = Eyes(runner=applitools_runner)
eyes.api_key = APPLITOOLS_API_KEY
eyes.batch = BatchInfo('My Python App') # Group tests in Test Manager
try:
# Open Eyes with the WebDriver, application name, test name, and viewport size
eyes.open(driver=driver, app_name='My App', test_name='Login Page Test', viewport_size={'width': 800, 'height': 600})
driver.get('https://demo.applitools.com/')
eyes.check('Login Window', Target.window().fully())
driver.find_element('id', 'username').send_keys('user')
driver.find_element('id', 'password').send_keys('password')
driver.find_element('id', 'log-in').click()
eyes.check('App Dashboard', Target.window().fully())
finally:
# Close Eyes to finish the test session
eyes.close()
Debug
Known issues
breakingThe GitHub repository `applitools/eyes.selenium.python` has been deprecated. While the `eyes-selenium` PyPI package remains the correct installation, users should refer to `applitools/eyes.sdk.python` for the latest source and potentially more up-to-date examples if direct repository interaction is needed.fixEnsure you are using the `eyes-selenium` PyPI package for installation and consult the Applitools documentation (applitools.com/docs) for the latest usage patterns.
affects: All versions
gotchaThe version of `ChromeDriver` (or any other browser driver) used with Selenium WebDriver must precisely match the installed version of the Chrome browser to avoid `WebDriverException` errors during initialization.fixRegularly update `ChromeDriver` to match your Chrome browser version. Consider using `webdriver-manager` for automated driver management if not already in use.
affects: All versions using local browser drivers
gotchaApplitools tests require the `APPLITOOLS_API_KEY` environment variable to be set for authentication with the Applitools Eyes server.fixSet `APPLITOOLS_API_KEY` in your environment (e.g., `export APPLITOOLS_API_KEY='YOUR_API_KEY'`). Optionally, `eyes.api_key` can be set programmatically, but environment variables are recommended.
affects: All versions
gotchaEvery Applitools Eyes test session must begin with `eyes.open()` and conclude with `eyes.close()` to ensure proper test execution and result reporting. Failing to call `close()` can lead to abandoned tests.fixAlways wrap your visual test logic within a `try...finally` block to ensure `eyes.close()` is called, even if exceptions occur. For runners, ensure `runner.get_all_test_results()` is called at the end of all tests.
affects: All versions
deprecatedThe synchronous `eyes.close()` method returns a single test result. For parallel execution or when using runners (like `VisualGridRunner`), it's recommended to use asynchronous closing mechanisms (`eyes.close_async()`) followed by `runner.get_all_test_results()` to retrieve all results efficiently.fixWhen using `VisualGridRunner` or `ClassicRunner`, call `eyes.close()` for each test instance (this will internally handle async if needed), and then `runner.get_all_test_results()` once after all tests have completed.
affects: Versions prior to `6.x` and early `6.x` when not using runners; usage with runners where single `close()` is called.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'applitools.common'
The Python environment cannot find the `applitools.common` module, which is an internal dependency of `eyes-selenium`. This often occurs due to incorrect installation, Python version conflicts, or issues within the virtual environment.
fixEnsure you are using the correct `pip` for your Python 3 environment (e.g., `python3 -m pip install -U eyes-selenium`). If the issue persists, try reinstalling `eyes-selenium` within a clean virtual environment.
ModuleNotFoundError: No module named 'applitools.eyes'
The `Eyes` class is being imported from an incorrect module path. In `eyes-selenium`, the `Eyes` class is located within the `applitools.selenium` module, not directly under `applitools.eyes`.
fixChange the import statement from `from applitools.eyes import Eyes` to `from applitools.selenium import Eyes`.
AttributeError: 'list' object has no attribute 'click'
This common Selenium error occurs when attempting to call the `click()` method on a list of web elements (returned by `find_elements()`) instead of a single `WebElement` (returned by `find_element()`). `eyes-selenium` users encounter this as it integrates with Selenium WebDriver.
fixUse `driver.find_element()` when you intend to interact with a single element. If you need to click multiple elements, iterate through the list returned by `find_elements()` and call `click()` on each individual element.
Upgrade
Version history
6.5.3latest on PyPI · released Aug 23, 2026
Audit
Dependencies
seleniumrequiredPrimary WebDriver integration for web automation.
Appium-Python-ClientoptionalIncluded for potential Appium WebDriver integration, though selenium is primary for this package.