Requirements Installer 🚀

Tired of hunting down missing Python dependencies? Requirements Installer automatically detects and installs all third-party packages your Python script needs—no requirements.txt needed!

Simply point it at a Python file, a Jupyter notebook, or a whole project folder, and it handles the rest. Perfect for running unfamiliar scripts, quick prototyping, or setting up development environments.

🎯 Two Ways to Use

1️⃣ Inside Your Code (Easiest!)

from requirements_installer import auto_install
auto_install()

2️⃣ Command Line

requirements_installer mycode.py          # one script
requirements_installer notebook.ipynb     # a notebook
requirements_installer src/               # a whole project

---

✨ Features

• ⚡ Auto-Install Inside Code - Just from requirements_installer import auto_install; auto_install() and you're done!
• 📓 Jupyter/Colab Support - Scans and installs from .ipynb files automatically (google.colab is never installed by mistake)
• 📁 Whole-Project Scanning - Point it at a directory and every .py / .ipynb below it is scanned; venvs, build/, node_modules/ are skipped
• 🔍 Smart Import Detection - Automatically scans your Python files for all third-party imports
• 📦 One-Command Install - Detects and installs dependencies in a single step
• 📝 Generate requirements.txt - Automatically create requirements.txt with pinned versions
• 🎯 Interactive Version Selection - Optionally choose specific versions for each package
• 🔒 Virtual Environment Support - Create and install into isolated environments
• 🧠 Intelligent Filtering - Excludes stdlib and local modules automatically
• 📄 Module-to-Package Mapping - Handles 380+ tricky cases like cv2 → opencv-python, pptx → python-pptx
• 🧩 Namespace-Aware - google.cloud.storage → google-cloud-storage, azure.storage.blob → azure-storage-blob, from google import genai → google-genai
• 🔧 Easy to Extend - Add new mappings by editing a simple JSON file
• 🌍 Recursive Local Import Scanning - Follows your own modules (and their imports) to catch every dependency
• 🎯 Runtime-Only - Imports under if TYPE_CHECKING: are ignored; already-installed packages are never reinstalled
• 💪 Pure Python - No external dependencies required

---

🔥 Installation

pip install requirements_installer

Or install from source:

git clone https://github.com/FH-Prevail/requirements_installer.git
cd requirements_installer
pip install -e .

---

🚀 Quick Start

⭐ NEW: Auto-Install Inside Your Code (Recommended!)

The easiest way - just add 2 lines to your script:

from requirements_installer import auto_install
auto_install()

# Now use any packages - they'll be auto-installed if missing!
import pandas as pd
import numpy as np
from sklearn.ensemble import RandomForestClassifier

Perfect for Jupyter/Colab notebooks:

# Cell 1: Your imports and code
import pandas as pd
import torch
from transformers import AutoModel
# ... your code ...

# Cell 2: Install everything (run this if imports fail)
!pip install -q requirements_installer
from requirements_installer import auto_install
auto_install()  # Scans all cells above and installs missing packages!

# Now re-run Cell 1 and it will work!

Or install dependencies first:

# Cell 1: Setup (run first)
!pip install -q requirements_installer
from requirements_installer import auto_install
auto_install()  # If you have imports in other cells, it will find them

# Cell 2+: Your code with any imports
import torch
import transformers

Basic Command-Line Usage

After pip install requirements_installer, use it as a command:

# Scan and install dependencies for a Python file
requirements_installer mycode.py

# Works with Jupyter notebooks too!
requirements_installer notebook.ipynb

# Scan an entire project directory (recursively)
requirements_installer src/

# The classic --file form still works
requirements_installer --file mycode.py

With Virtual Environment

# Create a venv and install dependencies there
requirements_installer --file mycode.py --use-venv --venv-path .venv

Interactive Version Selection

# Choose specific versions for each package
requirements_installer --file mycode.py --ask-version

Example interaction:

==================================================
Version Selection
==================================================

Install latest version of 'numpy'? [Y/n]: n
Enter version for 'numpy' (e.g., 1.2.3): 1.24.0

Install latest version of 'pandas'? [Y/n]: y

Install latest version of 'requests'? [Y/n]: 

Print Requirements Only

# Just show what would be installed, don't install
requirements_installer --file mycode.py --print-requirements

Generate requirements.txt

# Install dependencies AND generate requirements.txt with pinned versions
requirements_installer --file mycode.py --generate-requirements

