Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Standalone CLI Tool
✓ react-devtools
✗ import { DevTools } from 'react-devtools'
The primary interaction is running the `react-devtools` command directly in your terminal to launch the GUI application.
Client Connection Script (ESM)
✓ import 'react-devtools';
✗ const DevToolsClient = require('react-devtools');
This is a side-effect import that should be the very first import in your application's entry point (e.g., `index.js`) to establish a connection to the running standalone DevTools. It does not export any symbols for programmatic use.
Client Connection Script (HTML)
✓ <script src="http://localhost:8097"></script>
✗ <script type="module">import 'react-devtools';</script>
For HTML-based applications (e.g., Safari, IFrames), embed this script tag as the very first script in the `<head>` section of your page to enable connection. This script *must* be removed before deploying to production.
Demonstrates global installation, launching the standalone DevTools app, and setting up client connections for React Native and web-based applications.
npm install -g react-devtools
react-devtools
// For React Native (0.43+) debugging, if not using a local simulator,
// ensure port forwarding from device to host:
adb reverse tcp:8097 tcp:8097
// For web/iframe debugging, add this as the very first script in your HTML <head>:
// <script src="http://localhost:8097"></script>
// (Remember to remove this line for production builds!)
// Alternatively, if react-devtools is a project dependency:
npm install --save-dev react-devtools
npx react-devtools &
// In your application's main entry file (e.g., src/index.js), add as the first line:
// import 'react-devtools';
// (Also remove this import for production builds!)
react-devtools --version
Debug
Known issues
breakingReact DevTools has compatibility requirements with the major version of React it is debugging (e.g., DevTools 7.x is designed for React 18/19). Using a significantly mismatched version can lead to connection failures, incorrect component introspection, or missing features.fixEnsure your `react-devtools` package version aligns with the major version of `react` and `react-dom` used in your application. Consult the official React documentation or release notes for specific compatibility information.
affects: All versions
gotchaThe DevTools client connection script (either the `<script>` tag or `import 'react-devtools';`) is for development purposes only and *must* be removed from production builds. Leaving it in will unnecessarily increase your bundle size, potentially impact performance, and expose internal debugging capabilities.fixUtilize build-time environment variables, conditional compilation, or Webpack configurations to ensure the DevTools client code is completely excluded from your production assets.
affects: All versions
gotchaThe standalone DevTools app listens on port 8097 by default. If another application is already using this port, or if network configurations (like firewalls or VPNs) prevent access, the DevTools will fail to connect. For React Native on physical devices, port forwarding is crucial.fixEnsure port 8097 is free and accessible. On React Native, use `adb reverse tcp:8097 tcp:8097` for Android devices. If necessary, explore options to configure the DevTools to use an alternative port (though this is less common for the standalone app).
affects: All versions
gotchaWhen `react-devtools` is connected to a React Native application, the in-app Inspector will enter a special collapsed mode, deferring UI inspection to the standalone DevTools GUI. This alters the expected behavior of the native Inspector.fixTo exclusively use the React Native in-app Inspector, ensure the `react-devtools` standalone application is not running or disconnect your app from it. The 'Hide Inspector' option in the in-app developer menu can also be used.
affects: All versions (React Native)
Errors
Common errors & fixes
Could not connect to React DevTools.
This error typically indicates that the standalone `react-devtools` application is not running, the client-side connection script is missing or misconfigured, or there is a network connectivity issue (e.g., port blocked, `adb reverse` not applied).
fixFirst, verify that `react-devtools` is actively running in your terminal. For web apps, ensure `<script src="http://localhost:8097"></script>` is the very first script in `<head>` or `import 'react-devtools';` is the first line in your entry file. For React Native, confirm `adb reverse tcp:8097 tcp:8097` has been executed if debugging on a physical device or remote emulator.
Failed to load resource: net::ERR_CONNECTION_REFUSED
When debugging a web application, this browser error means the client-side connection script tried to reach the DevTools server at `http://localhost:8097` but was refused, usually because the `react-devtools` command was not started or crashed.
fixStart the `react-devtools` application in your terminal. If it's already running, ensure no other process is blocking port 8097 or that your browser isn't configured with proxies preventing localhost access.
Module not found: Can't resolve 'react-devtools'
This error occurs in a build process (e.g., Webpack, Vite) when your application code uses `import 'react-devtools';` but the `react-devtools` package is not listed as a dependency in your project's `package.json`.
fixInstall `react-devtools` as a development dependency: `npm install --save-dev react-devtools` or `yarn add --dev react-devtools`. If you prefer a global install, you'll need to use `npx react-devtools` to launch the tool and not rely on the `import` statement in your app code for connection.
Audit
Dependencies
No dependency data recorded yet.