Install & Compatibility
Where this runs
tested against v2.0.7 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.249s · 58MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.1s · import 1.146s · 58MB
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
percy_screenshot
✓ from percy import percy_screenshot
This quickstart demonstrates how to initialize an Appium driver and use `percy_screenshot` to capture visual snapshots. It assumes you have Appium and Percy CLI set up, and environment variables for Percy token and (optionally) BrowserStack credentials. Replace `<app_hash>` with your mobile application's identifier. The test should be executed via the `percy app:exec` command, which manages the Percy build lifecycle.
import os
from appium import webdriver
from percy import percy_screenshot
# Ensure PERCY_TOKEN is set in your environment
# export PERCY_TOKEN="your_percy_project_token"
# export BROWSERSTACK_USERNAME="your_bs_username"
# export BROWSERSTACK_ACCESS_KEY="your_bs_access_key"
PERCY_TOKEN = os.environ.get('PERCY_TOKEN', '')
BROWSERSTACK_USERNAME = os.environ.get('BROWSERSTACK_USERNAME', '')
BROWSERSTACK_ACCESS_KEY = os.environ.get('BROWSERSTACK_ACCESS_KEY', '')
if not PERCY_TOKEN:
raise ValueError("PERCY_TOKEN environment variable is not set.")
desired_caps = {
'app': 'bs://<app_hash>', # Replace with your app hash or local app path
'deviceName': 'Google Pixel 3',
'platformName': 'Android',
'platformVersion': '9.0',
'build': 'Percy Appium Python Build',
'name': 'Percy Appium Test',
'automationName': 'UiAutomator2'
}
# For BrowserStack App Automate
remote_url = f"https://{BROWSERSTACK_USERNAME}:{BROWSERSTACK_ACCESS_KEY}@hub-cloud.browserstack.com/wd/hub"
try:
driver = webdriver.Remote(remote_url, desired_caps)
# Your test steps here
# ... navigate, interact ...
percy_screenshot(driver, 'My First App Screenshot')
# Example: Take another screenshot after an action
# driver.find_element_by_accessibility_id('someElement').click()
# percy_screenshot(driver, 'After Element Click')
finally:
if driver:
driver.quit()
# To run this test, you'll typically use the Percy CLI:
# PERCY_TOKEN=your_token percy app:exec -- python your_test_file.py
Debug
Known issues
breakingThe `percy-appium-app` library (v2.0.8-beta.0 and later) introduced fixes for `remote_url` fetching when using `AppiumPythonClient` versions greater than 3. Older versions of `percy-appium-app` might not be compatible, leading to issues with Percy snapshots.fixUpgrade `percy-appium-app` to version `2.0.8-beta.0` or higher to ensure compatibility with `AppiumPythonClient > 3`. Always review changelogs for specific `Appium-Python-Client` version requirements.
affects: <2.0.8
gotchaWhen using `Appium-Python-Client >= v2.9.0`, there can be compatibility issues with recent `urllib3` versions. This can manifest as connection errors or unexpected behavior during driver initialization.fixIt is recommended to constrain your `urllib3` dependency to `>=1.26.15,<2` in your `requirements.txt` file to avoid conflicts.
affects: >=2.9.0 (Appium-Python-Client)
gotchaThe `@percy/cli` (Node.js package) is a mandatory dependency for `percy-appium-app` to function correctly. Without it, the `percy app:exec` command will not be available, and Percy builds cannot be created or snapshots uploaded.fixEnsure `@percy/cli` is installed globally (`npm install -g @percy/cli`) or as a dev dependency in your project (`npm install --save-dev @percy/cli`) and accessible in your system's PATH.
affects: All
Errors
Common errors & fixes
percy: command not found
The `@percy/cli` Node.js package is not installed or not in your system's PATH.
fixInstall the Percy CLI globally using npm: `npm install -g @percy/cli`. Verify installation by running `percy --version`.
ValueError: PERCY_TOKEN environment variable is not set.
The `PERCY_TOKEN` environment variable, which authenticates your Percy project, has not been configured.
fixSet the `PERCY_TOKEN` environment variable before running your tests. Example: `export PERCY_TOKEN="<your_project_token>"` (Linux/macOS) or `set PERCY_TOKEN="<your_project_token>"` (Windows Command Prompt).
urllib3.exceptions.MaxRetryError: HTTPSConnectionPool(...) Read timed out.
This often occurs due to incompatible versions of `Appium-Python-Client` and `urllib3`, particularly with `Appium-Python-Client >= 2.9.0` and newer `urllib3` versions.
fixAdd `urllib3>=1.26.15,<2` to your project's `requirements.txt` to ensure compatibility.
Upgrade
Version history
2.0.7latest on PyPI · released Mar 26, 2025
Audit
Dependencies
appium-python-clientrequiredRequired for Appium interactions and driver management. Compatibility issues noted with versions > 3 and older urllib3.
urllib3requiredSpecific version range required for compatibility with certain Appium-Python-Client versions (e.g., >=1.26.15,<2 for Appium-Python-Client >=2.9.0).
@percy/clirequiredPercy's command-line interface (Node.js based) is essential for orchestrating Percy builds and uploading screenshots. Must be installed globally or locally.
Resources
No resource links recorded.