This creates a requirements.txt file like:

# Generated by requirements_installer
# Install with: pip install -r requirements.txt

beautifulsoup4==4.12.2
numpy==1.24.3
pandas==2.0.2
requests==2.31.0

You can specify a custom output path:

requirements_installer --file mycode.py --generate-requirements --requirements-path deps.txt

---

📖 Usage Examples

Example 1: Auto-Install in Script (NEW! 🎉)

Make your scripts self-installing:

# my_analysis.py
from requirements_installer import auto_install
auto_install()

# Now use any packages!
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

df = pd.read_csv('data.csv')
plt.plot(df['x'], df['y'])
plt.show()

Just run it:

python my_analysis.py  # Auto-installs pandas, numpy, matplotlib!

Example 2: Jupyter/Colab Notebook

Option A - Install before running (recommended):

# Cell 1: One-time setup
!pip install -q requirements_installer
from requirements_installer import auto_install
auto_install()  # Scans ALL cells in notebook (even unexecuted ones!)

# Cell 2+: Now run your code
import pandas as pd
import torch
from transformers import AutoModel
model = AutoModel.from_pretrained('bert-base-uncased')

Option B - Fix import errors after they happen:

# Cell 1: Try to run your code
import pandas as pd
import torch
# ImportError: No module named 'torch'

# Cell 2: Install missing dependencies
!pip install -q requirements_installer
from requirements_installer import auto_install
auto_install()  # Scans ALL cells and installs what's needed!

# Cell 3: Re-run Cell 1 - now it works!

How it works in Colab/Jupyter:

• Automatically finds and reads your notebook file
• Scans ALL cells (even unexecuted ones!)
• Installs missing packages automatically
• No need to execute cells first - just call auto_install()

Example 3: Quick Script Setup

You clone a repo without a requirements.txt:

requirements_installer --file app.py

Output:

Detected environment: current Python at /usr/bin/python3
Entry file: /home/user/project/app.py
Installing: numpy pandas requests

==================================================
Installation Summary
==================================================
Installed: numpy, pandas, requests
Already satisfied: (none)
All requested packages are now present.

Example 4: Isolated Development Environment

requirements_installer --file main.py --use-venv

Creates a .venv folder and installs all dependencies there, keeping your system Python clean.

Example 5: Precise Version Control

requirements_installer --file analysis.py --ask-version

Prompts you for each package, letting you pin versions for reproducibility.

Example 6: Generate requirements.txt for Team Sharing

You inherit a script without documentation:

requirements_installer --file data_pipeline.py --generate-requirements

Output:

Detected environment: current Python at /usr/bin/python3
Entry file: /home/user/project/data_pipeline.py
Installing: pandas numpy sqlalchemy psycopg2-binary

==================================================
Installation Summary
==================================================
Installed: pandas, numpy, sqlalchemy, psycopg2-binary
Already satisfied: (none)
All requested packages are now present.

📝 Generating requirements.txt...
✅ Generated requirements.txt with 4 packages

You can now install these dependencies with:
  pip install -r requirements.txt

The generated requirements.txt:

# Generated by requirements_installer
# Install with: pip install -r requirements.txt

numpy==1.24.3
pandas==2.0.2
psycopg2-binary==2.9.6
sqlalchemy==2.0.15

Now you can share this with your team for reproducible installations!

---

🔧 Command-Line Options

After installation, use the requirements_installer command (or python -m requirements_installer):

usage: requirements_installer [-h] [--file FILE] [--use-venv] [--venv-path VENV_PATH]
                              [--print-requirements] [--ask-version]
                              [--generate-requirements] [--requirements-path REQUIREMENTS_PATH]
                              [--dry-run] [--upgrade] [--scan-config] [-q] [-v] [--version]
                              [path] [-- PIP_ARGS ...]

positional arguments:
  path                  Python file, Jupyter notebook, or directory to scan

options:
  -h, --help            Show this help message and exit
  --file FILE           Same as the positional PATH (kept for backwards compatibility)
  --use-venv            Create and use a virtual environment
  --venv-path VENV_PATH Where to create the venv (default: .venv)
  --print-requirements  Only print inferred packages and exit
  --ask-version         Interactively ask for a version preference for each package
  --generate-requirements
                        Generate requirements.txt with pinned versions after installation
  --requirements-path REQUIREMENTS_PATH
                        Path for requirements.txt file (default: requirements.txt)
  --dry-run             Show what would be installed without installing
  --upgrade             Pass --upgrade to pip for the packages being installed
  --scan-config         Also report packages declared in pyproject.toml / setup.cfg
  -q, --quiet           Suppress all output except errors
  -v, --verbose         Emit debug-level messages (shows skipped modules and pip output)
  --version             Show the version and exit
  -- PIP_ARGS           Everything after `--` is forwarded to `pip install`

