✨ Why Python Package Visualizer?

Every Python developer has been there: pip list --outdated is noisy, requirements.txt gets out of sync, CVEs go unnoticed, unused packages bloat your environment, and dependency conflicts break your builds. This extension fixes all of that — visually.

• 🎯 See everything at a glance — dashboard, dependency graph, health score
• 🔒 Catch vulnerabilities early — CVE badges pulled from PyPI advisory DB
• 🧹 Clean up bloat — find packages that aren't imported anywhere
• ⚡ Update safely — Safe Mode blocks major-version jumps
• 📸 Rollback confidently — environment snapshots & update history

🎬 Demo

🚀 Quick Start

1. Open a Python project containing requirements.txt, pyproject.toml, or setup.py
   (monorepos are supported — e.g. backend/requirements.txt is discovered automatically)
2. Click the 📦 icon in the Activity Bar (left side)
3. Click ▶ Open Package Visualizer in the sidebar

If no dependency file is found, the panel shows an in-app empty state with a Select requirements file button — no IDE popup required.

🎯 Core Features

📋 Package Management

🧹 Unused Packages & Cursor AI Review

The Unused Packages tab lists dependencies declared in your manifest files that were not found in static Python import scans. Each row shows a confidence score (high / medium / low) based on signals such as transitive deps, dev groups, popularity, and partial name matches — so you can prioritize cleanup safely.

Cursor AI workflow (opt-in)

1. Open the visualizer and scan the workspace.
2. Go to the Unused Packages tab.
3. Click ✨ Analyze with Cursor AI (visible only in Cursor when AI analysis is enabled).
4. The extension searches the workspace for non-import references (configs, Dockerfiles, CI, scripts) and sends the unused list to Cursor Agent with confidence scores and reference hits.
5. Review the Agent verdicts (USED / UNUSED / UNCERTAIN) in the chat.
6. Back in the tab, click Apply removals… to open a checklist — high-confidence packages without config references are pre-selected; confirm to remove them from dependency files.

Privacy & control: analysis starts only when you click the button. No background AI calls. In VS Code (without Cursor Agent), the AI button is hidden; one-click Remove still works.

Settings (Python Package Visualizer):

🧠 Code Intelligence

Import Annotations — see package status right above each import line:

✅ requests v2.31.0      ↗ PyPI
import requests

⚠️ flask 2.0.1 → 3.0.3   ↑ Update    ↗ PyPI
from flask import Flask

Function Metrics — quality insights above every function:

# 📊 18 lines · 🔗 2 refs · ⚡ Low
def load_resume_text(pdf_path: str) -> str:
    """Extract text from PDF."""
    ...

# 📊 25 lines · 🔗 0 refs · ⚡ Moderate
# ⚠️ Missing type hints (3/3 untyped, no return type) — Click to fix
# ⚠️ Missing docstring — Click to add
def create_qa_chain(resume_text):
    ...

Smart Hover Cards — hover any imported symbol for a compact card:

📦 langchain · v1.2.15 · MIT
Building applications with LLMs through composability
🟢 Up to date · 🐍 >=3.10 · 📅 2 days ago
↑ Update · 🔍 Inspect · PyPI ↗

API Cost Hints — hover on LLM clients like ChatGroq, ChatOpenAI:

🤖 ChatGroq
Provider: Groq
💰 Pricing: Free tier · ~$0.05-0.10/1M tokens
⚡ Speed: Very fast (~300 tok/s)

🔒 Security & Compliance

📊 Visualization & Analytics

• Dashboard — health score, security stats, maintainer activity
• Dependency Graph — interactive D3.js tree with collapsible nodes
• Performance — ranks packages by install time (Fast/Moderate/Slow)
• History — timeline of all updates, installs, rollbacks
• Licenses — packages grouped by license with risk badges
• Snapshots — save and restore your entire environment

🛠 Power Tools

Accessible from the Export dropdown in the main panel:

• 📤 Export Report — Markdown or JSON snapshot of your dependencies
• 📦 Generate requirements.txt — auto-scan imports and create requirements.txt
• 🐧 Setup Scripts — generate Bash / PowerShell / Markdown setup scripts for onboarding
• ⚡ Migrate to uv — convert requirements.txt → modern pyproject.toml
• 🎭 Migrate to Poetry — convert to Poetry format

⚙️ Settings Panel

Every code insight is toggleable from the sidebar — no need to dig into VS Code settings.json.

General Settings

• 🔘 Import annotations (inline package badges)
• 🔘 Show hover info
• 🔘 Auto-check on open
• 🔘 Notify on outdated packages
• 📋 Update check schedule (Off / Daily / Weekly / Monthly)
• 🌐 UI language (English / Italiano)

Code Insights

• 🔘 Function metrics (lines, references, complexity)
• 🔘 Method call hover (package info + API cost)
• 🔘 Complexity warnings
• 🔘 Type hint coverage warnings
• 🔘 Docstring warnings

⌨️ Keyboard Shortcuts

Inside the Package Visualizer panel:

📋 Full release history: CHANGELOG.md

🎯 What's New in v3.2.1

