Install & Compatibility
Where this runs
tested against v6.0.0 · 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 0.728s · 57.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.654s · 58MB
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
webdriver
✓ from appium import webdriver
✗ from appium.webdriver import webdriver
The `webdriver` object is now directly available under the `appium` top-level package.
AppiumOptions
✓ from appium.options.common.base import AppiumOptions
✗ from appium.options.common import AppiumOptions
Specific option classes are found in `appium.options.common.base` or platform-specific submodules.
AppiumBy
✓ from appium.webdriver.common.appiumby import AppiumBy
✗ from appium.webdriver.common.mobileby import MobileBy
`MobileBy` was deprecated; `AppiumBy` is the current standard for Appium-specific locator strategies.
This quickstart demonstrates how to connect to an Appium server, define basic Android capabilities using `AppiumOptions`, initialize the `webdriver.Remote` instance, and perform a simple element interaction (finding and clicking an element by accessibility ID). Ensure the Appium server (Node.js) is running before executing this script. Environment variables are used for flexibility, with sensible defaults.
import os
from appium import webdriver
from appium.options.common.base import AppiumOptions
from appium.webdriver.common.appiumby import AppiumBy
APPIUM_SERVER_URL = os.environ.get('APPIUM_SERVER_URL', 'http://localhost:4723')
options = AppiumOptions()
options.platformName = os.environ.get('APPIUM_PLATFORM_NAME', 'Android')
options.automationName = os.environ.get('APPIUM_AUTOMATION_NAME', 'UiAutomator2')
options.deviceName = os.environ.get('APPIUM_DEVICE_NAME', 'Android Emulator')
options.appPackage = os.environ.get('APPIUM_APP_PACKAGE', 'com.android.settings')
options.appActivity = os.environ.get('APPIUM_APP_ACTIVITY', '.Settings')
print(f"Connecting to Appium server at: {APPIUM_SERVER_URL}")
print(f"Using capabilities: {options.to_capabilities()}")
driver = None
try:
driver = webdriver.Remote(APPIUM_SERVER_URL, options=options)
print("Driver initialized successfully.")
# Example action: Find and click 'Display' setting
# Requires an Android emulator/device with the default Settings app
el = driver.find_element(AppiumBy.ACCESSIBILITY_ID, "Display")
print(f"Found element: {el.text}")
el.click()
print("Clicked 'Display' setting.")
except Exception as e:
print(f"An error occurred: {e}")
finally:
if driver:
driver.quit()
print("Driver quit.")
Debug
Known issues
breakingThe `desired_capabilities` dictionary for `webdriver.Remote` has been replaced by `options` objects (e.g., `AppiumOptions`). Passing a dictionary directly will likely lead to errors or unexpected behavior.fixInstead of `webdriver.Remote(command_executor, desired_capabilities=caps)`, use `options = AppiumOptions(); options.platformName = 'Android'; ...; webdriver.Remote(command_executor, options=options)`.
affects: 5.0.0+ (aligning with Appium 2.x and Selenium 4)
breakingDirect `find_element_by_*` methods (e.g., `find_element_by_id`, `find_element_by_xpath`) are deprecated and largely removed, aligning with Selenium 4 changes.fixUse the unified `driver.find_element(AppiumBy.STRATEGY, "locator_value")` pattern. For example, `driver.find_element(AppiumBy.ID, "someId")`.
affects: 5.0.0+ (aligning with Appium 2.x and Selenium 4)
gotchaFor Appium server 2.x, the default URL changed from `http://localhost:4723/wd/hub` to simply `http://localhost:4723`. Using the old `/wd/hub` path will result in connection failures.fixEnsure your `APPIUM_SERVER_URL` or `command_executor` points to `http://localhost:4723`.
affects: 5.0.0+ (when connecting to Appium server 2.x+)
gotchaThe Appium server (the Node.js application) must be installed and running independently before you can execute any Python client scripts. The Python client acts as a bridge to the server.fixInstall Appium globally via `npm install -g appium` and start it with `appium` in your terminal before running tests.
affects: All versions
gotchaWhile `AppiumOptions` is a base class, for real-world scenarios, it's often more appropriate and robust to use platform-specific option classes like `UiAutomator2Options` (for Android) or `XCUITestOptions` (for iOS). These provide specific capabilities and validations.fixImport and use `from appium.options.android import UiAutomator2Options` or `from appium.options.ios import XCUITestOptions` and instantiate them instead of `AppiumOptions`.
affects: 5.0.0+
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'appium'
The Appium Python client library is not installed in the Python environment.
fixInstall the Appium Python client using pip: `pip install Appium-Python-Client`.
ImportError: cannot import name 'webdriver' from 'appium'
The import statement is incorrect or the Appium Python client is not properly installed.
fixEnsure the Appium Python client is installed and use the correct import: `from appium import webdriver`.
ImportError: cannot import name 'TouchAction' from 'appium.webdriver.common.touch_action'
The `TouchAction` class has been removed in Appium Python client version 4.0.0.
fixUse W3C WebDriver actions or `mobile:` extensions instead of `TouchAction`.
urllib3.exceptions.MaxRetryError: HTTPConnectionPool(host='127.0.0.1', port=4723): Max retries exceeded with url: /wd/hub/session
This error indicates that the Python client failed to connect to the Appium server. This usually happens because the Appium server is not running, is running on a different host/port, or a firewall is blocking the connection.
fixVerify that your Appium server is running and listening on the expected address and port (default is `http://127.0.0.1:4723`). Check for other processes using the same port. If starting Appium programmatically, ensure `appium_service.start()` is successful and the server has enough time to initialize.
selenium.common.exceptions.WebDriverException: Message: An unknown server-side error occurred while processing the command.
This is a generic error from the Appium server, indicating an issue during command processing. The root cause can vary widely but often relates to incorrect desired capabilities, a problem with the Appium driver (e.g., UiAutomator2, XCUITest), or an unstable test environment (e.g., device disconnection, application crashes).
fixExamine the detailed Appium server logs for a more specific 'Original error' message, which often provides the actual reason (e.g., 'Could not find a driver for automationName', 'The instrumentation process cannot be initialized'). Review your desired capabilities for accuracy and ensure the Appium server, device/emulator, and application under test are in a stable state.
Upgrade
Version history
6.0.0latest on PyPI · released Aug 8, 2026
Audit
Dependencies
seleniumrequiredAppium Python Client builds on top of Selenium WebDriver for web automation functionalities.