pydeps

3.0.2 · active · verified Thu Apr 16

pydeps is a Python library and command-line tool for visualizing module dependencies within Python projects. It analyzes import statements to build a dependency graph and can output it in various formats (e.g., SVG, PNG) using Graphviz. The current version is 3.0.2, and it follows an active release cadence, often updating for Python compatibility or bug fixes.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'dot'
```
cause The Graphviz `dot` command, essential for rendering graphs, is not found in the system's PATH.

fix Install Graphviz on your system and ensure its executables are added to your PATH environment variable. Verify by running `dot -V`.
```
Error running pydeps: ... output format 'svg' needs graphviz, which is not installed or not in the PATH
```
cause Similar to the 'dot' error, pydeps cannot find the Graphviz tool to generate the requested output format.

fix Install Graphviz and ensure the `dot` command is available in your system's PATH. Restart your terminal or IDE if necessary after installation.
```
TypeError: 'Config' object does not support item assignment (when using --externals)
```
cause This specific error might occur in certain configurations or older versions when trying to modify the configuration object in an unsupported way, possibly related to `--externals` processing.

fix Ensure you are using a recent version of pydeps (3.0.2 or newer). If the issue persists, try running without `--externals` or consult the GitHub issues for specific workarounds related to your pydeps version and configuration.
```
ValueError: bad marshal data (unknown type code)
```
cause This error often indicates an issue with compiled Python bytecode files (`.pyc` files) that are corrupted or from an incompatible Python version, which pydeps might be trying to analyze.

fix Try cleaning your Python environment by removing `__pycache__` directories and `.pyc` files (`find . -name '__pycache__' -exec rm -rf {} +; find . -name '*.pyc' -delete`) and then re-running pydeps.

Warnings

breaking pydeps v3.0.0 and later require Python 3.10+. Version 2.0.0 required Python 3.8+.
Fix: Upgrade your Python environment to 3.10 or newer, or pin pydeps to a compatible older version (e.g., `pydeps<3.0.0` for Python 3.8/3.9).
breaking The `--show-cycles` option is deprecated since v3.0.0; import cycles are now always shown by default.
Fix: Remove the `--show-cycles` flag from your commands or configuration files. Cycles will be displayed automatically.
gotcha Graphviz must be installed separately and its `dot` command must be accessible in your system's PATH for pydeps to generate visual graphs (SVG, PNG).
Fix: Install Graphviz according to your operating system's instructions (e.g., `sudo apt install graphviz` on Linux, `brew install graphviz` on macOS, `choco install graphviz` on Windows). Verify installation by running `dot -V` in your terminal.
gotcha When using command-line options that accept multiple arguments (e.g., `-x` for excludes) *before* the target filename/package, you must separate them with `--`.
Fix: Use `pydeps -x os sys -- mypackage` instead of `pydeps -x os sys mypackage` to ensure `mypackage` is correctly parsed as the target.

Install

pip install pydeps Install pydeps
sudo apt install graphviz # On Debian/Ubuntu Install Graphviz (required)
brew install graphviz # On macOS Install Graphviz (macOS)
choco install graphviz # On Windows with Chocolatey Install Graphviz (Windows)

Imports

cli.main
```
from pydeps import cli
```
Primary programmatic entry point to mimic command-line usage.
externals
```
from pydeps.pydeps import externals
```
Used for programmatic extraction of external dependencies.
depgraph.DepGraph
```
from pydeps.depgraph import DepGraph
```
For building custom dependency graph analysis.

Quickstart

This quickstart demonstrates how to use pydeps from the command line (via subprocess) to visualize module dependencies. It creates a temporary Python package, runs pydeps on it, and prints the raw dependency list. To generate a visual graph (e.g., SVG), ensure Graphviz is installed and remove the `--nodot --no-output` flags, using `-o filename.svg` instead.

import os
import subprocess
import tempfile

def create_sample_project(path):
    os.makedirs(os.path.join(path, 'mypackage'), exist_ok=True)
    with open(os.path.join(path, 'mypackage', '__init__.py'), 'w') as f:
        f.write('')
    with open(os.path.join(path, 'mypackage', 'module_a.py'), 'w') as f:
        f.write('import os\nfrom . import module_b\ndef func_a():\n    print("Hello from A")')
    with open(os.path.join(path, 'mypackage', 'module_b.py'), 'w') as f:
        f.write('import sys\ndef func_b():\n    print("Hello from B")')

with tempfile.TemporaryDirectory() as tmpdir:
    create_sample_project(tmpdir)
    current_dir = os.getcwd()
    os.chdir(tmpdir)
    
    try:
        # Run pydeps as a subprocess to generate the dependency graph
        # Output to stdout and catch errors
        result = subprocess.run(
            ['pydeps', 'mypackage', '--nodot', '--no-output', '--show-deps'],
            capture_output=True, text=True, check=True
        )
        print("\n--- pydeps output (dependencies) ---")
        print(result.stdout)
        
        # To generate an SVG file, you'd typically run:
        # subprocess.run(['pydeps', 'mypackage', '-o', 'mypackage.svg'], check=True)
        # print(f"Dependency graph saved to {os.path.join(tmpdir, 'mypackage.svg')}")
        
    except FileNotFoundError:
        print("Error: 'pydeps' command not found. Ensure pydeps is installed and in PATH.")
        print("Error: 'dot' command (from Graphviz) might also be missing. Install Graphviz.")
    except subprocess.CalledProcessError as e:
        print(f"Error running pydeps: {e}")
        print(f"Stdout: {e.stdout}")
        print(f"Stderr: {e.stderr}")
    finally:
        os.chdir(current_dir)

view raw JSON →