PyRun

PyRun simplifies Python project setup, dependency management and development server execution with automatic virtual environment handling and reload behavior.

Why PyRun?

PyRun provides:

• One-command project initialization
• Automatic virtual environment creation
• Structured dependency tracking via modules.json
• Smart install, upgrade, and downgrade handling
• Bulk dependency installation (--all)
• Clean uninstall support
• Framework-aware run commands
• Host and port override support
• Automatic server refresh on dependency changes
• Optional reload with custom directories for development
• Run arbitrary Python modules with extra CLI arguments

It brings a familiar, clean CLI experience to Python development.

Installation

Install globally via npm:

npm install -g @caleb-ne1/pyrun

Verify installation:

pyrun --help

Quick Start

1. Initialize a Project

pyrun init <framework> [path]

Example:

pyrun init fastapi .

This will:

• Create a venv virtual environment
• Generate modules.json
• Install required framework dependencies

2. Run the Project

pyrun run [entry-file] --port <port> --host <host>

Examples:

pyrun run
pyrun run app.py
pyrun run app.py --port 3000
pyrun run app.py --host 0.0.0.0 --port 8000
pyrun run app.py --reload
pyrun run app.py --reload --reloadDirs src,api

PyRun automatically detects:

• app.py
• main.py
• manage.py

Frameworks with native reload support use their internal reload mechanisms for efficient development.

Reload behavior:

• Optional --reload enables automatic server restart on code changes

• --reloadDirs allows specifying directories to watch for changes (defaults to project root if not provided)

• Supported frameworks: Flask and FastAPI

3. Run Python Modules

You can run Python modules like pyinstaller, pytest, black, etc., directly:

pyrun run <project> --module pyinstaller --extraArgs="--onefile --noconsole app.py"
pyrun run <project> --module pytest --extraArgs="tests/"

• --module specifies the Python module

• --extraArgs passes additional CLI arguments to the module

4. Install Dependencies

Install one or multiple modules:

pyrun install requests
pyrun install flask:2.0.1
pyrun install requests fastapi:0.110.0

Behavior:

• Installs new modules
• Updates versions if different
• Downgrades when specified
• Updates modules.json
• Triggers server refresh when running

5. Install All Project Dependencies

After cloning a project:

pyrun install --all

This installs all dependencies defined in modules.json.

6. Uninstall Modules

pyrun uninstall requests

• Removes the module from the virtual environment
• Updates modules.json
• Refreshes the server if running

Project Structure

After initialization:

myproject/
├── venv/
├── modules.json
├── app.py | main.py | manage.py

modules.json Example

{
  "framework": "fastapi",
  "dependencies": {
    "fastapi": "0.110.0",
    "uvicorn": "0.29.0",
    "requests": "2.31.0"
  }
}

modules.json replaces traditional requirements.txt with structured dependency tracking.

Supported Frameworks

• Django
• Flask
• FastAPI
• Plain Python

License

This project is licensed under the MIT License. See the LICENSE file for details.