skip to content

Driver Installation

Appium 2 made drivers and plugins separately installed extensions: a bare server automates nothing until you add the UiAutomator2 driver for Android or the XCUITest driver for iOS.

part ofAppiumread it →
on this pageshow

explore

questions

4

Why does a freshly installed Appium server automate nothing until you install a driver?

level: middleimportance: must knowfreq 72%

answer

  1. the server hosts, it does not automate
  2. drivers are separate installable packages
  3. appium driver install, then a short name
  4. APPIUM_HOME holds extensions.yaml

basics

~20 s

Appium 2 turned drivers into separately installed extensions, so the server package ships only the protocol layer and the extension machinery. Until you install a driver - UiAutomator2 for Android, XCUITest for Apple platforms - no session can start.

solid answer

~40 s

Appium 2's headline architectural change was to split the product: the `appium` server is a protocol layer and an extension host, and every automation backend is an **extension you install yourself**. A bare server therefore answers HTTP but claims no platform, and `POST /session` fails during capability matching because no installed driver accepts the requested `platformName` and `appium:automationName` pair. You fix that with `appium driver install uiautomator2` for **Android** or `appium driver install xcuitest` for **Apple platforms**. Each is fetched as a package into `APPIUM_HOME` and recorded in the `extensions.yaml` manifest the server reads at startup, and `appium driver list --installed` shows what the current home holds. Appium 3 keeps this model unchanged.

code

bash · 5 lines
bash
# Android
appium driver install uiautomator2
# Apple platforms (iOS, iPadOS, tvOS)
appium driver install xcuitest
appium driver list --installed

go deeper

for a junior

Be ready to name the two commands - appium driver install uiautomator2 for Android and appium driver install xcuitest for Apple platforms - and to say that a server with neither installed cannot start a session at all.

for a middle

Explain the mechanics: the server hosts extensions, drivers are packages installed into APPIUM_HOME and recorded in extensions.yaml, and the server reads that manifest at startup to decide what it can load.

for a senior

Show that you diagnose rather than reinstall blindly - confirm the installed list under the APPIUM_HOME the server process actually uses, and separate a missing driver from one that is installed but simply not matched.

for a principal

Own the consequence: a machine's driver set is ambient state, so decide how a team pins driver versions, who is allowed to change them, and how a host's extension set is reproduced rather than remembered.

