Maven Dependency Tree Visualizer

A simple command-line tool to visualize the dependency tree of a Maven project in a graphical and interactive format.

This tool was born out of the frustration of not being able to easily visualize the dependency tree of a Maven project. The mvn dependency:tree command is great, but the output can be hard to read, especially for large projects. This tool aims to solve that problem by providing a simple way to generate an interactive diagram or a structured JSON output of the dependency tree.

Table of Contents

• Features
• Installation
• How to Use
• Examples
• Options
• Performance
• Troubleshooting
• Contributing
• License

Installation

Install the package from PyPI:

pip install mvn-tree-visualizer

Features

• 🌐 Multiple Output Formats:
  • HTML: Generates an interactive HTML diagram of your dependency tree using Mermaid.js.
  • JSON: Creates a structured JSON representation of the dependency tree, perfect for scripting or integration with other tools.
• 🎨 Theme System: Choose from 2 built-in themes (minimal, dark) for clean and consistent diagram styling.
• 🔄 Watch Mode: Automatically regenerates diagrams when Maven dependency files change using the --watch flag.
• 📋 Version Display: Toggle dependency versions in outputs with --show-versions
• 💾 Enhanced Downloads: SVG and PNG export directly from browser
• 📂 Smart File Handling: Automatically finds and merges multiple maven_dependency_file files from different subdirectories.
• 🎯 Color Coding: Visual distinction between root, intermediate, and leaf dependencies

How to Use

Step 1: Generate the dependency file

Run the following command in your terminal at the root of your Maven project. This will generate a file named maven_dependency_file in each module's target directory.

mvn dependency:tree -DoutputFile=maven_dependency_file -DappendOutput=true

💡 Tip: You can add other options like -Dincludes="org.example" to filter the dependencies.

Step 2: Visualize the dependency tree

Use the mvn-tree-visualizer command to generate the diagram.

HTML Output (Interactive Diagram)

mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --format html

JSON Output (Structured Data)

mvn-tree-visualizer --filename "maven_dependency_file" --output "dependencies.json" --format json

With Version Information

mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --show-versions

With Custom Themes

# Dark theme for low-light environments  
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --theme dark

# Default minimal theme (clean monospace design)
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html"

JSON Output with Versions

mvn-tree-visualizer --filename "maven_dependency_file" --output "dependencies.json" --format json --show-versions

Watch Mode (Auto-regeneration)

mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --watch

Quiet Mode (For Automation/Scripts)

# Only show errors, suppress success messages
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --quiet

# Short form also available
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" -q

Auto-Open in Browser

# Automatically open the generated HTML diagram in your default browser
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --open

Timestamped Output Files

# Generate files with timestamps (e.g., diagram_20250813_143022.html)
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --timestamp-output

# Combine with auto-open for immediate viewing
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --timestamp-output --open

💡 Tip: In watch mode, the tool will monitor for changes to your Maven dependency files and automatically regenerate the diagram. Perfect for development workflows! Press Ctrl+C to stop watching.

Step 3: View the output

• HTML: Open the generated diagram.html file in your web browser to view the interactive dependency tree.
• JSON: Use the dependencies.json file in your scripts or other tools.

Examples

Check out the examples/ directory for sample Maven dependency files and their outputs:

• Simple Project: Basic Spring Boot application with common dependencies
• Complex Project: Realistic microservice with comprehensive dependencies

Each example includes:

• Sample Maven dependency tree file
• Generated HTML and JSON outputs
• Usage instructions

Options

Option	Description	Default
--filename	The name of the file containing the Maven dependency tree	maven_dependency_file
--output	The name of the output file	diagram.html
--format	The output format (html or json)	html
--theme	Theme for HTML diagrams (minimal, dark)	minimal
--show-versions	Show dependency versions in the diagram	False
--watch	Watch for file changes and auto-regenerate diagram	False
--directory	The directory to scan for the Maven dependency file(s)	current directory
--keep-tree	Keep the intermediate dependency_tree.txt file	False
--quiet, -q	Suppress all console output except errors	False
--open	Automatically open generated HTML files in default browser	False
--timestamp-output	Add timestamp to output filename (e.g., diagram-2025-08-13-203045.html)	False
--version, -v	Show the current version and exit	-
--help	Show the help message and exit	-

Theme Options

• minimal: Clean monospace design with simple black borders (default)
• dark: Same minimal styling but with white text on black background

📖 See the complete Theme Documentation for detailed information about themes and interactive features.

Performance

For Large Projects:

• Consider filtering dependencies at the Maven level using -Dincludes or -Dexcludes parameters
• The tool can handle projects with hundreds of dependencies efficiently

Memory Usage:

• Memory usage scales with the number of dependencies
• Typical projects (50-200 dependencies) use minimal memory
• Very large projects (1000+ dependencies) may require more memory

Troubleshooting

Common Issues

"No dependency files found"

• The tool now provides detailed guidance including:
  • Exact directory searched and filename expected
  • Maven commands to generate dependency files
  • Instructions to ensure you're in a directory with pom.xml

"Empty or invalid output"

• Enhanced error messages now include:
  • Specific error details (encoding, permissions, empty files)
  • Validation of file content and format
  • Suggestions for fixing common parsing issues

"Browser doesn't display the diagram"

• Ensure you're opening the HTML file in a modern browser
• Check browser console for JavaScript errors
• Try a different browser (Chrome, Firefox, Safari)

"Permission denied errors"

• Improved diagnostics for:
  • Directory read/write permissions
  • File access issues
  • Output directory creation problems

Getting Help

• Check the examples directory for working samples
• Review the issues page
• Create a new issue with your Maven dependency file sample

Contributing

Contributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request.

Please read our CONTRIBUTING.md file for more details.

License

This project is licensed under the MIT License - see the LICENSE file for details.