Install Appium 3 Drivers and Plugins with CLI

TL;DR

Install Appium globally, add platform drivers with appium driver install, and add optional server plugins with appium plugin install. Verify every extension with the list and doctor commands, then start Appium with explicit plugin activation.

Key Takeaways

• Appium core and its drivers are separate packages, so install each required driver explicitly.
• Use appium driver list --installed and appium plugin list --installed to audit local extensions.
• Install only drivers that match the platforms your test host can actually automate.
• Activate plugins with --use-plugins when starting the server, because installation alone does not enable them.
• Pin and record extension versions so local machines and CI agents use the same automation stack.
• Run doctor checks and a real session after installation instead of treating a successful npm command as proof.

The appium 3 install drivers plugins cli workflow starts with one important fact: Appium core is only the server framework. You install platform drivers and optional server plugins separately through Appium's Extension CLI, then verify and activate exactly what your project needs.

This tutorial takes you from a clean Node.js environment to an Appium 3 server with Android and iOS drivers, useful plugins, repeatable version checks, and a real session test. For the broader architecture, platform setup, and framework choices, read the Appium 3 mobile automation complete guide.

You will use commands that are safe to copy into a terminal in 2026. You will also learn where installation ends and host-specific setup begins, because an installed driver cannot replace Android SDK, Xcode, device, or signing requirements.

What You Will Build

By the end, you will have a small but auditable Appium extension stack:

• Appium 3 installed and reachable from your shell.
• UiAutomator2 installed for Android automation.
• XCUITest installed when the host is macOS and iOS testing is required.
• The images and relaxed-caps plugins installed as practical examples.
• A server start command that activates only selected plugins.
• A shell-based verification routine suitable for a workstation or CI image.
• A minimal Android session request that proves the driver can create a session.

The tutorial keeps global installation for clarity. If your team prefers project-local npm dependencies, the same Extension CLI concepts apply when commands run through the local Appium binary.

Prerequisites

Use a supported Node.js LTS release and npm. Appium 3 requires Node.js 20.19.0 or newer and npm 10 or newer, so confirm both before installing anything:

node --version
npm --version

You also need a terminal with permission to install npm global packages. Do not solve permission errors with a permanent habit of running npm through sudo. Use a Node version manager or configure npm's global prefix for your user.

For Android, install Android Studio or the Android command-line tools, set ANDROID_HOME, accept SDK licenses, and make adb available on PATH. Have an emulator running or a physical device authorized before the final session test.

For iOS, use a Mac with a supported Xcode installation, Xcode command-line tools, and the required simulator runtimes. XCUITest may install as an Appium extension on another operating system, but it cannot automate iOS there.

You can check the host tools now:

which node
which npm
which adb || true
xcodebuild -version 2>/dev/null || true

A missing adb is acceptable if you only need iOS. A missing xcodebuild is expected on Linux and Windows.

Step 1: Install Appium 3 and Confirm the CLI

Install Appium globally with npm:

npm install --global appium@3

Ask the installed executable for its version and help:

appium --version
appium --help
appium driver --help
appium plugin --help

The driver and plugin command groups are the Extension CLI. They manage extensions in Appium's home directory, which defaults to ~/.appium. They do not add packages to the current application's package.json.

If your shell reports appium: command not found, inspect npm's global executable location and restart the shell after correcting PATH:

npm prefix --global
npm list --global --depth=0

With a Node version manager, verify that the active shell uses the same Node installation where Appium was installed. Switching Node versions can switch the global npm package directory too.

Verify the step: appium --version must print a version beginning with 3., and both extension help commands must exit successfully. Do not continue if the command resolves to Appium 2 or an unrelated executable.

Step 2: Run the appium 3 install drivers plugins cli Audit

Before installing a driver, inspect the Extension CLI's view of the environment:

appium driver list
appium driver list --installed
appium plugin list
appium plugin list --installed

The broad list shows extensions known to Appium's extension metadata. The installed view is your local source of truth. It helps you avoid assuming that a driver bundled with an older Appium setup still exists after moving to a clean Appium 3 home.

The output distinguishes installed extensions from available ones and normally displays package versions. Treat names shown by the CLI as identifiers for later commands. Common driver identifiers include uiautomator2 and xcuitest; common plugin identifiers include images and relaxed-caps.