• 🔧 Reliable package removal — UTF-16 requirements.txt support, PEP 508 direct URLs (pkg @ git+…), and fallback search across included -r files
• 🔗 Bulk align fix — sync now searches included requirement files, handles pip hash/continuation lines, and preserves environment markers

🎯 What's New in v3.2.0

• 🏷️ Independent community release — published under FaberVi (separate from the original marketplace extension)
• 🛠️ Tools menu — export, generate, and uv/Poetry migration in one dropdown
• ⚡ uv migration (manual/automatic) — optional cleanup of legacy requirements*.txt files
• 📦 Updated branding — extension icon aligned with the in-app package tile

v3.1.x highlights

• 🔍 Robust dependency file discovery — scans subfolders (e.g. backend/requirements.txt in monorepos)
• 🔗 requirements-dev.txt support — follows -r requirements.txt includes and merges packages correctly
• 🖥️ In-panel empty state — manual file selection from the visualizer UI (EN/IT), no IDE notification popup
• 🤖 Cursor AI review — optional Agent analysis for unused packages (Auto model, codebase search)
• 🧹 Smarter unused detection — dynamic imports, config/Dockerfile references, reduced false positives
• ⚠️ Conflict-aware updates — blocked updates on pip check conflicts, revert & force-update actions
• 🐍 Global Python guard — confirmation before install/update when not using a workspace venv
• 🇮🇹 Italian localization — webview, sidebar, tour, and key VS Code messages
• 🧩 Cursor compatibility — engine ^1.105.0, installable in Cursor via VSIX

v3.0.x highlights

• 📝 Import annotations, function metrics, quick-fix CodeLens, smart hover cards
• 📦 Environment snapshots, Safe Mode, uv/Poetry migration, setup script generator

📋 Supported Project Types

The extension automatically detects and parses dependency files recursively in the workspace (up to 6 levels deep), skipping node_modules, .git, venv, etc.

Virtual environments are auto-detected from: .venv/, venv/, env/, .env/ at the workspace root and common subfolders (backend/, api/, server/, python/).

You can also pick a requirements file manually from the dashboard or the in-panel empty state.

🔧 Installation

Extension ID: FaberVi.python-package-visualizer-community
This is a community fork, independent from Elanchezhiyan-P.python-package-visualizer.
If you had the original installed, disable or uninstall it to avoid duplicate sidebars.

From VS Code Marketplace

1. Open VS Code or Cursor
2. Go to Extensions (Ctrl+Shift+X)
3. Search Python Package Visualizer (Community)
4. Install the extension published by FaberVi

From VSIX (VS Code or Cursor)

# VS Code
code --install-extension python-package-visualizer-community-3.2.1.vsix

# Cursor
cursor --install-extension python-package-visualizer-community-3.2.1.vsix --force

Or run the full pipeline from the project root:

.\scripts\build-all.ps1

🏗️ Development

Prerequisites

• Node.js v18+
• npm (bundled with Node.js)
• VS Code or Cursor ^1.105.0

Setup

# Clone the repository (fork with active development)
git clone https://github.com/FaberVi/python-package-visualizer.git
cd python-package-visualizer

# Install dependencies
npm install

Upstream original project: Elanchezhiyan-P/python-package-visualizer

Build & Install (One Command)

The project includes an automated build pipeline that runs all steps in sequence:

.\scripts\build-all.ps1

This single script performs 5 steps automatically:

The pipeline stops on first failure and reports which step failed with the exit code. After install, reload manually with Ctrl+Shift+P → Developer: Reload Window.

Individual npm Scripts

For granular operations, you can run each step individually:

Coverage policy (unit-test scope): lines/statements ≥ 79%, branches ≥ 72%, functions ≥ 81% on modules exercised by test:unit. Full-repo line coverage including webview/commands remains lower by design; patch gate (node scripts/check-patch-coverage.mjs) enforces 70% on newly added src/ files that are unit-tested. Local full check: .\scripts\diff-coverage.ps1.

Typical Development Workflow

# Option A — Full automated pipeline (build + install + reload)
.\scripts\build-all.ps1

# Option B — Watch mode for rapid iteration
npm run watch
# Press F5 in VS Code to launch the Extension Development Host
# Make changes → watcher rebuilds → reload dev host (Ctrl+Shift+P → "Reload Window")

Project Structure

