Guide · Open source

How to use madge: graph module dependencies and find cycles

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Madge is a command-line tool and Node.js library that reads your source code, works out which files import which others, and shows the result as a visual graph. This guide explains how to install it, run it from the command line, and use its main options. By the end you will be able to find circular dependencies, orphaned files and modules with no dependencies in a JavaScript project.

Madgepahen/madge · ★ 10.2k · MIT Install options & downloads

Quick start

1Install madge. Run npm -g install madge to add the madge command globally. You need Node.js and npm first.
2Install Graphviz if you want images. Graphviz is optional. Install it with brew or port on Mac OS X, or apt-get on Ubuntu, only if you need SVG or DOT graph output.
3Run madge on your entry file. Run madge followed by the path to your main file or source directory to list its dependencies.
4Check for circular dependencies. Add the --circular flag to list modules that import each other in a loop.
5Find orphans and dependents. Use --orphans to list modules nothing depends on, or --depends with a file name to see which modules import it.
6Add a config file if needed. Create a .madgerc file or a madge key in package.json to set options such as fileExtensions or graph colours.

What madge does and who it is for

Madge generates a visual graph of your module dependencies and can also report circular dependencies and other useful information. It works with JavaScript modules in AMD, CommonJS and ES6 formats, and it also handles CSS preprocessor files written in Sass, Stylus and Less.

It is aimed at JavaScript developers working on large codebases with many imports, teams that want to catch circular dependencies early, and anyone who wants a picture of how a project's modules fit together. It is not aimed at non-developers, because it runs from the command line or from Node.js code.

Works for JavaScript (AMD, CommonJS, and ES6 modules)
Works for CSS preprocessors (Sass, Stylus, and Less)
NPM installed dependencies are excluded by default (can be enabled)
All core Node.js modules (assert, path, fs, etc) are excluded

Install madge and Graphviz

Madge is installed with npm. The README uses a global install command. Graphviz is optional and is only needed if you want visual graph output such as SVG or DOT images. You will need Node.js and npm.

Graphviz is listed as optional in the README, with separate install commands for Mac OS X and Ubuntu.

Mac OS X (optional Graphviz): brew install graphviz, or port install graphviz
Ubuntu (optional Graphviz): apt-get install graphviz

npm -g install madge

Run madge from the command line

Pass madge a file or directory and it lists the dependencies it finds. You can give it a single file, several files, or one or more directories. When you point it at a directory, it reads all *.js files found there by default.

To include other extensions, use the --extensions flag. The README gives the example of reading both .js and .jsx files in a directory.

Single file: madge path/src/app.js
Several files: madge path/src/foo.js path/src/bar.js
A directory: madge path/src
Several directories: madge path/src/foo path/src/bar
Extra extensions: madge --extensions js,jsx path/src

madge path/src/app.js

Find circular dependencies, orphans and dependents

Circular dependencies are the main reason to run madge. The --circular flag reports modules that import each other in a loop. The --depends flag shows which modules depend on a given module, and --orphans shows modules that no other module depends on.

The README also describes a leaves function, which returns modules that have no dependencies, and the README's CLI section continues with that option. Check the CLI help for the exact flag names in your installed version.

Circular: madge --circular path/src/app.js
Dependents of a module: madge --depends wheels.js path/src/app.js
Orphans: madge --orphans path/src/

madge --circular path/src/app.js

Use madge in Node.js code

You can call madge from your own script. The madge function takes a path (a file, directory, array, or predefined tree object) and an optional config object, and returns a Promise that resolves with a Madge instance. The instance provides methods such as obj(), circular(), depends(), orphans(), leaves(), dot(), image() and svg().

The image() method writes the graph to a file, and the image format is determined from the file extension. The README's example writes an SVG.

.obj() returns all dependencies as an Object
.circular() returns an Array of modules with circular dependencies
.depends(file) returns an Array of modules that depend on a given module
.orphans() returns an Array of modules nobody depends on
.leaves() returns an Array of modules with no dependencies

const madge = require('madge');

madge('path/to/app.js')
	.then((res) => res.image('path/to/image.svg'))
	.then((writtenImagePath) => {
		console.log('Image written to ' + writtenImagePath);
	});

Configure madge with .madgerc or package.json

Configuration is optional. You can put it in a .madgerc file in your project or home folder, or inside the madge key of package.json. The README lists options such as baseDir, includeNpm, fileExtensions, excludeRegExp, requireConfig, webpackConfig, tsConfig, layout, rankdir, fontName, fontSize, backgroundColor, nodeShape, nodeStyle, nodeColor, noDependencyColor, cyclicNodeColor, edgeColor, graphVizOptions, graphVizPath, detectiveOptions and dependencyFilter.

Default values in the README include rankdir set to LR, layout set to dot, and cyclicNodeColor set to #ff6c60. Circular nodes are shown in red, and nodes with no dependencies in green.

fileExtensions defaults to ['js']
includeNpm defaults to false
Nodes with circular dependencies use cyclicNodeColor

{
  "fontSize": "10px",
  "graphVizOptions": {
    "G": {
      "rankdir": "LR"
    }
  }
}

What people use it for

Untangling a large codebase by viewing which files import which others
Catching circular dependencies in a team project before they cause bugs
Checking the dependencies of a project that uses Sass, Stylus or Less
Finding modules that nothing else uses with the orphans option

Frequently asked questions

Is madge free to use?

Madge is released under the MIT licence, as stated in the project's listing. Check the LICENSE file in the repository for the full terms.

What do I need to install madge?

The source lists Node.js and npm as prerequisites. Graphviz is optional and is only needed for visual graph output such as SVG or DOT.

Does madge work without Graphviz?

The source says image output depends on Graphviz. Without it you can still use the text-based commands and methods that return lists or objects, such as --circular and orphans.

Which languages and file types does madge support?

The README says madge works with JavaScript modules in AMD, CommonJS and ES6 formats, and with Sass, Stylus and Less files. Projects that need other languages should check the README before relying on it.

How do I find circular dependencies with madge?

Run madge --circular followed by your file or directory path. It lists modules that have circular dependencies.

How does madge compare to dependency-cruiser or webpack-bundle-analyzer?

This guide does not have verified comparison data. dependency-cruiser and webpack-bundle-analyzer are listed as comparable projects, so review their own documentation to decide which fits your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Madge suits JavaScript developers and teams who need to see module structure, find circular dependencies or locate orphaned files, and who are comfortable with the command line. It is less suitable for non-developers or for languages beyond the JavaScript and preprocessor formats listed in its README, where you should look at the comparable projects instead.

Install options & downloads