You can also make the Appium home location explicit. This is useful for isolated experiments and CI images:

export APPIUM_HOME="$PWD/.appium-home"
appium driver list --installed

Do not commit that directory. It contains downloaded packages and generated state. In production CI, point APPIUM_HOME to a cacheable location or rebuild it deterministically.

Verify the step: both list --installed commands must run without a stack trace. On a clean home, an empty installed list is correct. Record the displayed versions if extensions already exist, because later installation or update commands can change them.

Step 3: Install the Android UiAutomator2 Driver

Install the official Android driver by its Extension CLI name:

appium driver install uiautomator2

Then list it and run its doctor checks:

appium driver list --installed
appium driver doctor uiautomator2

Installation downloads the driver package into APPIUM_HOME. It does not install the Android SDK, create an emulator, choose an application, or configure Java. The doctor command checks important host dependencies and reports required and optional fixes.

Confirm that Android Debug Bridge can see a target:

adb devices

An emulator or physical device should appear with the state device. If it appears as unauthorized, unlock the physical phone and accept the debugging prompt. If no row appears, start an emulator or repair the SDK and USB setup before blaming Appium.

For a shared environment, capture the driver version from the installed list and document it beside the Appium version. Avoid blindly adding @latest to automated provisioning because an unreviewed driver change can alter platform behavior.

Verify the step: appium driver list --installed must show uiautomator2. The doctor command should report mandatory checks as successful, or clearly identify a host dependency you must install. Finally, adb devices must show at least one usable target before Step 7.

Step 4: Install the XCUITest Driver When Needed

Run this step on macOS when your project automates iOS:

appium driver install xcuitest
appium driver list --installed
appium driver doctor xcuitest

Check the Apple toolchain separately:

xcode-select --print-path
xcodebuild -version
xcrun simctl list devices available

The XCUITest driver uses WebDriverAgent to communicate with simulators and real devices. Installing the extension does not finish real-device provisioning. A physical iPhone requires a trusted device, valid signing configuration, an Apple development team, and network or USB connectivity appropriate to your test setup.

If your team tests Android only, skip XCUITest. Every extra extension increases the packages you patch, audit, and reproduce. A focused Appium home is easier to troubleshoot than a workstation containing every known driver.

On Linux or Windows, keep iOS execution on a macOS worker. You may still prepare cross-platform client code elsewhere, but session creation must reach an Appium server hosted where Xcode is available.

