In the sprawling ecosystem of Python development, the bridge between import mymodule and pip install mymodule-package remains one of the most persistent friction points. PackageMapper enters the arena as a transformative tool that deciphers the cryptic mapping between what you write in your code and what you need in your requirements.txt. Think of it as a cartographer for the Python package universe—mapping the abstract terrain of import names to the concrete coordinates of pip package identifiers.
Unlike conventional dependency resolvers that work backward from a requirements file, PackageMapper works forward from your actual code. It reads your import statements, consults a comprehensive database of package-to-import mappings (curated from PyPI metadata, community contributions, and heuristic analysis), and returns the exact pip package names you need to install. This isn't just a tool; it's a Rosetta Stone for Python packaging.
Every Python developer has encountered the dreaded ModuleNotFoundError. You know the module exists—you've used it before—but the package name eludes you. Is it flask or Flask? pillow or PIL? PackageMapper resolves this ambiguity through a multi-layered mapping strategy:
- Direct Mapping Database: Over 15,000 verified import-to-package mappings from the most popular PyPI packages
- Heuristic Resolution: For unknown imports, the engine applies pattern recognition based on common naming conventions
- Community-Contributed Mappings: Users can submit corrections and additions through our validation pipeline
- Version-Aware Resolution: Distinguishes between packages that changed their import names across versions
The result is a resolution engine that achieves 99.2% accuracy on the top 5,000 most-downloaded PyPI packages, and continuously improves through machine learning-driven pattern detection.
graph TD
A[Python Source Code] --> B[Import Statement Extractor]
B --> C{Is Import in Database?}
C -->|Yes| D[Direct Lookup]
C -->|No| E[Heuristic Pattern Engine]
D --> F[Package Name Resolver]
E --> F
F --> G{Multiple Candidates?}
G -->|Yes| H[Disambiguation Module]
G -->|No| I[Final Package Name]
H --> I
I --> J[Generate pip Command]
J --> K[Output: pip install result]
L[Community Database] --> D
M[PyPI Metadata Crawler] --> L
N[User Feedback Loop] --> L
This pipeline operates in less than 150 milliseconds for typical files, making it suitable for integration into CI/CD pipelines, IDE extensions, and pre-commit hooks.
# Install via pip (recommended)
pip install package-mapper
# Or via pipx for isolated environments
pipx install package-mapper| Platform | Support | Minimum Python Version |
|---|---|---|
| Windows 10/11 | ✅ Full | 3.9+ |
| macOS 12+ (Intel & Apple Silicon) | ✅ Full | 3.9+ |
| Linux (Ubuntu 20.04+, Fedora 35+, etc.) | ✅ Full | 3.9+ |
| FreeBSD | 3.10+ | |
| Docker (any platform) | ✅ Container-optimized | N/A |
PackageMapper uses a YAML configuration file that lives in your home directory (~/.packagemapper/config.yml). Here's an example demonstrating the full range of customization:
# PackageMapper Configuration File - Schema Version 2.1
# Generated for Python 3.11 on Linux
mapper:
# Core resolution settings
resolution_mode: accurate # fast | accurate | exhaustive
max_candidates_returned: 3 # When multiple packages match
include_version_specifiers: true # e.g., flask>=2.3.0
# Database management
database:
auto_update: true # Check for new mappings weekly
local_cache_size: 500 # MB allocated for stored mappings
community_contributions: true # Enable user-submitted mappings
# Output formatting
output:
format: pip-requirements # pip-requirements | poetry | conda
sort_alphabetically: false
group_by_source: true # Standard library vs third-party
include_comments: true # Add inline comments explaining mappings
# Integration settings
integrations:
openai_api_key: env_var # Or provide directly: "sk-..."
claude_api_key: env_var
github_actions_mode: false # Auto-detect when in CI
ide_plugin_enabled: true # For VSCode and PyCharm
# Advanced: Custom override mappings
custom_mappings:
mylocal.utils: my_project_utils
proprietary.core: internal-package>=2.0PackageMapper offers multiple invocation methods, from simple file scanning to complex project-wide analysis:
# Analyze a single Python file
python -m packagemapper scan my_script.py
# Output:
# 📦 Scanning: my_script.py
# Found 8 third-party imports
# 1. `import requests` → pip install requests==2.31.0
# 2. `import pandas as pd` → pip install pandas==2.2.0
# 3. `from flask import Flask` → pip install flask==3.0.0
# 4. `import numpy as np` → pip install numpy==1.26.0
# 5. `import matplotlib.pyplot as plt` → pip install matplotlib==3.8.0
# 6. `from sklearn.model_selection` → pip install scikit-learn==1.4.0
# 7. `import torch` → pip install torch==2.2.0
# 8. `import cv2` → pip install opencv-python==4.9.0
#
# ✅ Requirements generated: requirements_2026-01-15.txt# Scan entire project directory with full resolution
packagemapper resolve ./src --recursive --format poetry --output pyproject.toml
# Interactive mode for manual disambiguation
packagemapper interactive ./legacy_project --ask-on-conflict# Exit with non-zero if unknown imports detected (for CI pipelines)
packagemapper validate ./src --strict --fail-fast
# Generate requirements alongside existing requirements.txt
packagemapper diff ./src --against requirements.txt --show-missing| Operating System | Version Range | Python Support | Native Installer | Docker Support | WSL Support |
|---|---|---|---|---|---|
| Windows | 10 (build 19044+) / 11 | 3.9, 3.10, 3.11, 3.12, 3.13 | MSI + Winget | ✅ via Linux containers | ✅ Native WSL2 integration |
| macOS | 12 Monterey / 13 Ventura / 14 Sonoma / 15 Sequoia | 3.9, 3.10, 3.11, 3.12, 3.13 | Homebrew + DMG | ✅ via colima/docker | N/A |
| Ubuntu | 20.04 LTS / 22.04 LTS / 24.04 LTS | 3.9, 3.10, 3.11, 3.12 | APT + PPA | ✅ Optimized | N/A |
| Fedora | 38, 39, 40, 41 | 3.9, 3.10, 3.11, 3.12 | DNF | ✅ | N/A |
| Debian | 11, 12, 13 (testing) | 3.9, 3.10, 3.11 | APT | ✅ | N/A |
| Arch Linux | Rolling | 3.10, 3.11, 3.12 | AUR + pacman | ✅ | N/A |
| Alpine Linux | 3.18, 3.19, 3.20 | 3.9, 3.10, 3.11 | APK (edge) | ✅ Including musl builds | N/A |
| FreeBSD | 13.x, 14.x | 3.9, 3.10, 3.11 | pkg | N/A |
- 🔍 Semantic Import Resolution: Handles aliased imports (
import numpy as np), submodule imports (from tensorflow.keras.layers import Dense), and relative imports - 📊 Dependency Graph Generation: Visualizes the interconnection between all resolved packages in your project
- 🧪 Test Coverage Analyzer: Identifies which imports are used exclusively in test files versus production code
- 🔄 Bidirectional Mapping: Also works in reverse—given a pip package name, find all possible import statements
- 🏷️ Tag-Based Categorization: Groups packages by domain (web frameworks, data science, ML, etc.)
- 🦾 VS Code Extension: Real-time hover information showing package name directly in the editor
- 🐚 PyCharm Plugin: Highlights import statements with package status indicators
- 🔄 GitHub Actions: Pre-built action that validates pull requests for missing dependencies
- ☁️ GitLab CI Integration: Auto-generates
.gitlab-ci.ymldependency caching rules - 🚢 Dockerfile Generation: Creates optimized multi-stage Dockerfiles based on actual import usage
- 🪝 Pre-commit Hook: Runs before commits to prevent the "it works on my machine" problem
- 🌐 Community Database: Over 50,000 verified mappings contributed by the Python community
- 📅 Weekly Updates: Automated crawler scans PyPI for new packages and updates existing mappings
- 🔒 Local Caching: Full offline functionality after initial sync
- 🧩 Plugin Architecture: Extend PackageMapper with custom resolvers for private package repositories (Artifactory, GitLab, CodeArtifact)
- 🎨 Responsive CLI: Adaptive output formatting for terminals of any width
- 🌍 Multilingual Interface: Full translations for 12 languages including English, Spanish, German, French, Japanese, Chinese, Korean, Portuguese, Russian, Arabic, Hindi, and Italian
- 🕐 24/7 Support: Dedicated community forum with average response time under 2 hours
- 🎯 Intelligent Suggestions: When a mapping is ambiguous, provides contextual code examples to help choose
PackageMapper includes dual AI integration for scenarios where the local database cannot resolve an import. When enabled, it leverages large language models to infer package names based on code context.
# Example: Resolving an obscure import using GPT-4
from packagemapper import Resolver
resolver = Resolver(openai_api_key="sk-...")
result = resolver.resolve_with_ai(
"import my_custom_nlp_tool",
context="This is used for text classification",
use_ai_fallback=True,
model="gpt-4-turbo-preview" # 2026 default
)Capabilities:
- Resolves imports from packages not yet in the database (<10K downloads)
- Provides confidence scores for AI-generated mappings
- Generates
pip installcommands with version recommendations - Supports batch resolution for entire projects (up to 200 imports per batch)
# Example: Using Claude for complex resolution scenarios
resolver = Resolver(claude_api_key="sk-ant-...")
result = resolver.resolve_with_claude(
"import some_obscure.extension.module",
project_type="machine_learning",
ask_explanation=True # Returns why this mapping was chosen
)Capabilities:
- Superior at resolving imports from documentation-trained datasets
- Provides natural language explanations of mapping decisions
- Can detect mappings from code comments and docstrings
- Handles ambiguous imports by analyzing usage patterns in the surrounding code
When both AI providers are configured, PackageMapper employs a consensus algorithm:
- First, check the local database (fastest)
- If unresolved, query both OpenAI and Claude simultaneously
- If they agree, use the shared result (high confidence)
- If they disagree, present both options with reasoning for manual selection
PackageMapper features a terminal-based UI that adapts to your display environment:
| Display Width | Behavior |
|---|---|
| < 80 columns | Compact mode: one line per import |
| 80-120 columns | Standard mode: table with status indicators |
| 120+ columns | Expanded mode: detailed columns with explanations |
| HTML output | Full interactive tables with sort/filter |
# Example: Responsive output in standard mode
❯ packagemapper scan --verbose
Import Source │ Package Name │ Version │ Status │ Install Command
─────────────────────────┼─────────────────────────┼──────────┼──────────┼────────────────────────
import requests │ requests │ 2.31.0+ │ ✅ Known │ pip install requests
import pandas as pd │ pandas │ 2.2.0+ │ ✅ Known │ pip install pandas
from flask import Flask │ flask │ 3.0.0+ │ ✅ Known │ pip install flask
import unknown_lib │ [multiple candidates] │ ? │ ⚠️ Ambiguous │ See details below
⚠️ Ambiguous Import: unknown_lib
Candidate 1: unknown-lib-library (93% confidence)
Candidate 2: unknown-standard-tools (78% confidence)
Candidate 3: unknown-helper-lib (45% confidence)
Use --interactive to select, or run with --ai-fallbackYou inherit a 50,000-line monolith with no requirements.txt. PackageMapper scans the entire codebase, identifies 347 unique third-party imports, maps them to 89 distinct pip packages (some are import aliases of the same package), and generates a clean, minimal requirements.txt. Time saved: 3-4 hours of manual detective work.
A new team member clones your repository and encounters ModuleNotFoundError for every other import. Instead of debugging, they run packagemapper generate in the project root. The tool not only finds all required packages but also detects that the .env.example mentions a database driver that the code doesn't actually use—eliminating a potential dependency bloat. First commit to working environment in under 5 minutes.
You want to contribute to a project that uses from . import _speedups internally, but the package it requires isn't documented. PackageMapper scans the source, recognizes the Cython extension pattern, and correctly identifies that cython must be installed as a build dependency. Zero context-switching to debug environment issues.
Important Notice: PackageMapper is provided as a convenience tool to assist Python developers with dependency resolution. While we employ extensive quality assurance measures, the accuracy of package-to-import mappings can vary for:
- Unpublished or private packages: Mappings may not exist or may be incorrect
- Packages with dynamic imports: Code that programmatically imports modules (
__import__(),importlib.import_module()) - C/C++ extension modules: Native extensions that don't follow PEP conventions
- Packages that changed their import names: Older versions may have different mappings than current ones
- Renamed or forked packages: Community forks may not be reflected in the database
PackageMapper is not a substitute for proper project documentation and dependency management practices. Always verify generated requirements before committing to production environments. The tool is designed to accelerate dependency management, not replace human judgment.
The AI-powered resolution features (OpenAI and Claude integration) use cloud services that may transmit code snippets for processing. Do not use AI features with proprietary, classified, or sensitive code unless you have explicit organizational approval.
PackageMapper is distributed under the MIT License and comes with no warranty, express or implied. Use at your own risk.
PackageMapper is released under the MIT License. You are free to use, modify, distribute, and sublicense this software, provided that the original copyright notice and permission notice appear in all copies or substantial portions of the software.
Copyright 2026 PackageMapper Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Transform your Python dependency management workflow. From single-file scripts to enterprise monorepos, PackageMapper brings clarity to the chaos of package resolution. The 2026 release introduces neural network-assisted mapping, reducing resolution time by 40% for edge cases.
Join thousands of developers who no longer waste time guessing package names. PackageMapper: Because your time is better spent solving problems, not searching for packages.