Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท Architecture and Setup

Installing the Appium Server and Drivers

Install Node.js, the Appium server and the UiAutomator2 and XCUITest drivers, list and update them, start the server and verify it is running.

Installing Appium is a short sequence of commands, but each one matters. You need Node.js, the Appium server package, one or more drivers, and the platform tools those drivers rely on. This lesson covers the first three; the platform tools get their own lessons for Android and iOS.

All commands below are for a terminal on your own computer. They cannot run in this page, so they are shown read-only.

Step 1: Node.js

Appium is a Node.js program. Appium 2 requires a reasonably recent Node release, and newer Appium versions raise the minimum (Appium 3 requires Node 20.19 or newer, among supported lines). Install the current Long Term Support (LTS) version from nodejs.org or with a version manager such as nvm, fnm or Volta, then check:

Terminal
node --version
npm --version

If the server complains about the Node version, the fix is nearly always to upgrade Node, not to change Appium.

Step 2: install the server

Install the appium package globally with npm:

Terminal
npm install -g appium
appium --version

Global installation puts the appium command on your PATH. Many teams instead install Appium as a project dependency and run it with npx appium, so that every developer and the CI machine use the same version. Both styles are valid; pick one and write it in your README.

Step 3: install drivers

A fresh server has no drivers. You add the ones you need with the driver command:

Terminal
appium driver install uiautomator2
appium driver install xcuitest
appium driver list

appium driver list shows installed drivers and those available from the official list; appium driver list --installed shows only yours. Drivers live under the Appium home directory (~/.appium by default, set APPIUM_HOME to change it), not inside the npm package, so updating one is independent of updating the server:

Terminal
appium driver update uiautomator2
appium driver uninstall xcuitest

Useful official drivers:

Driver name Automates Host OS needed
uiautomator2 Android 5.0+ native apps and browsers Windows, macOS, Linux
espresso Android apps through Espresso Windows, macOS, Linux
xcuitest iOS and iPadOS macOS only
mac2 macOS apps macOS
windows Windows desktop apps Windows
flutter Flutter apps any

You can only drive iPhones from a Mac. If your team uses Windows laptops, iOS tests have to run on a Mac build agent or a cloud device farm (the Cloud Device Farms chapter later in the course).

Step 4: plug-ins (optional)

Plug-ins extend the server itself rather than a platform. Install one with appium plugin install <name>, then enable it when starting the server with --use-plugins. Examples include plug-ins for image comparison and for relaxing security features. Skip them until you need them.

Step 5: start the server

Terminal
appium

By default the server listens on 0.0.0.0:4723. Useful options:

Terminal
appium --address 127.0.0.1 --port 4723
appium --log-level debug
appium --use-drivers=uiautomator2,xcuitest

Bind to 127.0.0.1 unless you really want other machines to connect: the Appium server can install apps and run commands on the device, so it must never be exposed to an untrusted network.

Check that it is alive from another terminal:

Terminal
curl http://127.0.0.1:4723/status

A healthy server answers with JSON that says it is ready. If the port is already taken, change it with --port.

Version rules that save time

  • Pin versions in a package.json or a setup script so tests behave the same next month.
  • Server and client versions must be compatible; use the current major of both. Older Java and Python clients may expect the Appium 1 base path /wd/hub.
  • Capabilities need the appium: prefix in Appium 2 and later (Capabilities Explained).

Check an environment in a stand-in

A very useful skill is checking your versions against requirements. The stand-in compares version strings the way a setup script might. Replace the sample values with your own node --version output (a stand-in cannot run the commands for you).

JS Stand-in: version check for your setup

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Reading driver lists

appium driver list can output JSON with --json. Scripts often parse that to check what is installed before a CI run. The stand-in uses a made-up sample in that general shape (the real field set may differ, so check the output of your version) to show the idea of a pre-flight check.

JS Stand-in: pre-flight driver check

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common installation errors

  • EACCES permission errors on npm install -g. Configure npm's global prefix to a folder you own, or use a Node version manager, rather than using sudo.
  • Driver installs but the session fails. The driver is only the translator; the Android SDK or Xcode must also be set up.
  • Wrong server picked up. Two Appium installs on one machine: run which appium (macOS, Linux) or where appium (Windows) to see which one runs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A freshly installed Appium 2+ server has which drivers?

    Drivers are separate packages, installed with appium driver install <name>.
  2. 2. Which command installs the Android driver?

    Drivers use the driver subcommand and the driver's name, uiautomator2 for Android.
  3. 3. Why should you bind the server to 127.0.0.1 unless remote access is needed?

    Anyone who can reach the server can control the device, so restrict it to the local machine by default.
  4. 4. Which host OS is required to run the xcuitest driver?

    iOS automation depends on Xcode, which only runs on macOS.

Summary

  • Install Node.js LTS, then npm install -g appium (or as a project dependency).
  • Drivers are installed separately with appium driver install, and updated independently.
  • uiautomator2 works on any desktop OS; xcuitest needs a Mac.
  • Start the server with appium, verify with /status, bind to localhost by default.
  • Pin versions and keep server and clients compatible.

Next: Android SDK and Emulators