appium-uiautomator2-driver: black-box Android testing on top of UI Automator

What the driver actually does on the device

The architecture is a chain of three pieces and the readme describes it plainly. The driver operates in scope of the W3C WebDriver protocol with several custom extensions to cover operating-system specific scenarios, and it proxies most of the commands to the UiAutomator2 server, which uses Google's UI Automator framework under the hood. Some commands are proxied directly to appium-adb and other helpers built on top of the Android platform tools. That split is the interesting part. A WebDriver request arrives, the driver translates it, and most of the work is done on the device by a separate server component that the driver installs and launches. The parts that need raw device access, installing an app, toggling settings, reading logs, go through the adb helpers instead. An end-to-end architecture diagram is referenced in the docs, and the practical consequence of this arrangement is that a session involves installing and starting a server on the device, which is why several of the capabilities in the readme are about server installation and timeouts.

The Appium 3 requirement is the first thing to check

There is an important notice above the documentation section and it is the first thing any adopter should read. Since major version 5.0.0, this driver is only compatible with Appium 3, and the instruction is to use the appium driver install uiautomator2 command to add it to your distribution. The word distribution is doing work there, because the Appium 2 model was a single global installation with drivers installed into it, whereas Appium 3 treats drivers as extensions managed per installation. If your team still has a shared Appium 2 server, this driver will not work with it and the fix is an upgrade of Appium itself rather than anything in this repository. The documentation also says that the original readme remains below but will be removed in the near future, and asks that links be updated to the documentation website, so anyone pointing at the repository readme should redirect to the site. The releases follow a versioning scheme where 8.x is the current stable line and a 9.0.0 beta appeared on 2026-10-01, with 8.7.0 on 2026-09-14 and 8.6.4 on 2026-09-12 before it.

The prerequisites are a Java version, an SDK path and an enabled device

The requirements section is where a first setup usually goes wrong, and the details are specific. Windows, Linux and macOS are all supported as hosts. The Android SDK Platform tools must be installed, with the note that Android Studio IDE also provides a convenient interface for installing and managing them, and either the ANDROID_HOME or the ANDROID_SDK_ROOT environment variable must be set. A Java JDK must be installed and JAVA_HOME must be set, and here the version depends on the SDK: Android SDK below API 30 requires Java 8, while Android SDK 30 and above requires Java 9 or newer. An emulator platform image must be installed if you plan to run tests on one. Real devices must have USB debugging enabled and should show as online in the adb devices -l output. On the Android version floor, since driver version 6.0.0 the minimum supported version is API 8, Oreo, at API level 26, and before 6.0.0 it was API 5, level 21, with version 6.0 recommended instead because 5 has some known compatibility issues. The doctor command exists precisely because of this list. Since driver version 2.39.0 you can automate the validation of most of the requirements, as well as various optional ones needed by driver extensions, by running the appium driver doctor uiautomator2 command.

Capabilities that decide how a session behaves

The capability tables are where the operational behaviour of a session is actually configured, and a few entries matter more than the rest. The automationName capability must always be set to uiautomator2, and those values are compared case-insensitively. The udid capability selects the device and can be retrieved from the adb devices -l output, and if it is unset the driver tries to use the first connected device, which is why the documentation says to always set it when running parallel tests. The deviceName capability is only nominally the name of the device, and the note points you at udid for real devices and avd for emulators instead. The platformVersion capability is used for device autodetection when udid is not provided. On reset behaviour, noReset prevents the device being reset before session startup, so the application under test is neither terminated nor its data cleaned, and fullReset set to true always enforces full uninstall before a new session. Both default to false. The printPageSourceOnFindFailure capability dumps the actual XML page source into the log when an error happens, which is a cheap way to make a failed locator debuggable.

Server ports, install timeouts and parallel runs

The driver and server capability section covers the mechanics of getting a server running on a device, and this is where a CI environment differs most from a laptop. The systemPort capability is the port on the host used for the UiAutomator2 server, and by default the first free port in the 8200 to 8299 range is selected, with the explicit recommendation to set this value if you are running parallel tests on the same machine. The uiautomator2ServerLaunchTimeout is the maximum number of milliseconds to wait for the server to be listening on the device, 30000 ms by default, and uiautomator2ServerInstallTimeout covers the install step, which has a longer default. The skipServerInstallation capability skips installing the server component on the device along with all the related checks, and the documentation is honest about the trade: it can speed up session startup if you know the correct server version is already installed, but if the server is missing or the wrong version is present you may get an unexpected error later, and it defaults to false. The set of free ports in the 8200 range is the reason a parallel run needs explicit systemPort values rather than relying on the default, since two sessions racing for the same first free port is exactly the kind of thing that makes a parallel suite flaky.

What the package ships and how the tests are run

The package metadata describes a modern ES module package with a build step. The name is appium-uiautomator2-driver, the type is module, the main entry is the built index.js and the types entry is the generated declaration file, with an exports map that points at the types and the ES module build. The build script is tsc -b, the clean script reuses the build with a clean flag, and there is a dev script that runs the build in watch mode. The published files list includes lib, the built lib, scripts, the changelog and the licence, so the runtime artefacts and the helper scripts go out and the sources do not. The end to end test scripts are worth noting, because they use the Node test runner directly with a concurrency of one and a ten minute timeout per test, and they are split by area into commands, with a separate target for the find commands, for general commands, for keyboard commands and for the driver itself. The test directory is inside the repository rather than a separate project, and the repository also carries a mkdocs configuration for the documentation site, typedoc configuration for the API reference, an oxlint and oxfmt configuration for linting and formatting, and a release configuration.

Editorial conclusion

appium-uiautomator2-driver is the right choice for a team running Appium tests against Android apps, because it is the component that speaks the W3C WebDriver protocol to Google's UI Automator framework, and because it works the same way on emulators and on real hardware. It is the wrong choice for iOS or for cross platform desktop testing, since it is Android only, and it is the wrong choice for a test suite that needs to inspect the app internals rather than the black-box UI, which is exactly what this driver gives you. It is also the wrong choice if your Appium distribution is still on version 2, since the driver has required Appium 3 since major version 5.0.0. Before adopting it, run the doctor command, because it automates the validation of the prerequisites and of the optional pieces the extensions need, and set appium:udid explicitly if you run parallel tests, since the driver otherwise picks the first connected device. The project is Apache-2.0 licensed, the last push was on 2026-10-19, and the current stable release is v8.7.0 from 2026-09-14 with a 9.0.0 beta published on 2026-10-01.

Frequently asked questions

Official sources

1. appium/appium-uiautomator2-driver on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases