project-mapper

Understand what a Python file depends on — without running the code.

project-mapper is a static analysis tool for Python. Point it at an entry-point file and it maps every local file that entry point reaches, classifies its imports, detects environment-variable names, and produces a polished, self-contained HTML report.

It never executes the code it analyzes. It makes no network calls. It sends no telemetry. Everything runs locally.

project-mapper main.py

Project Mapper

Analyzing
  /Users/yash/projects/example/main.py

Scanning dependencies...

✓ Entry point parsed
✓ 8 Python files analyzed
✓ 13 local dependencies found
✓ 5 third-party imports found
✓ 11 standard-library imports found
✓ 4 environment variables found

Generating HTML report...

✓ Report generated
  ./project-mapper-report.html

How it works

Entry point
    ↓
AST analysis          (Python's ast module — never executed)
    ↓
Local dependency resolution
    ↓
Recursive traversal
    ↓
HTML report

Installation

pip install project-mapper

Or from source:

git clone https://github.com/Yashjindal11/projectmap
cd projectmap
pip install -e ".[dev]"

Requires Python 3.10+.

Naming: the PyPI distribution and CLI command are both project-mapper, and the Python import package is project_map.

Usage

CLI

project-mapper main.py                      # writes ./project-mapper-report.html
project-mapper ./main.py --output map.html  # custom output
project-mapper main.py -o map.html --open   # open in default browser
project-mapper main.py --verbose            # extra diagnostics
project-mapper --help

Python API

from project_map import analyze
from project_map.report import generate_html

result = analyze("main.py")
generate_html(result, "project-mapper-report.html")

print(result.third_party_imports)     # ['pandas', 'requests']
print(result.environment_variables)   # ['API_KEY', 'DATABASE_URL']

Example

Given:

my-project/
├── main.py
├── config.py
├── services/
│   └── customer.py
└── utils/
    └── helpers.py

project-mapper main.py

The report shows the dependency structure:

main.py
├── config.py
└── services/customer.py
    └── utils/helpers.py

plus:

Third Party
    requests

Standard Library
    os
    logging

Environment Variables
    API_KEY

Features

• Static Python analysis — parses the AST; never runs your code.
• Recursive local dependency mapping — follows reachable local imports.
• Import classification — local, standard library, third-party, unresolved.
• Environment-variable detection — reports names only, never values.
• Standalone HTML report — inline CSS/SVG, works offline via file://.
• CLI and Python API.
• No code execution. No network. No telemetry.

Privacy & safety

• The analyzed code is treated as untrusted input and is never imported, executed, or evaluated (no eval, no exec, no subprocesses).
• .env files are never read. Only environment-variable names that appear literally in the source are reported — never their values.
• No network requests are made by the analyzer.

Limitations

Static analysis cannot perfectly resolve every import. In particular:

• Dynamic imports such as importlib.import_module(name) or __import__(name) cannot be followed.
• Third-party import names are not guaranteed PyPI package names — for example, import cv2 corresponds to the PyPI package opencv-python. They are labelled as third-party imports, not package names.
• V1 targets common, predictable project layouts. Exotic import machinery, namespace packages, and sys.path manipulation may not resolve.

Where resolution is uncertain, the import is reported honestly as Unresolved rather than guessed.

License

MIT — see LICENSE.