python-package-visualizer/
├── src/                          # TypeScript source (compiled by esbuild)
│   ├── extension.ts              # Extension entry point (activate/deactivate)
│   ├── commands/
│   │   ├── commandController.ts  # Central command dispatcher
│   │   └── handlers/
│   │       ├── visualizerHandler.ts   # Core scan + update orchestration
│   │       ├── visualizer/
│   │       │   └── displayCompiler.ts # Payload building (shared by panel + sidebar)
│   │       ├── packageInstaller.ts    # pip install/update/rollback
│   │       ├── requirementsHandler.ts # Requirements file operations
│   │       ├── reportExporter.ts      # Markdown/JSON export
│   │       ├── snapshotHandler.ts     # Environment snapshots
│   │       ├── migrationHandler.ts    # uv/Poetry migration
│   │       └── utilityHandler.ts      # Misc utilities
│   ├── modules/
│   │   ├── importScanner.ts      # Facade — delegates to import/ sub-modules
│   │   ├── import/
│   │   │   ├── scanner.ts        # Python file scanning + import extraction
│   │   │   ├── confidence.ts     # Unused package confidence scoring
│   │   │   └── maps.ts           # stdlib, import-to-package mappings
│   │   ├── packageScanner.ts     # Requirements/pyproject/setup.py parser
│   │   ├── depFileDiscovery.ts   # Recursive monorepo dep-file search
│   │   ├── parsers/              # Format-specific parsers
│   │   ├── requirementsSync.ts   # Align/remove version lines in requirements
│   │   ├── requirementsGenerator.ts
│   │   ├── migrationHelper.ts
│   │   └── setupScriptGenerator.ts
│   ├── services/
│   │   ├── versionChecker.ts     # PyPI API queries
│   │   ├── versionHistoryCache.ts # Local JSON history store
│   │   └── cursorAiService.ts    # Cursor Agent integration (unused review)
│   ├── providers/                # CodeLens, Hover, and Diagnostics providers
│   ├── ui/
│   │   ├── webviewPanel.ts       # Main webview panel manager
│   │   ├── sidebarProvider.ts    # Activity bar sidebar
│   │   └── statusBarManager.ts   # Status bar item
│   ├── data/                     # Static data (alternatives, API costs)
│   └── utils/                    # Logger, helpers
├── media/
│   ├── webview/
│   │   ├── index.html            # Main webview HTML template
│   │   ├── main.js               # Webview entry point
│   │   ├── js/
│   │   │   ├── state.js          # Global state management
│   │   │   ├── utils.js          # Shared utilities (esc, formatters)
│   │   │   ├── i18n.js           # i18n engine + static translations
│   │   │   ├── i18n/             # Language packs (en.js, it.js)
│   │   │   ├── filters.js        # Search, sort, filter logic
│   │   │   ├── table.js          # Package list table renderer
│   │   │   ├── tabs.js           # Tab router + shared tab utilities
│   │   │   ├── tabs/             # Per-tab renderers
│   │   │   │   ├── dashboard.js
│   │   │   │   ├── unused.js
│   │   │   │   ├── licenses.js
│   │   │   │   ├── performance.js
│   │   │   │   ├── history.js
│   │   │   │   └── snapshots.js
│   │   │   ├── detail.js         # Package detail side panel
│   │   │   ├── graph.js          # D3.js dependency graph
│   │   │   ├── modal.js          # Modal dialogs
│   │   │   └── tour.js           # Guided tour
│   │   └── css/
│   │       ├── base.css          # CSS custom properties + reset
│   │       ├── layout.css        # Header, toolbar, stats bar
│   │       ├── components.css    # Buttons, badges, tags, banners
│   │       ├── components/       # Extracted component styles
│   │       │   ├── loader.css
│   │       │   ├── empty-state.css
│   │       │   ├── modal.css
│   │       │   ├── export-menu.css
│   │       │   └── tour.css
│   │       ├── list-view.css     # Package table styles
│   │       ├── detail-view.css   # Detail panel styles
│   │       ├── graph-view.css    # Graph visualization styles
│   │       ├── tabs-view.css     # Tab bar controls
│   │       └── tabs/             # Per-tab styles
│   │           ├── dashboard.css
│   │           ├── unused.css
│   │           ├── licenses.css
│   │           ├── performance.css
│   │           ├── history.css
│   │           └── snapshots.css
│   └── sidebar/
│       ├── welcome.html          # Sidebar HTML template
│       └── welcome.js            # Sidebar settings + event handlers
├── test/                         # Extension integration tests
├── scripts/
│   └── build-all.ps1             # Automated build pipeline (lint → type-check → build → package → install)
├── dist/                         # Compiled output (gitignored)
├── esbuild.js                    # Build script configuration
├── tsconfig.json                 # TypeScript compiler config
├── tsconfig.test.json            # Test-specific TS config
├── package.json                  # Extension manifest + npm scripts
└── .vscodeignore                 # Files excluded from VSIX package

🤝 Contributing

Issues and pull requests are welcome!

• 🐛 Bug reports & features: FaberVi/python-package-visualizer — Issues
• 📝 Changelog: CHANGELOG.md
• 🔼 Upstream: Elanchezhiyan-P/python-package-visualizer

Before submitting a PR, run .\scripts\build-all.ps1 and make sure all 5 steps pass cleanly.

👥 Credits

📜 License

MIT © Vincenzo Fabiano (fork maintainer), Elanchezhiyan P (original author), and contributors. See LICENSE for details.

📸 Screenshots & GIFs

All media is stored in media/screenshots/. Current assets:

Regenerate all README screenshots (uses the real webview UI + demo fixture data, captured via headless Chrome/Edge):

npm run screenshots
# or: python scripts/screenshots/capture.py

Requires Node.js, Python 3 + Pillow, and Chrome or Edge installed locally.