# PyEnvRunner
**Automatically manage Python virtual environments and dependencies.**
PyEnvRunner is a command-line tool that runs Python scripts with automatic dependency detection and installation. When your script imports missing packages, PyEnvRunner automatically installs them in an isolated virtual environment. Perfect for quick prototyping, sharing scripts, and avoiding "works on my machine" issues.
[](https://badge.fury.io/py/pyenvrunner)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
## ✨ Features
- **🚀 Automatic Dependency Installation** - Detects missing imports at runtime and installs them automatically
- **🔒 Isolated Environments** - Creates virtual environments to keep your system Python clean
- **💨 Real-time Output Streaming** - See script output immediately, perfect for long-running services and APIs
- **📦 Import Name Mapping** - Handles cases where import names differ from PyPI names (e.g., `import cv2` → `pip install opencv-python`)
- **📝 Requirements Tracking** - Optionally save installed packages to a requirements file with version pinning
- **🎯 Zero External Dependencies** - Uses only Python standard library
- **🔧 Flexible CLI** - Supports various workflows with intuitive command-line flags
## 🎯 Use Cases
- **Quick Prototyping** - Run scripts without worrying about dependencies
- **Sharing Scripts** - Share a single `.py` file that anyone can run
- **CI/CD Pipelines** - Automatically install dependencies in clean environments
- **API Development** - Real-time output streaming for server logs
- **Education** - Students can run examples without manual setup
- **Testing** - Quickly test scripts in isolated environments
## 📦 Installation
```bash
pip install pyenvrunner
```
## 🚀 Quick Start
### Basic Usage
```bash
# Run a script - automatically installs missing packages
pyenvrunner my_script.py
# Run a script with arguments
pyenvrunner my_script.py --arg1 value1 --arg2 value2
# Save installed packages to requirements file
pyenvrunner --save-reqs my_script.py
```
### Example Script
Create a file `demo.py`:
```python
# No need to install requests first!
import requests
response = requests.get('https://api.github.com')
print(f"Status: {response.status_code}")
```
Run it:
```bash
$ pyenvrunner demo.py
Virtual environment is ready in './env'.
To activate it manually in your shell:
source env/bin/activate
------------------------------
--- Running script: demo.py using env/bin/python ---
Traceback (most recent call last):
File "demo.py", line 1, in <module>
import requests
ModuleNotFoundError: No module named 'requests'
>>> Detected missing module: 'requests'. Attempting to install 'requests'...
--- pip install STDOUT for requests ---
Collecting requests
Using cached requests-2.32.5-py3-none-any.whl (64 kB)
...
Successfully installed requests-2.32.5
>>> Installation of requests successful. Retrying script...
--- Running script: demo.py using env/bin/python ---
Status: 200
--- Script demo.py completed successfully ---
```
## 📖 CLI Documentation
### Command Syntax
```bash
pyenvrunner [OPTIONS] <script_path> [SCRIPT_ARGS...]
```
### Options
#### Script Execution
- **`script_path`** - Path to the Python script to execute (default: `main.py`)
#### Virtual Environment Options
- **`--env-name NAME`** - Name of the virtual environment directory (default: `env`)
- **`--use-current-env`** - Use the current Python environment instead of creating a venv
- **`--force-recreate-env`** - Delete and recreate the venv if it already exists
#### Package Management Options
- **`--save-reqs`** - Save newly installed packages to requirements file
- **`--reqs-file FILE`** - Specify custom requirements file name (default: `pyenvrunner_requirements.txt`)
#### Utility Commands
- **`--list-import-mappings`** - Display predefined import-to-package mappings and exit
- **`--clear-env`** - Remove all installed packages from the environment and exit
- **`-h, --help`** - Show help message and exit
### Usage Examples
```bash
# Basic execution with automatic venv creation
pyenvrunner my_script.py
# Save dependencies to requirements file
pyenvrunner --save-reqs my_script.py
# Use custom virtual environment name
pyenvrunner --env-name my_custom_env my_script.py
# Force recreate environment (fresh start)
pyenvrunner --force-recreate-env my_script.py
# Use current Python environment (no venv)
pyenvrunner --use-current-env my_script.py
# Save to custom requirements file
pyenvrunner --save-reqs --reqs-file deps.txt my_script.py
# Pass arguments to your script
pyenvrunner my_script.py --input data.csv --output results.json
# List import name mappings
pyenvrunner --list-import-mappings
# Clear all packages from environment
pyenvrunner --clear-env --env-name my_env
```
## 🗺️ Import Name Mapping
Some Python packages have different import names than their PyPI package names. PyEnvRunner handles these automatically:
| Import Statement | PyPI Package |
|-----------------|-------------|
| `import cv2` | `opencv-python` |
| `import sklearn` | `scikit-learn` |
| `from PIL import Image` | `Pillow` |
| `import yaml` | `PyYAML` |
| `from dotenv import load_dotenv` | `python-dotenv` |
| `import dateutil` | `python-dateutil` |
View all mappings:
```bash
pyenvrunner --list-import-mappings
```
## 🔧 How It Works
1. **Create/Reuse Virtual Environment** - PyEnvRunner creates a venv in the current directory (or uses an existing one)
2. **Run Your Script** - Executes your script using the venv's Python interpreter
3. **Detect Missing Imports** - Monitors stderr for `ModuleNotFoundError` messages
4. **Install Packages** - Automatically runs `pip install <package>` for missing modules
5. **Retry Execution** - Reruns the script after installing packages
6. **Real-time Output** - Streams stdout/stderr in real-time using multi-threading
7. **Success** - Script completes with all dependencies installed
## 📁 Project Structure
```
pyenvrunner/
├── pyenvrunner/
│ ├── __init__.py
│ ├── cli/
│ │ └── main.py # CLI entry point and argument parsing
│ └── core/
│ ├── config.py # Configuration (import mappings, defaults)
│ ├── exceptions.py # Custom exception classes
│ ├── package_management.py # Package installation and script execution
│ └── venv_management.py # Virtual environment creation
├── tests/
│ ├── test_cases/ # 20 comprehensive test cases
│ ├── run_tests.py # Test runner with reporting
│ └── clear.sh # Cleanup script
├── setup.py # Package configuration
├── .gitignore # Git ignore rules
└── README.md # This file
```
## 🧪 Testing
PyEnvRunner includes a comprehensive test suite with 20 test cases covering all features:
```bash
cd tests
python3 run_tests.py
```
Test categories:
- **Core Functionality** - Basic execution, argument handling, auto-install
- **CLI Flags** - All command-line options
- **Error Handling** - Script errors, invalid imports, exit codes
- **Edge Cases** - No output, special characters, warnings
Clean up test artifacts:
```bash
cd tests
./clear.sh
```
## 🤝 Contributing
Contributions are welcome! Here's how you can help:
1. **Fork the repository**
2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
3. **Make your changes**
4. **Add tests** for your changes
5. **Run the test suite** (`cd tests && python3 run_tests.py`)
6. **Commit your changes** (`git commit -m 'Add amazing feature'`)
7. **Push to the branch** (`git push origin feature/amazing-feature`)
8. **Open a Pull Request**
### Development Setup
```bash
# Clone the repository
cd pyenvrunner
pip install -e .
```
## 📋 Requirements
- Python 3.6 or higher
- No external dependencies (uses only Python standard library)
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Inspired by tools like `pipx`, `uvx`, and npm's automatic package installation
- Built with ❤️ for the Python community
## 🐛 Known Limitations
- **Import Detection** - Only detects `ModuleNotFoundError` at runtime. Imports inside try-except blocks won't be detected.
- **Dynamic Imports** - Doesn't detect imports using `importlib` or `__import__()`.
- **Sequential Installation** - Installs packages one at a time, not in parallel.
## 📞 Support
- **Email** - thiyyaguraadityareddy@gmail.com
## 🗺️ Roadmap
- [ ] Add static analysis to detect imports before runtime
- [ ] Support for conda environments
- [ ] Parallel package installation
- [ ] Configuration file support (.pyenvrunner.toml)
- [ ] Integration with poetry/pipenv
- [ ] Docker container support
---
**Made with ❤️ by Aditya Thiyyagura**
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/pyenvrunner",
"name": "pyenvrunner",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "venv virtualenv dependency-management pip automation",
"author": "Aditya Thiyyagura",
"author_email": "thiyyaguraadityareddy@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/18/fe/b673b93ddcf623aa927d0e768e88534c9dad0400e8520c3203891c9b878d/pyenvrunner-1.0.1.tar.gz",
"platform": null,
"description": "# PyEnvRunner\n\n**Automatically manage Python virtual environments and dependencies.**\n\nPyEnvRunner is a command-line tool that runs Python scripts with automatic dependency detection and installation. When your script imports missing packages, PyEnvRunner automatically installs them in an isolated virtual environment. Perfect for quick prototyping, sharing scripts, and avoiding \"works on my machine\" issues.\n\n[](https://badge.fury.io/py/pyenvrunner)\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\n## \u2728 Features\n\n- **\ud83d\ude80 Automatic Dependency Installation** - Detects missing imports at runtime and installs them automatically\n- **\ud83d\udd12 Isolated Environments** - Creates virtual environments to keep your system Python clean\n- **\ud83d\udca8 Real-time Output Streaming** - See script output immediately, perfect for long-running services and APIs\n- **\ud83d\udce6 Import Name Mapping** - Handles cases where import names differ from PyPI names (e.g., `import cv2` \u2192 `pip install opencv-python`)\n- **\ud83d\udcdd Requirements Tracking** - Optionally save installed packages to a requirements file with version pinning\n- **\ud83c\udfaf Zero External Dependencies** - Uses only Python standard library\n- **\ud83d\udd27 Flexible CLI** - Supports various workflows with intuitive command-line flags\n\n## \ud83c\udfaf Use Cases\n\n- **Quick Prototyping** - Run scripts without worrying about dependencies\n- **Sharing Scripts** - Share a single `.py` file that anyone can run\n- **CI/CD Pipelines** - Automatically install dependencies in clean environments\n- **API Development** - Real-time output streaming for server logs\n- **Education** - Students can run examples without manual setup\n- **Testing** - Quickly test scripts in isolated environments\n\n## \ud83d\udce6 Installation\n\n```bash\npip install pyenvrunner\n```\n\n## \ud83d\ude80 Quick Start\n\n### Basic Usage\n\n```bash\n# Run a script - automatically installs missing packages\npyenvrunner my_script.py\n\n# Run a script with arguments\npyenvrunner my_script.py --arg1 value1 --arg2 value2\n\n# Save installed packages to requirements file\npyenvrunner --save-reqs my_script.py\n```\n\n### Example Script\n\nCreate a file `demo.py`:\n\n```python\n# No need to install requests first!\nimport requests\n\nresponse = requests.get('https://api.github.com')\nprint(f\"Status: {response.status_code}\")\n```\n\nRun it:\n\n```bash\n$ pyenvrunner demo.py\n\nVirtual environment is ready in './env'.\nTo activate it manually in your shell:\n source env/bin/activate\n------------------------------\n\n--- Running script: demo.py using env/bin/python ---\nTraceback (most recent call last):\n File \"demo.py\", line 1, in <module>\n import requests\nModuleNotFoundError: No module named 'requests'\n\n>>> Detected missing module: 'requests'. Attempting to install 'requests'...\n--- pip install STDOUT for requests ---\nCollecting requests\n Using cached requests-2.32.5-py3-none-any.whl (64 kB)\n...\nSuccessfully installed requests-2.32.5\n>>> Installation of requests successful. Retrying script...\n\n--- Running script: demo.py using env/bin/python ---\nStatus: 200\n\n--- Script demo.py completed successfully ---\n```\n\n## \ud83d\udcd6 CLI Documentation\n\n### Command Syntax\n\n```bash\npyenvrunner [OPTIONS] <script_path> [SCRIPT_ARGS...]\n```\n\n### Options\n\n#### Script Execution\n- **`script_path`** - Path to the Python script to execute (default: `main.py`)\n\n#### Virtual Environment Options\n- **`--env-name NAME`** - Name of the virtual environment directory (default: `env`)\n- **`--use-current-env`** - Use the current Python environment instead of creating a venv\n- **`--force-recreate-env`** - Delete and recreate the venv if it already exists\n\n#### Package Management Options\n- **`--save-reqs`** - Save newly installed packages to requirements file\n- **`--reqs-file FILE`** - Specify custom requirements file name (default: `pyenvrunner_requirements.txt`)\n\n#### Utility Commands\n- **`--list-import-mappings`** - Display predefined import-to-package mappings and exit\n- **`--clear-env`** - Remove all installed packages from the environment and exit\n- **`-h, --help`** - Show help message and exit\n\n### Usage Examples\n\n```bash\n# Basic execution with automatic venv creation\npyenvrunner my_script.py\n\n# Save dependencies to requirements file\npyenvrunner --save-reqs my_script.py\n\n# Use custom virtual environment name\npyenvrunner --env-name my_custom_env my_script.py\n\n# Force recreate environment (fresh start)\npyenvrunner --force-recreate-env my_script.py\n\n# Use current Python environment (no venv)\npyenvrunner --use-current-env my_script.py\n\n# Save to custom requirements file\npyenvrunner --save-reqs --reqs-file deps.txt my_script.py\n\n# Pass arguments to your script\npyenvrunner my_script.py --input data.csv --output results.json\n\n# List import name mappings\npyenvrunner --list-import-mappings\n\n# Clear all packages from environment\npyenvrunner --clear-env --env-name my_env\n```\n\n## \ud83d\uddfa\ufe0f Import Name Mapping\n\nSome Python packages have different import names than their PyPI package names. PyEnvRunner handles these automatically:\n\n| Import Statement | PyPI Package |\n|-----------------|-------------|\n| `import cv2` | `opencv-python` |\n| `import sklearn` | `scikit-learn` |\n| `from PIL import Image` | `Pillow` |\n| `import yaml` | `PyYAML` |\n| `from dotenv import load_dotenv` | `python-dotenv` |\n| `import dateutil` | `python-dateutil` |\n\nView all mappings:\n```bash\npyenvrunner --list-import-mappings\n```\n\n## \ud83d\udd27 How It Works\n\n1. **Create/Reuse Virtual Environment** - PyEnvRunner creates a venv in the current directory (or uses an existing one)\n2. **Run Your Script** - Executes your script using the venv's Python interpreter\n3. **Detect Missing Imports** - Monitors stderr for `ModuleNotFoundError` messages\n4. **Install Packages** - Automatically runs `pip install <package>` for missing modules\n5. **Retry Execution** - Reruns the script after installing packages\n6. **Real-time Output** - Streams stdout/stderr in real-time using multi-threading\n7. **Success** - Script completes with all dependencies installed\n\n## \ud83d\udcc1 Project Structure\n\n```\npyenvrunner/\n\u251c\u2500\u2500 pyenvrunner/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 cli/\n\u2502 \u2502 \u2514\u2500\u2500 main.py # CLI entry point and argument parsing\n\u2502 \u2514\u2500\u2500 core/\n\u2502 \u251c\u2500\u2500 config.py # Configuration (import mappings, defaults)\n\u2502 \u251c\u2500\u2500 exceptions.py # Custom exception classes\n\u2502 \u251c\u2500\u2500 package_management.py # Package installation and script execution\n\u2502 \u2514\u2500\u2500 venv_management.py # Virtual environment creation\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 test_cases/ # 20 comprehensive test cases\n\u2502 \u251c\u2500\u2500 run_tests.py # Test runner with reporting\n\u2502 \u2514\u2500\u2500 clear.sh # Cleanup script\n\u251c\u2500\u2500 setup.py # Package configuration\n\u251c\u2500\u2500 .gitignore # Git ignore rules\n\u2514\u2500\u2500 README.md # This file\n```\n\n## \ud83e\uddea Testing\n\nPyEnvRunner includes a comprehensive test suite with 20 test cases covering all features:\n\n```bash\ncd tests\npython3 run_tests.py\n```\n\nTest categories:\n- **Core Functionality** - Basic execution, argument handling, auto-install\n- **CLI Flags** - All command-line options\n- **Error Handling** - Script errors, invalid imports, exit codes\n- **Edge Cases** - No output, special characters, warnings\n\nClean up test artifacts:\n```bash\ncd tests\n./clear.sh\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. **Fork the repository**\n2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)\n3. **Make your changes**\n4. **Add tests** for your changes\n5. **Run the test suite** (`cd tests && python3 run_tests.py`)\n6. **Commit your changes** (`git commit -m 'Add amazing feature'`)\n7. **Push to the branch** (`git push origin feature/amazing-feature`)\n8. **Open a Pull Request**\n\n### Development Setup\n\n```bash\n# Clone the repository\ncd pyenvrunner\npip install -e .\n```\n\n## \ud83d\udccb Requirements\n\n- Python 3.6 or higher\n- No external dependencies (uses only Python standard library)\n\n## \ud83d\udcdc License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Inspired by tools like `pipx`, `uvx`, and npm's automatic package installation\n- Built with \u2764\ufe0f for the Python community\n\n## \ud83d\udc1b Known Limitations\n\n- **Import Detection** - Only detects `ModuleNotFoundError` at runtime. Imports inside try-except blocks won't be detected.\n- **Dynamic Imports** - Doesn't detect imports using `importlib` or `__import__()`.\n- **Sequential Installation** - Installs packages one at a time, not in parallel.\n\n## \ud83d\udcde Support\n\n- **Email** - thiyyaguraadityareddy@gmail.com\n\n## \ud83d\uddfa\ufe0f Roadmap\n\n- [ ] Add static analysis to detect imports before runtime\n- [ ] Support for conda environments\n- [ ] Parallel package installation\n- [ ] Configuration file support (.pyenvrunner.toml)\n- [ ] Integration with poetry/pipenv\n- [ ] Docker container support\n\n---\n\n**Made with \u2764\ufe0f by Aditya Thiyyagura**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Wrapper to manage Python venvs & run scripts, installing missing dependencies",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/yourusername/pyenvrunner/issues",
"Homepage": "https://github.com/yourusername/pyenvrunner",
"Source": "https://github.com/yourusername/pyenvrunner"
},
"split_keywords": [
"venv",
"virtualenv",
"dependency-management",
"pip",
"automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d29b3f328523aa3ca301ddc3b481d10cbc1040d0171dbec2b3204e4d5bf1fc85",
"md5": "82e5f20e3527bfc2670b9c4863078a4d",
"sha256": "4c245d56c766ba36bb493f6e57a986a9fd8aef4216184da7122576da5fe0bc70"
},
"downloads": -1,
"filename": "pyenvrunner-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "82e5f20e3527bfc2670b9c4863078a4d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 18913,
"upload_time": "2025-10-28T08:28:47",
"upload_time_iso_8601": "2025-10-28T08:28:47.475841Z",
"url": "https://files.pythonhosted.org/packages/d2/9b/3f328523aa3ca301ddc3b481d10cbc1040d0171dbec2b3204e4d5bf1fc85/pyenvrunner-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "18feb673b93ddcf623aa927d0e768e88534c9dad0400e8520c3203891c9b878d",
"md5": "0ef2e5b1491340c7d342e91326462777",
"sha256": "16e178fefb047df825061914bd65bcab0d2a3e504a883f33eef2dd3329654a5e"
},
"downloads": -1,
"filename": "pyenvrunner-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "0ef2e5b1491340c7d342e91326462777",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 19975,
"upload_time": "2025-10-28T08:28:48",
"upload_time_iso_8601": "2025-10-28T08:28:48.879018Z",
"url": "https://files.pythonhosted.org/packages/18/fe/b673b93ddcf623aa927d0e768e88534c9dad0400e8520c3203891c9b878d/pyenvrunner-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 08:28:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "pyenvrunner",
"github_not_found": true,
"lcname": "pyenvrunner"
}
JSON
