{"id":7556,"library":"pydeps","title":"pydeps","description":"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.","status":"active","version":"3.0.2","language":"en","source_language":"en","source_url":"https://github.com/thebjorn/pydeps","tags":["dependency analysis","visualization","developer tool","graphviz","static analysis"],"install":[{"cmd":"pip install pydeps","lang":"bash","label":"Install pydeps"},{"cmd":"sudo apt install graphviz # On Debian/Ubuntu","lang":"bash","label":"Install Graphviz (required)"},{"cmd":"brew install graphviz # On macOS","lang":"bash","label":"Install Graphviz (macOS)"},{"cmd":"choco install graphviz # On Windows with Chocolatey","lang":"bash","label":"Install Graphviz (Windows)"}],"dependencies":[{"reason":"Required for rendering the dependency graphs (e.g., to SVG/PNG). The `dot` command must be available in your system's PATH.","package":"Graphviz","optional":false}],"imports":[{"note":"Primary programmatic entry point to mimic command-line usage.","symbol":"cli.main","correct":"from pydeps import cli"},{"note":"Used for programmatic extraction of external dependencies.","symbol":"externals","correct":"from pydeps.pydeps import externals"},{"note":"For building custom dependency graph analysis.","symbol":"depgraph.DepGraph","correct":"from pydeps.depgraph import DepGraph"}],"quickstart":{"code":"import os\nimport subprocess\nimport tempfile\n\ndef create_sample_project(path):\n    os.makedirs(os.path.join(path, 'mypackage'), exist_ok=True)\n    with open(os.path.join(path, 'mypackage', '__init__.py'), 'w') as f:\n        f.write('')\n    with open(os.path.join(path, 'mypackage', 'module_a.py'), 'w') as f:\n        f.write('import os\\nfrom . import module_b\\ndef func_a():\\n    print(\"Hello from A\")')\n    with open(os.path.join(path, 'mypackage', 'module_b.py'), 'w') as f:\n        f.write('import sys\\ndef func_b():\\n    print(\"Hello from B\")')\n\nwith tempfile.TemporaryDirectory() as tmpdir:\n    create_sample_project(tmpdir)\n    current_dir = os.getcwd()\n    os.chdir(tmpdir)\n    \n    try:\n        # Run pydeps as a subprocess to generate the dependency graph\n        # Output to stdout and catch errors\n        result = subprocess.run(\n            ['pydeps', 'mypackage', '--nodot', '--no-output', '--show-deps'],\n            capture_output=True, text=True, check=True\n        )\n        print(\"\\n--- pydeps output (dependencies) ---\")\n        print(result.stdout)\n        \n        # To generate an SVG file, you'd typically run:\n        # subprocess.run(['pydeps', 'mypackage', '-o', 'mypackage.svg'], check=True)\n        # print(f\"Dependency graph saved to {os.path.join(tmpdir, 'mypackage.svg')}\")\n        \n    except FileNotFoundError:\n        print(\"Error: 'pydeps' command not found. Ensure pydeps is installed and in PATH.\")\n        print(\"Error: 'dot' command (from Graphviz) might also be missing. Install Graphviz.\")\n    except subprocess.CalledProcessError as e:\n        print(f\"Error running pydeps: {e}\")\n        print(f\"Stdout: {e.stdout}\")\n        print(f\"Stderr: {e.stderr}\")\n    finally:\n        os.chdir(current_dir)\n","lang":"python","description":"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."},"warnings":[{"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).","message":"pydeps v3.0.0 and later require Python 3.10+. Version 2.0.0 required Python 3.8+.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Remove the `--show-cycles` flag from your commands or configuration files. Cycles will be displayed automatically.","message":"The `--show-cycles` option is deprecated since v3.0.0; import cycles are now always shown by default.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `pydeps -x os sys -- mypackage` instead of `pydeps -x os sys mypackage` to ensure `mypackage` is correctly parsed as the target.","message":"When using command-line options that accept multiple arguments (e.g., `-x` for excludes) *before* the target filename/package, you must separate them with `--`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install Graphviz on your system and ensure its executables are added to your PATH environment variable. Verify by running `dot -V`.","cause":"The Graphviz `dot` command, essential for rendering graphs, is not found in the system's PATH.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'dot'"},{"fix":"Install Graphviz and ensure the `dot` command is available in your system's PATH. Restart your terminal or IDE if necessary after installation.","cause":"Similar to the 'dot' error, pydeps cannot find the Graphviz tool to generate the requested output format.","error":"Error running pydeps: ... output format 'svg' needs graphviz, which is not installed or not in the PATH"},{"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.","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.","error":"TypeError: 'Config' object does not support item assignment (when using --externals)"},{"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.","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.","error":"ValueError: bad marshal data (unknown type code)"}]}