## The split Appium 2 made Appium once shipped as a single package carrying both the WebDriver protocol layer and every automation backend it supported. Appium 2 broke that apart, and Appium 3 kept the break. What the `appium` package installs today is a **server**: an HTTP service that speaks the W3C WebDriver protocol, hosts an extension system, and matches each incoming session request against whatever backends happen to be present. The backends themselves - the **drivers** - are separate packages you install into that server. **Plugins**, which wrap or add commands, use the same mechanism. The practical consequence surprises anyone whose memory of Appium predates the split: a freshly installed server is complete, correct, and automates nothing. It starts, it answers HTTP, and it refuses every session. ## Installing the driver you actually need The install surface is one subcommand per extension kind: - `appium driver install uiautomator2` adds the UiAutomator2 driver, which automates **Android**. - `appium driver install xcuitest` adds the XCUITest driver, which automates **Apple platforms** - iOS and iPadOS, tvOS, and watchOS on simulators. - `appium driver install espresso` adds the Espresso driver, a second **Android** backend. - `appium plugin install images` adds a plugin; plugins install exactly the way drivers do. - `appium setup mobile` is a convenience preset that installs the mainstream mobile drivers in one command instead of naming each one. A bare short name such as `uiautomator2` works because the CLI knows the official extensions by name. Anything else - a community driver, a fork, a working checkout - is installed by saying where it comes from with `--source`, whose values are `npm`, `github`, `git` and `local`. ## Where an installed extension lives Extensions do not land in your project. They land under **`APPIUM_HOME`**, an environment variable that defaults to `~/.appium`. That directory holds the extension packages and an **`extensions.yaml`** manifest recording each installed extension's name, package, version and source, and the server reads the manifest at startup to decide what it may load. Two rules follow: 1. `APPIUM_HOME` is the unit of isolation - point it elsewhere and you get a different, very possibly empty, driver set. 2. The same value must be in effect for the install *and* for the server start. Installing into the default home and then starting the server with a project-specific `APPIUM_HOME` is the most common 'but I did install it' failure. `appium driver list --installed` prints what the current home holds, and is the first command to run when a session reports that no driver matched. ## What the failure actually looks like Without a matching driver the failure is neither a transport error nor a missing route: `POST /session` exists on a bare server. The request gets as far as capability matching and is rejected because no installed driver claims the requested `platformName` and `appium:automationName` pair. That is useful information - the server is healthy and the extension set is wrong. Check, in order: - The installed list, under the same `APPIUM_HOME` the server process uses. - Whether the server was started with `--use-drivers`, which narrows the active set to the drivers you name. - Whether the installed driver's declared peer dependency matches the server's major line; every current driver declares one against the server package. ## What the extra step buys | | Android suite | Apple-platform suite | |---|---|---| | Driver to install | `appium driver install uiautomator2` | `appium driver install xcuitest` | | Host it needs | any host with the Android SDK's `adb` reachable | macOS with Xcode to build the on-device agent or run simulators | | Second official option | `appium driver install espresso` | none | - You install only the platforms you automate, so a server's footprint matches its job. - Drivers release on their own cadence, independently of the server's. - A third-party or forked driver is a first-class citizen rather than a patch applied to the server. - The set of drivers on a machine becomes something you can state, inspect and reproduce, instead of something implied by the server version. The cost is exactly the step this question is about: nothing automates anything until you say what to install, and a host that has never been told stays a perfectly healthy server that answers every request by refusing it.

  • Where does appium driver install put the driver, and how does the server find it later?
    Into `APPIUM_HOME`, which defaults to `~/.appium`. The package lands under that directory and an entry is added to the `extensions.yaml` manifest recording its name, package, version and source. The server reads that manifest when it starts, so a server run with a different `APPIUM_HOME` sees a different - often empty - set of drivers.
  • The driver is installed and the session still fails to match - what do you check?
    First, that the installed list you looked at is under the same `APPIUM_HOME` the server process uses. Then whether the server was started with `--use-drivers` narrowing the active set. Then whether the session actually asks for that driver's platform. A driver that is present, active and simply unmatched is a capability problem, not an installation one.

A bare Appium server is a print server with no printer drivers: it accepts jobs over the network all day and has nothing it knows how to drive until you install the driver for the hardware you actually own.

  • Thinks the Appium server ships with the Android and Apple drivers built in
  • Believes installing the server package alone is enough to start any session
  • Says the server downloads a missing driver on demand at session start
  • Calls the driver a client library rather than a server-side extension
  • Assumes one driver covers both Android and Apple platforms
  • Expects extensions to be shared across every APPIUM_HOME on the host

Separately installed drivers and plugins are Appium 2's break from Appium 1, and Appium 3 keeps the model.

open as a page

In Appium, why must you pass --use-plugins at server start when --use-drivers is optional?

level: middleimportance: should knowfreq 44%

basics

~20 s

Installing an Appium extension and activating it are different steps. Every installed driver is active by default, so --use-drivers only narrows the set; no plugin runs unless --use-plugins names it, because a plugin sits in every session's command path.

open as a page

Your Appium library loan-renewal suite needs an unreleased driver fix - how do you install that build?

level: seniorimportance: should knowfreq 37%

basics

~20 s

Install the build from where it lives: appium driver install with --source=github or --source=git plus --package, or --source=local for a checkout. It lands in APPIUM_HOME like any driver, but a branch pins nothing - treat it as temporary.

open as a page

How would you scope APPIUM_HOME when several Appium suites share one machine?

level: principalimportance: should knowfreq 33%

basics

~20 s

APPIUM_HOME scopes one thing: the installed extensions and their extensions.yaml manifest. Share one home while every suite can agree on driver versions, and give each suite its own when they cannot - setting the variable for both install and server start.

open as a page