Install & Compatibility
Where this runs
tested against v6.10.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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Eyes
✓ from applitools.selenium import Eyes
The primary class for interacting with Applitools Eyes. The specific import path depends on the integration (e.g., applitools.selenium, applitools.playwright).
Configuration
✓ from applitools.selenium import Configuration
Used to configure the Eyes object, including API key, batch info, and server URL. Path depends on integration.
BatchInfo
✓ from applitools.common.batch_info import BatchInfo
✗ from applitools.selenium import BatchInfo
BatchInfo is a common component; import from `applitools.common.batch_info` is generally preferred, although it might be re-exported by specific SDKs.
Target
✓ from applitools.selenium import Target
Used to define what part of the application is being visually checked (e.g., window, element, region). Path depends on integration.
ClassicRunner
✓ from applitools.selenium import ClassicRunner
Manages multiple Eyes sessions without the Ultrafast Grid. Path depends on integration.
VisualGridRunner
✓ from applitools.selenium import VisualGridRunner
Manages Eyes sessions when using the Ultrafast Grid for parallel cross-browser/device testing. Path depends on integration.
This quickstart demonstrates a basic visual test using `eyes-selenium` to integrate with Selenium WebDriver. It initializes Applitools Eyes, navigates to a webpage, performs a visual checkpoint, and then closes the test. The `APPLITOOLS_API_KEY` must be set as an environment variable for authentication. It also correctly handles the `runner` and `eyes` object lifecycle.
import os
from selenium import webdriver
from applitools.selenium import Eyes, Target, Configuration, ClassicRunner
from applitools.common.batch_info import 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.")
runner = ClassicRunner()
eyes = Eyes(runner)
config = Configuration()
config.set_api_key(APPLITOOLS_API_KEY)
config.set_app_name('Hello World App')
config.set_test_name('My First Visual Test')
config.set_batch(BatchInfo('Python Quickstart Batch'))
eyes.set_configuration(config)
driver = None
try:
# Initialize a Chrome WebDriver (ensure you have chromedriver installed and in PATH)
driver = webdriver.Chrome()
# Navigate to a URL
driver.get('https://applitools.com/helloworld')
# Start the visual test
eyes.open(driver)
# Visual checkpoint #1.
eyes.check('Hello World Page', Target.window())
# Click a button to change content (example for a second checkpoint)
# driver.find_element_by_css_selector('button').click()
# eyes.check('Hello World Page after click', Target.window())
# End the test
eyes.close(raise_exception=True)
finally:
# Close the browser
if driver:
driver.quit()
# Close the Eyes runner if it's still open (e.g., due to an aborted test)
runner.get_all_test_results(raise_exception=True)
print("Visual test completed. Check Applitools Test Manager for results.")
Debug
Known issues
breakingMigration from Applitools Eyes Python SDK v3 to v4 (specifically for `eyes-selenium`) introduced significant API changes, moving from a 'Classic API' (e.g., `check_window()`) to a 'Fluent API' (`check()`). Users migrating older tests will need to update their checkpoint calls.fixRewrite visual checkpoints using the `eyes.check(name, Target.window())` or `eyes.check(name, Target.region(...))` fluent API. Refer to the Applitools migration guides for specific SDKs.
affects: Introduced in v4.x, impacts users upgrading from v3.x or older.
gotchaFailing to set the `APPLITOOLS_API_KEY` environment variable will prevent tests from running and uploading results to the Applitools Test Manager. The SDK requires this key for authentication.fixEnsure `APPLITOOLS_API_KEY` is set in your environment before running tests. For example: `export APPLITOOLS_API_KEY='your_api_key'`.
affects: All versions
gotchaNot calling `eyes.close()` at the end of a test (e.g., due to an unhandled exception) can result in tests being marked as 'Aborted' in the Applitools Test Manager and test results not being finalized or reported correctly.fixAlways wrap your test execution in a `try...finally` block to ensure `eyes.close()` is called. Additionally, `runner.get_all_test_results(raise_exception=True)` should be called in the final block to retrieve and report all test results, especially when using a `Runner`.
affects: All versions
gotcha`eyes-common` is a shared dependency. Users should install and use the specific Applitools Eyes SDK for their testing framework (e.g., `eyes-selenium` for Selenium, `eyes-playwright` for Playwright, `eyes-appium` for Appium). Directly importing from `eyes-common` for core functionality is generally not the intended pattern, though some common utilities might be exposed.fixInstall the appropriate Applitools SDK for your test framework (e.g., `pip install eyes-selenium`). All core `Eyes` objects and configurations should be imported from the specific SDK package (e.g., `from applitools.selenium import Eyes`).
affects: All versions
gotchaWhen using `VisualGridRunner` for the Ultrafast Grid, concurrency might be limited to 1 for free Applitools accounts, which can affect the parallel execution benefits.fixBe aware of your Applitools account's concurrency limits. For increased concurrency with the Ultrafast Grid, a paid Applitools account is typically required.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'applitools.common'
This error occurs when you try to directly import from `applitools.common`, which is a foundational package whose components are typically re-exported and accessed through specific Applitools SDKs (e.g., `eyes-selenium`, `eyes-playwright`).
fixInstead of directly importing from `applitools.common`, import the necessary classes or functions from the specific Applitools SDK you are using. For example, if you need core utilities, check the documentation for the specific SDK (e.g., `applitools.selenium`) to find where those utilities are re-exported or how to access them correctly.
ModuleNotFoundError: No module named 'applitools.eyes'
Developers often attempt to import the main `Eyes` class from a non-existent `applitools.eyes` module.
fixThe `Eyes` class should be imported from the specific Applitools SDK relevant to your test framework, such as `applitools.selenium` for Selenium-based tests or `applitools.playwright` for Playwright-based tests.
ImportError: cannot import name 'Region'
This `ImportError` typically arises when attempting to import the `Region` class (or similar core geometry/utility classes) from an incorrect or deprecated module path within the `applitools` package structure.
fixThe `Region` class is part of the common utilities. It should be imported from `applitools.common.geometry`. For example: `from applitools.common.geometry import Region`.
AttributeError: 'Eyes' object has no attribute 'set_api_key'
This error indicates that you are attempting to set the Applitools API key directly on the `Eyes` object using a method like `set_api_key`, which is not the correct or current way to configure the API key.
fixThe API key should be set either through an environment variable (`APPLITOOLS_API_KEY`) or by using the `Configuration` object. Instantiate a `Configuration` object, set the API key on it using `config.set_api_key('YOUR_API_KEY')`, and then apply this configuration to your `Eyes` instance using `eyes.set_configuration(config)`. Upgrade
Version history
6.10.3latest on PyPI · released Aug 23, 2026
Audit
Dependencies
seleniumoptionalRequired if using the 'eyes-selenium' integration package for web browser automation.
playwrightoptionalRequired if using the 'eyes-playwright' integration package for web browser automation.
Appium-Python-ClientoptionalRequired if using the 'eyes-appium' integration package for mobile app automation.