Examples:

# Basic usage
requirements_installer mycode.py

# Whole project
requirements_installer src/

# With virtual environment
requirements_installer mycode.py --use-venv

# Interactive version selection
requirements_installer mycode.py --ask-version

# Scan Jupyter notebook
requirements_installer notebook.ipynb

# Generate requirements.txt
requirements_installer mycode.py --generate-requirements

# Custom requirements file path
requirements_installer mycode.py --generate-requirements --requirements-path deps.txt

# Use a private index / extra pip flags
requirements_installer mycode.py -- --index-url https://pypi.example.com/simple

Note: If you cloned the repository and want to run directly without installation:

python -m requirements_installer mycode.py

🐍 Python API

from requirements_installer import auto_install

# Auto-detect and install (recommended)
auto_install()

# Specify file explicitly
auto_install(file_path='script.py')
auto_install(file_path='notebook.ipynb')

# Use virtual environment
auto_install(use_venv=True, venv_path='.venv')

# Quiet mode (only show errors)
auto_install(quiet=True)

# Generate requirements.txt with pinned versions
auto_install(generate_requirements=True)

# Custom requirements file path
auto_install(generate_requirements=True, requirements_path='deps.txt')

# Scan a whole directory
auto_install(file_path='src/')

# Pass extra flags to pip, upgrade, or fail loudly
auto_install(upgrade=True, extra_pip_args=['--index-url', 'https://pypi.example.com/simple'])
auto_install(raise_on_error=True)   # RuntimeError if something could not be installed

# auto_install() returns the set of detected distributions
required = auto_install(dry_run=True)

---

🎯 How It Works

1. Parse Imports: Uses Python's AST to find all import and from ... import statements
2. Filter Standard Library: Removes built-in Python modules (e.g., os, sys, json)
3. Filter Local Modules: Excludes your project's own modules and follows them recursively so their imports are picked up too
4. Map Module Names: Converts import names to PyPI package names using module_mappings.json (e.g., cv2 → opencv-python). Dotted keys handle namespace packages (google.cloud.storage → google-cloud-storage); an empty value marks modules that must never be installed (google.colab)
5. Check Installation: Queries what's already installed (PEP 503-normalised, so typing_extensions == typing-extensions) to avoid redundant work
6. Install Packages: Uses pip to install missing packages
7. Verify: Confirms all required packages are present

---

📊 Comparison with Other Tools

Feature	requirements_installer	pipreqs	pigar	pythonrunscript
Auto-detect imports	✅	✅	✅	❌
Auto-install packages	✅	❌	❌	✅
Generate requirements.txt	✅	✅	✅	❌
Pinned versions in output	✅	✅	✅	❌
One-step install + generate	✅	❌	❌	❌
Call from inside code	✅	❌	❌	⚠️
Jupyter notebook support	✅	⚠️	✅	❌
Interactive version selection	✅	❌	❌	❌
Virtual environment support	✅	❌	❌	✅
No source file modification	✅	✅	✅	❌
One-command operation	✅	❌	❌	✅
Easy to extend mappings	✅	❌	❌	❌

Why requirements_installer?

• pipreqs/pigar: Generate requirements.txt but don't install (requires 2 steps)
• pythonrunscript: Installs but requires metadata comments in your code
• requirements_installer:
  • ✨ Call auto_install() directly in your code
  • 📓 Full Jupyter/Colab support
  • 🚀 Self-installing scripts
  • 💪 380+ module-to-package mappings, namespace-aware
  • 🔧 Easy to extend via JSON file
  • 📝 One command to install AND generate requirements.txt

---

🧪 Module-to-Package Mappings

The tool includes smart mappings for 380+ common cases where the import name differs from the PyPI package name. These mappings are stored in requirements_installer/module_mappings.json for easy maintenance and contributions.

Common examples:

