---
id: percy-selenium
version: "2.2.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# percy-selenium — Python client for visual testing with Percy

License: permissive · Maintenance: active · Downloads: 132.7K/mo

## What it is and what it does

percy-selenium is a Python client that connects Selenium browser automation to Percy's visual testing service. It provides functions like percy_snapshot() and percy_screenshot() that capture the current state of a web page and send it to Percy for comparison against baseline images, flagging visual regressions when they occur.

The package wraps selenium and requests to communicate with Percy's infrastructure. It requires the @percy/cli Node package and a PERCY_TOKEN to function; without them, snapshot calls are no-ops. It supports both standard visual snapshots and Percy on Automate screenshots, with options for full-page capture, animated image freezing, region-based comparison, and selective element ignoring or consideration during diff analysis.

Use it for:

- Detect unintended visual changes in UI components across browser versions or screen sizes
- Validate responsive design by capturing snapshots at different viewport dimensions
- Monitor visual consistency of marketing or public-facing pages after code deployments
- Automate screenshot comparison in CI/CD pipelines to catch layout or styling regressions
- Test visual appearance of dynamically generated content or third-party integrations

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Integrates Percy visual testing into Python Selenium tests, capturing and comparing screenshots against baseline images to detect visual regressions.

Yes, if you are already using Selenium for browser automation and want to add visual regression detection to your test suite. The low install friction, active maintenance, MIT license, and zero known vulnerabilities make it a straightforward addition. You will need to set up @percy/cli and obtain a Percy project token; without those, the package is present but inactive.

## Install

pip install percy-selenium
uv add percy-selenium
poetry add percy-selenium

## Installing percy-selenium

Before you install: Low install friction with a pure-Python wheel. Actively maintained with a recent release; last commit on 2026-08-10 and production-stable status indicate ongoing support.

License in practice: MIT license permits commercial and private use with minimal restrictions; suitable for most projects without licensing concerns.

Quickstart:

pip install percy-selenium

from percy import percy_snapshot
from selenium import webdriver

browser = webdriver.Firefox()
browser.get('http://example.com')
percy_snapshot(browser, 'Python example')

Requires @percy/cli to be installed via npm and PERCY_TOKEN environment variable set to upload snapshots; without these, snapshots are silently disabled.

Verify before relying:

- Whether percy-selenium works with all Selenium driver types or only specific ones
- Performance impact of snapshot operations on test execution time
- Compatibility with headless browser modes and remote WebDriver instances

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 132.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

visual regression testing selenium, percy python selenium integration, screenshot comparison testing, visual testing automation, percy snapshots python, visual-testing, selenium-integration, regression-detection

[View on SkillFed](https://skillfed.io/packages/percy-selenium) · [View on PyPI](https://pypi.org/project/percy-selenium/)