How to Use Appium Doctor to Diagnose Appium Setup Issues
Use Appium’s extension-specific Doctor checks to find missing setup prerequisites, understand their limits, and verify an Android UiAutomator2 environment.
Use the Doctor command built into the Appium CLI for the driver or plugin you have installed. For Android with UiAutomator2, run appium driver doctor uiautomator2. It checks prerequisites that the installed driver knows how to validate. A clean result is useful evidence about those prerequisites, but it does not guarantee that a particular device, app, capability set, or test session will work.
The old standalone appium-doctor command and the @appium/doctor package are deprecated. Current instructions should start with the installed extension and its official setup guide, not a global install of the legacy tool.
1. Identify the installed extension and platform
Appium’s server runtime requirements are only the base layer. A driver adds platform-specific requirements, such as Android SDK components or Apple’s iOS development toolchain. First identify the platform and driver your test will use, then follow that driver’s official setup instructions.
For Android, this guide uses the UiAutomator2 driver. For iOS, use the corresponding installed iOS driver and follow its platform-specific toolchain requirements; do not assume that Android checks cover iOS.
The Appium project lists macOS, Linux, or Windows as supported environments for the server, and requires Node.js ^20.19.0 || ^22.12.0 || >=24.0.0 and npm >=10. These are server requirements, not a complete checklist for any particular driver. See Appium System Requirements and the setup guide for your driver.
2. Install Appium and the driver
With a compatible Node.js and npm installation, install Appium if it is not already available, then install UiAutomator2 through the Appium CLI:
npm install --global appium
appium driver install uiautomator2If Appium is already installed, you can skip the first command. Check the installed extensions with:
appium driver list --installedUse the driver version and setup instructions appropriate for your project. The official UiAutomator2 Driver Quickstart walks through the Android driver workflow.
3. Run the Doctor check
Run the documented UiAutomator2 check from a terminal where the Appium CLI is available:
appium driver doctor uiautomator2The general command form is appium driver doctor <driver-name> or appium plugin doctor <plugin-name>. Doctor checks belong to an installed extension. A driver or plugin may not provide any checks; in that case the command can produce no results. Follow that extension’s official setup guide and verify its platform tools independently.
For tooling that needs structured output, the CLI reference documents the --json option:
appium driver doctor uiautomator2 --jsonUse the JSON form when you want to inspect or store the result in a script or setup report. Keep the human-readable output available when troubleshooting interactively.
4. Interpret the results and fix prerequisites
Read each reported item as a prerequisite diagnostic for that extension. Resolve items marked as required, then run the same command again. Optional recommendations are distinct from required fixes. The UiAutomator2 quickstart says: “This guide has focused on essential requirements, so Appium Doctor may suggest one or more optional fixes.”
If the driver reports zero required fixes, the setup requirements that it checks are satisfied. That result does not test whether a device is reachable, an application is installable, capabilities are valid, or the test logic is correct. Treat Doctor as one setup check in a larger debugging process.
5. Start Appium and validate a real session separately
After the prerequisite checks pass, start the server:
appiumThen run a minimal session using the capabilities and app appropriate to your environment. If the session fails, inspect the server log and the specific session error. Doctor’s result cannot establish that the device, app path, permissions, network connection, or requested capabilities are correct.
What Appium Doctor checks—and what it does not
| Question | What to expect |
|---|---|
| Does it check Appium prerequisites? | Yes, the checks supplied by the installed driver or plugin. |
| Does every extension have checks? | No. Some extensions provide no Doctor checks, so there may be no results. |
| Does a clean result prove my test will pass? | No. It only speaks to the prerequisites that were checked; validate a real session separately. |
| Does the Android UiAutomator2 command validate iOS? | No. Use the installed iOS driver and its platform-specific setup guidance. |
| Can I get machine-readable output? | The CLI reference documents --json for Doctor. |
Common errors and fixes
appium: command not found or not recognized
The Appium CLI may not be installed, or its executable directory may not be on the shell’s PATH. Confirm that Node.js and npm are available, install Appium if needed, and reopen the terminal after correcting the PATH. If you use a project-local installation, invoke the CLI through that project’s package scripts or local executable.
The driver is not installed
Doctor checks are extension-specific. Install the driver your test uses, then verify it appears in appium driver list --installed. For the Android example, install uiautomator2 and rerun its Doctor command.
The command prints no checks or no results
The extension may not include Doctor checks, or the named extension may not be installed. Confirm the extension name and installation. If it is installed and still provides no checks, use its official requirements guide and validate the platform tools directly; an empty result is not a pass for unexamined prerequisites.
A required prerequisite is missing
Use the failed check’s description and the driver’s setup guide to identify the required SDK, environment setting, or tool. Install or configure that prerequisite, open a fresh terminal if environment variables changed, and rerun Doctor.
Doctor is clean but the session still fails
Move to session-level diagnosis. Check that the device is connected and authorized, that the app and package identifiers are correct, that capabilities match the driver, and that the Appium server log identifies the failing stage. These are examples of session inputs that a prerequisite check does not prove.
An old tutorial says to install appium-doctor
That is legacy guidance. The standalone repository and @appium/doctor package are deprecated. Use the Appium CLI’s driver or plugin Doctor command when the installed extension provides checks.
Legacy instructions: what changed
Older guides may show npm install -g appium-doctor followed by commands such as appium-doctor --android or appium-doctor --ios. Those commands belong to the deprecated standalone CLI; do not treat them as the current route. The @appium/doctor package is also marked deprecated and directs users to checks integrated with an installed driver or plugin, where available.
Reliability and maintenance notes
- Run the check for the extension actually installed and used by the test.
- Rerun after changing a reported prerequisite or relevant environment setting.
- Use the extension’s official setup guide as the authority for requirements that its Doctor checks do not cover.
- Keep prerequisite validation separate from a real device and app session check.
- When automating setup diagnostics, capture the JSON output and the CLI exit status in your own tooling; interpret the actual reported checks rather than treating the presence of output as proof that the environment is ready.
Or skip the browser setup
Appium Doctor is for diagnosing mobile automation prerequisites. If your workflow also needs website screenshots—for example, to inspect a web page or capture a browser-rendered result—ScreenshotNeo provides a website screenshot API and MCP server for developers. One GET request can return an image or PDF. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.
Sign up for 1,000 free screenshots a month, with no card required.
FAQ
How do I use Appium Doctor to diagnose setup issues?
Install the driver or plugin for your target, then run its Appium CLI Doctor command. For Android UiAutomator2, use appium driver doctor uiautomator2.
What does appium driver doctor uiautomator2 check?
It reports prerequisite checks provided by the installed UiAutomator2 driver. Consult that driver’s setup guide for the complete requirements and anything the checks do not cover.
Should I install appium-doctor separately?
No. The standalone CLI and the @appium/doctor package are deprecated. Use the integrated extension check when available.
Can Appium Doctor tell me why a test failed?
It can help identify missing setup prerequisites, but it is not a general test-session diagnosis tool. Use the Appium server log and a separate session check for device, app, capability, and test failures.
