Installing Appium Server and CLI

Appium is a Node.js application. Installing it takes five minutes if you have Node already. If you don't, that's the first thing to fix. This lesson walks through a clean install from zero, explains what appium-doctor tells you, and makes sure you can start the server before you touch Android or iOS setup.

Prerequisites

You need Node.js 16 or later. The simplest way to manage Node versions on macOS or Linux is nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc   # or ~/.bashrc
nvm install --lts
nvm use --lts
node --version    # should print v20.x.x or similar

On Windows, use the official Node installer from nodejs.org or nvm-windows.

Installing Appium 2

Install the Appium server globally:

npm install -g appium

Verify:

appium --version

If you get "command not found," the npm global bin directory is not in your PATH. Fix it:

# Find the npm global bin path
npm bin -g
 
# Add it to PATH in your shell profile
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc
source ~/.zshrc

Installing drivers

Appium 2 ships with no drivers bundled. You install only what you need:

# For Android testing
appium driver install uiautomator2
 
# For iOS testing
appium driver install xcuitest

List installed drivers at any time:

appium driver list --installed

List available drivers (including community plugins):

appium driver list

Starting the server

appium

The output looks like this:

[Appium] Welcome to Appium v2.5.x
[Appium] Appium REST http interface listener started on http://0.0.0.0:4723
[Appium] Available drivers:
[Appium]   - uiautomator2@3.x.x (automationName 'UiAutomator2')
[Appium]   - xcuitest@7.x.x (automationName 'XCUITest')

By default, the server binds to 0.0.0.0:4723. Your test code connects to http://127.0.0.1:4723.

Useful flags:

appium --port 4724          # different port
appium --log appium.log     # write logs to a file
appium --log-level debug    # verbose output for debugging

appium-doctor

appium-doctor is a diagnostic CLI that checks your environment for missing dependencies. Install it:

npm install -g @appium/doctor

Run the check:

appium-doctor --android   # check Android prerequisites
appium-doctor --ios       # check iOS prerequisites (macOS only)

The output is a checklist of green checkmarks and red crosses. Fix every red cross before trying to run tests — each one represents a dependency that Appium needs and cannot find.

Common failures and fixes:

Environment variables to set permanently

Add these to your ~/.zshrc (macOS) or ~/.bashrc (Linux):

# Java
export JAVA_HOME=$(/usr/libexec/java_home)
 
# Android SDK (adjust path for your OS)
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH

After saving:

source ~/.zshrc
appium-doctor --android   # should show all green

Keeping Appium updated

npm update -g appium
appium driver update uiautomator2
appium driver update xcuitest

Check the Appium changelog before updating in a team environment — driver updates can change capability names or interaction APIs.

Running Appium as a background service

During development, running appium in a terminal tab is fine. In CI, start it in the background before tests and kill it after:

appium &
APPIUM_PID=$!
# ... run tests ...
kill $APPIUM_PID

Or use a process manager like pm2:

npm install -g pm2
pm2 start appium
pm2 stop appium