cv2          → opencv-python
PIL          → Pillow
sklearn      → scikit-learn
yaml         → PyYAML
bs4          → beautifulsoup4
pptx         → python-pptx
docx         → python-docx
MySQLdb      → mysqlclient
psycopg2     → psycopg2-binary
telegram     → python-telegram-bot
discord      → discord.py
serial       → pyserial
git          → GitPython
win32api     → pywin32
google.cloud.storage → google-cloud-storage   # dotted keys for namespace packages
from google import genai → google-genai
azure.storage.blob   → azure-storage-blob
google.colab → (skipped – never pip-installed)
en_core_web_sm → (skipped – install via `python -m spacy download`)
# ... and 370+ more!

Sub-packages of google.cloud.*, azure.*, opentelemetry.* and sphinxcontrib.* are also mapped generically (import a.b.c → a-b-c) when no explicit entry exists.

Adding Your Own Mappings

It's easy to contribute new mappings! Just edit module_mappings.json:

{
  "your_import_name": "pypi-package-name",
  "namespace.subpackage": "namespace-subpackage",
  "never_install_this": ""
}

Keys may be dotted; the longest matching prefix wins. An empty string means never install.

Then submit a pull request or use your custom version locally.

---

⚠️ Limitations

• Dynamic imports: Limited detection of importlib.import_module() calls
• Conditional imports: Imports inside try/except ImportError are still installed (only if TYPE_CHECKING: blocks are skipped)
• Version conflicts: Doesn't resolve complex dependency conflicts (delegates to pip)
• Jupyter notebooks: Best results when notebook is saved. If not found, falls back to scanning executed cells only

These are deliberate trade-offs for simplicity and speed. For complex projects with intricate dependency trees, consider using Poetry or Pipenv.

---

🆘 Troubleshooting

Imports not detected in Jupyter/Colab

Problem: Some imports are not being detected.

Solution:

The tool automatically tries to find your notebook file to scan ALL cells. If it can't find the file:

1. Save your notebook - This helps the tool locate and read it
2. For Colab: Mount Google Drive if your notebook is stored there:

from google.colab import drive
drive.mount('/content/drive')

3. Fallback behavior: If the notebook file isn't found, it scans executed cells only. In this case, run cells with imports before calling auto_install().

Command not found

# If 'requirements_installer' command not found, try:
python -m requirements_installer mycode.py

# Or check if installed:
pip show requirements_installer

---

🆚 Command Line vs auto_install()

Command Line (traditional):

pip install requirements_installer
requirements_installer --file mycode.py
python mycode.py

auto_install() (modern - recommended):

python mycode.py  # That's it! Self-installing

---

🤝 Contributing

Contributions are welcome! Here are some ways you can help:

• 🐛 Report bugs and issues
• 💡 Suggest new features or improvements
• 📝 Improve documentation
• 🔧 Submit pull requests
• ⭐ Add more module-to-package mappings to module_mappings.json

Development Setup

git clone https://github.com/FH-Prevail/requirements_installer.git
cd requirements_installer
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Adding New Mappings

To add new module-to-package mappings:

1. Edit module_mappings.json
2. Add your mapping: "import_name": "pypi-package-name"
3. Test it works
4. Submit a pull request!

Note: Only add mappings where the import name differs from the package name. No need for entries like "torch": "torch".

Running Tests

python -m pytest tests/

Releasing

Bump __version__ in requirements_installer/__init__.py, update CHANGELOG.md, then:

python publish.py --dry-run   # test → build → twine check
python publish.py             # …and upload (token from .env: PYPI_API_TOKEN=…)

See CHANGELOG.md for release notes.

---

📝 Changelog

See CHANGELOG.md.

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

Inspired by:

• pipreqs - For the import scanning approach
• pigar - For AST parsing techniques
• pythonrunscript - For auto-installation workflows

---

📬 Contact & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Repository: github.com/FH-Prevail/requirements_installer
• Author: Sina Mirshahi

---

🎓 Perfect For:

• 📓 Jupyter/Colab notebooks - Make them truly self-contained
• 🚀 Quick scripts - No setup, just run
• 👥 Sharing code - Recipients don't need to know about dependencies
• 🎓 Teaching - Students can run examples immediately
• 🔬 Research - Reproducible notebooks that "just work"
• 🤖 Automation - Scripts that set themselves up
• 📋 Team collaboration - Generate requirements.txt for reproducible environments
• 🔄 CI/CD pipelines - Automatically detect and document dependencies

---

Made with ❤️ by Sina Mirshahi

Star this repo if you find it useful! ⭐

Report Bug · Request Feature · Contribute