Verify the step: the installed list must show xcuitest), the doctor output must not contain unresolved mandatory failures, and xcrun simctl list devices available` must show at least one available simulator when simulator testing is planned. A successful driver installation alone is not enough.

Step 5: Install Appium Plugins with the CLI

Plugins extend server behavior across drivers. Install two examples:

appium plugin install images
appium plugin install relaxed-caps
appium plugin list --installed

The images plugin supports image-related commands and image element finding. Depending on the host and plugin version, image processing can require native dependencies, so read installation output and run a small image test before relying on it in CI.

The relaxed-caps plugin allows extension capabilities without the appium: vendor prefix. It can help migrate old test suites, but standards-compliant W3C capabilities with explicit prefixes remain clearer. Treat this plugin as a compatibility tool, not permission to keep ambiguous capability names forever.

Installation and activation are different operations. A plugin present in the installed list is available to Appium, but Appium does not automatically turn on every installed plugin.

If your project needs another plugin, inspect the available list and official plugin documentation before installing it. Do not copy arbitrary npm package names into a privileged automation host.

Verify the step: appium plugin list --installed must contain both images and relaxed-caps with versions. If installation fails while compiling a native package, preserve the complete npm error, confirm the active Node architecture, and install the operating-system prerequisites named by the failing package.

Step 6: Activate Plugins and Start the Server

Activate installed plugins explicitly with --use-plugins. Start Appium with both examples:

appium --use-plugins=images,relaxed-caps

Keep this terminal open. Read the startup log. It should load both plugins and then listen on the default Appium address and port, commonly http://0.0.0.0:4723.

From a second terminal, query the status endpoint:

curl --fail --silent http://127.0.0.1:4723/status

For day-to-day use, activate only plugins required by the suite:

appium --use-plugins=images

You can also use --use-plugins=all, but explicit names make behavior easier to review and reproduce. An installed plugin may change request handling, capabilities, routes, or commands, so enabling everything is rarely the cleanest default.

The base URL for modern Appium is http://127.0.0.1:4723, not the historical /wd/hub path unless you deliberately configure a base path. Client configuration and health checks must agree with the server.

For durable server arguments, move reviewed settings into a configuration file rather than growing a fragile shell command. The Appium 3 config file setup tutorial explains that next step.

Verify the step: startup logs must say that the selected plugins loaded without error. The status request must return JSON containing a truthy value.ready field. Stop the server with Ctrl+C before changing the extension set.

Step 7: Create a Real Android Session

A health endpoint proves that the server process runs. A session proves that Appium can select the driver, connect to the device, and initialize automation.

Start the server in one terminal:

appium --use-plugins=images

In another terminal, create a session against an available Android emulator or device:

curl --fail --silent   --header 'Content-Type: application/json'   --request POST   --data '{
    "capabilities": {
      "alwaysMatch": {
        "platformName": "Android",
        "appium:automationName": "UiAutomator2",
        "appium:deviceName": "Android",
        "appium:noReset": true
      },
      "firstMatch": [{}]
    }
  }'   http://127.0.0.1:4723/session

If more than one target is connected, add "appium:udid": "DEVICE_SERIAL" using a serial from adb devices. If you want to launch an application, add its package and activity or provide an appium:app path that the server can access.

Copy the returned session ID, then delete the session:

SESSION_ID="replace-with-returned-session-id"
curl --fail --silent   --request DELETE   "http://127.0.0.1:4723/session/$SESSION_ID"

This request uses W3C capability names. Standard capabilities such as platformName remain unprefixed. Appium-specific capabilities use appium:, even if the relaxed-caps plugin is available.

Verify the step: the response must include a nonempty session ID and must not contain an Appium error object. Server logs should show UiAutomator2 selected for the request. The delete request should end the session so the device is ready for another test.

Step 8: Pin, Update, and Remove Extensions Safely

Extension maintenance is part of installation. First capture the current state:

appium --version
appium driver list --installed
appium plugin list --installed

Before upgrading a driver or plugin, read its release notes and confirm compatibility with your Appium major version, Node version, and platform toolchain. The Appium 3 driver version management guide covers repeatable pinning and controlled updates in depth.

Use the CLI help as the authority for the exact update syntax supported by your installed Appium release:

appium driver update --help
appium plugin update --help

Then update a named extension only after review:

appium driver update uiautomator2
appium plugin update images

Re-run doctor and session verification after every driver update. A package update that exits with code zero can still expose a mismatch with an old Android SDK, Xcode release, emulator image, or client capability set.

Remove extensions your project no longer uses:

appium plugin uninstall relaxed-caps
appium driver uninstall xcuitest

Run the uninstall command only when the named extension is outside your test matrix. On a shared host, coordinate before removal because another suite may depend on it.

Verify the step: list installed extensions again and compare names and versions with the intended baseline. Start the server using the approved plugins, query /status, and create one smoke session per retained driver. Commit the version record or provisioning script used by your team, not the generated APPIUM_HOME directory.

Troubleshooting

Problem: appium: command not found after npm installation -> Run npm prefix --global, locate the global binary directory, and add it to PATH. If you use nvm, fnm, Volta, or another Node manager, activate the Node version that owns the Appium installation.

Problem: npm returns EACCES during a global install -> Use a Node version manager or a user-owned npm global prefix. Do not recursively change ownership of system directories without understanding what other software uses them.

Problem: the driver is installed but session creation says no matching driver was found -> Confirm platformName and appium:automationName spelling, capitalization, and prefixes. Run appium driver list --installed, then restart the Appium server so it discovers the current extension state.

Problem: UiAutomator2 doctor reports missing Android tools -> Set ANDROID_HOME to the actual SDK root, add platform-tools to PATH, install required SDK packages, accept licenses, and verify adb devices. The driver installer cannot repair an incomplete Android SDK.

Problem: a plugin appears installed but has no effect -> Stop Appium and restart it with --use-plugins=plugin-name. Check startup logs for plugin activation and confirm the request actually uses a route or capability the plugin changes.

Problem: an update breaks previously passing sessions -> Compare the recorded before and after versions, restore the reviewed version through your provisioning baseline, and rerun doctor plus a minimal session. Avoid deleting all caches first because logs and version evidence help isolate the incompatible layer.

Best Practices

• Install only the drivers and plugins used by the project's test matrix.
• Keep Appium core, extension, Node.js, Android SDK, and Xcode versions in one environment record.
• Use a dedicated, predictable APPIUM_HOME in CI.
• Treat list --installed, doctor checks, server status, and a smoke session as four separate verification layers.
• Activate plugins explicitly and review their effect on server behavior.
• Use W3C capability prefixes even when a compatibility plugin can relax them.
• Upgrade one extension at a time, then test before changing the next layer.
• Keep secrets, signing files, and device credentials outside extension installation scripts.
• Rebuild CI workers from the recorded baseline regularly to prove that setup is reproducible.

Common Mistakes

The most common mistake is assuming Appium includes a default mobile driver. Appium 3 keeps core, drivers, and plugins separate, so a running server can still be unable to automate Android or iOS.

Another mistake is confusing package installation with platform readiness. UiAutomator2 needs a usable Android toolchain and target. XCUITest needs macOS, Xcode, simulators or devices, and sometimes signing. Doctor checks expose many of these gaps early.

Teams also install plugins and forget to activate them. Keep --use-plugins in the reviewed server command or configuration, and assert plugin startup in logs.

Finally, avoid unreviewed upgrades on every CI run. A reproducible stack is more valuable than silently collecting new versions. When moving an existing suite from Appium 2, use the Appium 2 to Appium 3 migration tutorial to separate migration changes from extension upgrades.

Where To Go Next

You now have a verified extension stack. Continue with the part that matches your responsibility:

• Use the complete Appium 3 mobile automation guide to place drivers, clients, devices, and CI in one architecture.
• Put reviewed server options into a reusable file with the Appium 3 configuration tutorial.
• Establish a team upgrade policy with Appium 3 driver version management.
• Modernize an existing framework through the Appium 2 to Appium 3 migration guide.
• Add platform-specific smoke tests after every environment build, including one session per driver and one command per enabled plugin.

Interview Questions and Answers

Q: Why does Appium 3 not automate Android immediately after installing Appium core?

Appium core provides the server and extension system. Android automation is implemented by a separate driver such as UiAutomator2, which you install with the Extension CLI. The host also needs Android SDK tools and a reachable target.

Q: What is the difference between an Appium driver and an Appium plugin?

A driver translates WebDriver sessions and commands for a specific automation technology or platform. A plugin modifies or extends Appium server behavior, routes, commands, or capability processing. Drivers are selected by session capabilities, while plugins must usually be activated when the server starts.

Q: How do you verify a driver installation?

Run appium driver list --installed, then run appium driver doctor <name> when supported. Start the server and create a minimal real session. The session is the strongest proof because it validates driver selection and host integration.

Q: Why is an installed plugin not active?

Appium separates plugin installation from activation. Start the server with --use-plugins=name or configure the approved plugin list through server configuration. Confirm activation in startup logs.

Q: How should a team control Appium extension versions?

Record Appium core and every installed extension version, review compatibility before updates, and provision the same baseline on developer and CI machines. Upgrade one layer at a time and rerun doctor checks plus smoke sessions.

Q: What does APPIUM_HOME control?

It identifies the directory where Appium stores installed extensions and related state. Setting it explicitly can isolate projects or make CI caching predictable. The generated directory should not replace a human-readable version baseline.

Q: Should you use relaxed capabilities in a new framework?

Prefer standard W3C capabilities and the appium: prefix for Appium-specific keys. Relaxed capabilities can support a staged migration, but explicit prefixes make ownership clear and reduce ambiguity.

Conclusion

The reliable appium 3 install drivers plugins cli process is more than three install commands. Install Appium core, inspect the environment, add only required extensions, activate plugins explicitly, and verify the stack through lists, doctor checks, server health, and real sessions.

Record the resulting versions before you scale the setup to teammates or CI. That baseline turns an individual workstation experiment into a repeatable Appium 3 automation environment.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Appium 3 Driver Version Management: A Practical Tutorial
• Appium 3 Config File Setup Tutorial: capabilities and .conf (2026)
• Migrate an Appium 2 Framework to Appium 3
• AI test data generation with Faker and LLMs (2026)
• Appium 3 Mobile Automation Complete Guide (2026)
• Appium gestures and swipe: A Practical Guide (2026)