# Maven Dependency Tree Visualizer
[](https://badge.fury.io/py/mvn-tree-visualizer)
[](https://pepy.tech/project/mvn-tree-visualizer)
[](https://github.com/dyka3773/mvn-tree-visualizer/actions)
[](https://github.com/astral-sh/ruff)
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](#features)
- [Installation](#installation)
- [How to Use](#how-to-use)
- [Examples](#examples)
- [Options](#options)
- [Performance](#performance)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
## Installation
Install the package from PyPI:
```bash
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.
```bash
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)
```bash
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --format html
```
#### JSON Output (Structured Data)
```bash
mvn-tree-visualizer --filename "maven_dependency_file" --output "dependencies.json" --format json
```
#### With Version Information
```bash
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --show-versions
```
#### With Custom Themes
```bash
# 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
```bash
mvn-tree-visualizer --filename "maven_dependency_file" --output "dependencies.json" --format json --show-versions
```
#### Watch Mode (Auto-regeneration)
```bash
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --watch
```
> **💡 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/`](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` |
| `--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](docs/THEMES.md) 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](examples/) directory for working samples
- Review the [issues](https://github.com/dyka3773/mvn-tree-visualizer/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](CONTRIBUTING.md) file for more details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "mvn-tree-visualizer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "cli, command-line, dependency, graph, maven, mermaid, tool, tree, visualization",
"author": null,
"author_email": "Iraklis Konsoulas <dyka3773@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/71/aa/901889b49c09e950efd9b014be996a37361a2589c286ffd528234de51a14/mvn_tree_visualizer-1.6.0.tar.gz",
"platform": null,
"description": "# Maven Dependency Tree Visualizer\n\n[](https://badge.fury.io/py/mvn-tree-visualizer)\n\n\n[](https://pepy.tech/project/mvn-tree-visualizer)\n[](https://github.com/dyka3773/mvn-tree-visualizer/actions)\n[](https://github.com/astral-sh/ruff)\n\nA simple command-line tool to visualize the dependency tree of a Maven project in a graphical and interactive format.\n\nThis 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.\n\n## Table of Contents\n- [Features](#features)\n- [Installation](#installation)\n- [How to Use](#how-to-use)\n- [Examples](#examples)\n- [Options](#options)\n- [Performance](#performance)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nInstall the package from PyPI:\n\n```bash\npip install mvn-tree-visualizer\n```\n\n## Features\n\n- **\ud83c\udf10 Multiple Output Formats:**\n - **HTML:** Generates an interactive HTML diagram of your dependency tree using Mermaid.js.\n - **JSON:** Creates a structured JSON representation of the dependency tree, perfect for scripting or integration with other tools.\n- **\ud83c\udfa8 Theme System:** Choose from 2 built-in themes (minimal, dark) for clean and consistent diagram styling.\n- **\ud83d\udd04 Watch Mode:** Automatically regenerates diagrams when Maven dependency files change using the `--watch` flag.\n- **\ud83d\udccb Version Display:** Toggle dependency versions in outputs with `--show-versions`\n- **\ud83d\udcbe Enhanced Downloads:** SVG and PNG export directly from browser\n- **\ud83d\udcc2 Smart File Handling:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.\n- **\ud83c\udfaf Color Coding:** Visual distinction between root, intermediate, and leaf dependencies\n\n## How to Use\n\n### Step 1: Generate the dependency file\n\nRun 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.\n\n```bash\nmvn dependency:tree -DoutputFile=maven_dependency_file -DappendOutput=true\n```\n\n> **\ud83d\udca1 Tip:** You can add other options like `-Dincludes=\"org.example\"` to filter the dependencies.\n\n### Step 2: Visualize the dependency tree\n\nUse the `mvn-tree-visualizer` command to generate the diagram.\n\n#### HTML Output (Interactive Diagram)\n```bash\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"diagram.html\" --format html\n```\n\n#### JSON Output (Structured Data)\n```bash\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"dependencies.json\" --format json\n```\n\n#### With Version Information\n```bash\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"diagram.html\" --show-versions\n```\n\n#### With Custom Themes\n```bash\n# Dark theme for low-light environments \nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"diagram.html\" --theme dark\n\n# Default minimal theme (clean monospace design)\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"diagram.html\"\n```\n\n#### JSON Output with Versions\n```bash\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"dependencies.json\" --format json --show-versions\n```\n\n#### Watch Mode (Auto-regeneration)\n```bash\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"diagram.html\" --watch\n```\n\n> **\ud83d\udca1 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.\n\n### Step 3: View the output\n\n- **HTML:** Open the generated `diagram.html` file in your web browser to view the interactive dependency tree.\n- **JSON:** Use the `dependencies.json` file in your scripts or other tools.\n\n## Examples\n\nCheck out the [`examples/`](examples/) directory for sample Maven dependency files and their outputs:\n\n- **Simple Project**: Basic Spring Boot application with common dependencies\n- **Complex Project**: Realistic microservice with comprehensive dependencies\n\nEach example includes:\n- Sample Maven dependency tree file\n- Generated HTML and JSON outputs\n- Usage instructions\n\n## Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--filename` | The name of the file containing the Maven dependency tree | `maven_dependency_file` |\n| `--output` | The name of the output file | `diagram.html` |\n| `--format` | The output format (`html` or `json`) | `html` |\n| `--theme` | Theme for HTML diagrams (`minimal`, `dark`) | `minimal` |\n| `--show-versions` | Show dependency versions in the diagram | `False` |\n| `--watch` | Watch for file changes and auto-regenerate diagram | `False` |\n| `--directory` | The directory to scan for the Maven dependency file(s) | current directory |\n| `--keep-tree` | Keep the intermediate `dependency_tree.txt` file | `False` |\n| `--help` | Show the help message and exit | - |\n\n### Theme Options\n\n- **`minimal`**: Clean monospace design with simple black borders (default)\n- **`dark`**: Same minimal styling but with white text on black background\n\n\ud83d\udcd6 **See the complete [Theme Documentation](docs/THEMES.md) for detailed information about themes and interactive features.**\n\n## Performance\n\n**For Large Projects:**\n- Consider filtering dependencies at the Maven level using `-Dincludes` or `-Dexcludes` parameters\n- The tool can handle projects with hundreds of dependencies efficiently\n\n**Memory Usage:**\n- Memory usage scales with the number of dependencies\n- Typical projects (50-200 dependencies) use minimal memory\n- Very large projects (1000+ dependencies) may require more memory\n\n## Troubleshooting\n\n### Common Issues\n\n**\"No dependency files found\"**\n- The tool now provides detailed guidance including:\n - Exact directory searched and filename expected\n - Maven commands to generate dependency files\n - Instructions to ensure you're in a directory with pom.xml\n\n**\"Empty or invalid output\"**\n- Enhanced error messages now include:\n - Specific error details (encoding, permissions, empty files)\n - Validation of file content and format\n - Suggestions for fixing common parsing issues\n\n**\"Browser doesn't display the diagram\"**\n- Ensure you're opening the HTML file in a modern browser\n- Check browser console for JavaScript errors\n- Try a different browser (Chrome, Firefox, Safari)\n\n**\"Permission denied errors\"**\n- Improved diagnostics for:\n - Directory read/write permissions\n - File access issues\n - Output directory creation problems\n\n### Getting Help\n\n- Check the [examples](examples/) directory for working samples\n- Review the [issues](https://github.com/dyka3773/mvn-tree-visualizer/issues) page\n- Create a new issue with your Maven dependency file sample\n\n## Contributing\n\nContributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request.\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple command line tool to visualize the dependency tree of a Maven project in a graphical format.",
"version": "1.6.0",
"project_urls": {
"source": "https://github.com/dyka3773/mvn-tree-visualizer"
},
"split_keywords": [
"cli",
" command-line",
" dependency",
" graph",
" maven",
" mermaid",
" tool",
" tree",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8079e6f893dfd2a750fa4c3fa9c2c350910191cd9b26ecc62bcea60efa50ad75",
"md5": "f96834a17e4dba76776a7888b5b941a9",
"sha256": "00fae42d7f2a30a6bb2f03068630ad7a927e35aab009bf4342ac61b36caa5d7a"
},
"downloads": -1,
"filename": "mvn_tree_visualizer-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f96834a17e4dba76776a7888b5b941a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 19598,
"upload_time": "2025-07-24T16:48:25",
"upload_time_iso_8601": "2025-07-24T16:48:25.866836Z",
"url": "https://files.pythonhosted.org/packages/80/79/e6f893dfd2a750fa4c3fa9c2c350910191cd9b26ecc62bcea60efa50ad75/mvn_tree_visualizer-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "71aa901889b49c09e950efd9b014be996a37361a2589c286ffd528234de51a14",
"md5": "5876625394974c60c04ae9969680b9ea",
"sha256": "7532edf6d0c2ee3a6916b8a78247cc05836f7c8c8b71e343c104cbd52573977c"
},
"downloads": -1,
"filename": "mvn_tree_visualizer-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "5876625394974c60c04ae9969680b9ea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 85372,
"upload_time": "2025-07-24T16:48:26",
"upload_time_iso_8601": "2025-07-24T16:48:26.625896Z",
"url": "https://files.pythonhosted.org/packages/71/aa/901889b49c09e950efd9b014be996a37361a2589c286ffd528234de51a14/mvn_tree_visualizer-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 16:48:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dyka3773",
"github_project": "mvn-tree-visualizer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mvn-tree-visualizer"
}
JSON
