requirements-installer 1.0.4

Automatically detect and install Python dependencies from your code

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 your Python file, 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 --file mycode.py

---

✨ 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
• 🔍 Smart Import Detection - Automatically scans your Python files for all third-party imports
• 📦 One-Command Install - Detects and installs dependencies in a single step
• 🎯 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 100+ tricky cases like cv2 → opencv-python, pptx → python-pptx
• 🌐 One-Hop Local Import Scanning - Follows local imports to catch all dependencies
• 💪 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 --file mycode.py

# Works with Jupyter notebooks too!
requirements_installer --file notebook.ipynb

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

---

📖 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 - 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!

Option B - Set up first (recommended for sharing):

# Cell 1: One-time setup
!pip install -q requirements_installer
from requirements_installer import auto_install
auto_install()  # Will scan entire notebook session

# Cell 2+: Your code
import torch
from transformers import AutoModel
model = AutoModel.from_pretrained('bert-base-uncased')

How it works in Colab:

• Reads all executed cells from your notebook session
• Finds all import statements
• Installs missing packages automatically
• No need to save the notebook as a file!

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.

---

🔧 Command-Line Options

After installation, use the requirements_installer command:

usage: requirements_installer [-h] --file FILE [--use-venv] 
                              [--venv-path VENV_PATH]
                              [--print-requirements] [--ask-version]

options:
  -h, --help            Show this help message and exit
  --file FILE           Entry Python file or Jupyter notebook (.ipynb) to scan
  --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 version preference for each package

Examples:

# Basic usage
requirements_installer --file mycode.py

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

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

# Scan Jupyter notebook
requirements_installer --file notebook.ipynb

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

python requirements_installer.py --file 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)

---

🎯 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
4. Map Module Names: Converts import names to PyPI package names (e.g., cv2 → opencv-python)
5. Check Installation: Queries what's already installed 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	✅	❌	❌	✅
Call from inside code	✅	❌	❌	⚠️
Jupyter notebook support	✅	⚠️	✅	❌
Interactive version selection	✅	❌	❌	❌
Virtual environment support	✅	❌	❌	✅
No source file modification	✅	✅	✅	❌
One-command operation	✅	❌	❌	✅

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
  • 💪 100+ module-to-package mappings

---

🧪 Module-to-Package Mappings

The tool includes smart mappings for 100+ common cases where the import name differs from the PyPI package name:

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
# ... and 90+ more!

---

⚠️ Limitations

• One-hop scanning: Only follows local imports one level deep (for speed)
• Dynamic imports: Limited detection of importlib.import_module() calls
• Conditional imports: Treats all imports equally (no context analysis)
• Version conflicts: Doesn't resolve complex dependency conflicts (delegates to pip)
• Jupyter/Colab: Scans all executed cells in the session. Make sure to run cells with imports before calling auto_install()

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

---

🆘 Troubleshooting

Google Colab: "Could not detect file to scan"

Problem: You get this error in Colab:

❌ Could not detect file to scan. Please provide file_path argument.

Solution: In Colab, auto_install() reads from your executed cells. Make sure you:

1. Run cells with imports first, then run auto_install():

# Cell 1: Your code with imports
import pandas as pd
import numpy as np

# Cell 2: Run this cell
!pip install -q requirements_installer  
from requirements_installer import auto_install
auto_install()  # This reads Cell 1 and installs pandas, numpy

2. Or, if you already ran your code and got import errors, just run auto_install() - it will scan all previous cells!

Command not found

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

# Or check if installed:
pip show requirements_installer

Imports not detected

Make sure you've executed the cells containing your imports. In Jupyter/Colab, only executed cells are scanned.

---

🆚 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

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 .

Running Tests

python -m pytest tests/

---

📄 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

---

🎓 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

---

Made with ❤️ by Sina

Star this repo if you find it useful! ⭐

Report Bug · Request Feature · Contribute