How to use APPIUM_HOME for Appium extensions

Project test suites can load the wrong Appium driver when every install goes into the default user extension directory. APPIUM_HOME points Appium at a separate driver and plugin directory, so a project or CI job can install the extensions it needs without changing another suite.

Appium stores managed drivers and plugins outside the server package. If APPIUM_HOME is unset, Appium uses ~/.appium; when it is set, the extension CLI and Appium server read extension metadata and packages from that directory instead.

Use the same APPIUM_HOME value when installing extensions, listing extensions, and starting the server. Keep project-local homes out of source control because they contain installed npm packages and cache metadata, and recreate or cache them as part of the local or CI setup.

1. Open a terminal in the project root.
2. Create a project-local Appium home directory.

   $ mkdir -p .appium-home/android

3. Install the Android driver into that home.

   $ APPIUM_HOME="$PWD/.appium-home/android" appium driver install uiautomator2
   - Checking if 'appium-uiautomator2-driver' is compatible
   - Installing 'uiautomator2'
   - Validating 'uiautomator2'
   Driver uiautomator2@7.6.1 successfully installed
   - automationName: UiAutomator2
   - platformNames: ["Android"]

   Use the driver or plugin name required by the project. The selected APPIUM_HOME receives the npm package and Appium extension metadata for this install.

   Related: How to install the Appium Android driver

4. List installed drivers from the same home.

   $ APPIUM_HOME="$PWD/.appium-home/android" appium driver list --installed
   - Listing installed drivers (rerun with --verbose for more info)
   - uiautomator2@7.6.1 [installed (npm)]

5. List a different Appium home before using it.

   $ APPIUM_HOME="$PWD/.appium-home/web" appium driver list --installed
   - Listing installed drivers (rerun with --verbose for more info)

   No driver row below the listing line means Appium is reading a separate home with no installed drivers yet.

6. Start Appium with the same home used for the project.

   $ APPIUM_HOME="$PWD/.appium-home/android" appium --address 0.0.0.0 --port 4723

   Starting Appium without this environment variable makes the server fall back to the default ~/.appium directory and can hide drivers installed only in the project home.

   Related: How to start the Appium server

7. Keep the project-local Appium home out of source control.

   .appium-home/