Installation

Install venvm from PyPI:

python -m pip install venvm

Usage

Select an environment and script interactively:

venvm

In an interactive terminal, use the arrow keys and Enter or type an option number and press Enter. Numbered prompts remain available in non-interactive terminals.

Script discovery scans the project recursively and displays paths relative to the project root. Virtual environments, version-control metadata, caches, build output, and node_modules are excluded from the scan. Root-level scripts are listed first, followed by scripts in progressively deeper directories.

The script picker shows only the current directory and child directories that contain scripts. Use Right or Enter to open a directory, Left to return to its parent, and Enter to run a script. Numbered selection remains available.

Run a script with arguments:

venvm app.py --port 8000

Select an environment explicitly or use the system interpreter:

venvm --env .venv app.py
venvm --system app.py

Run a Python module:

venvm --env .venv --module pytest -q
venvm --system --module http.server 8000

Values after --module are passed directly to the module. Place environment options before --module.

List detected environments without running anything:

venvm --list

--yes accepts confirmation prompts. If multiple environments exist, .venv is used when available. Otherwise, specify the environment with --env.

Use --install-deps to install detected dependency sources without additional confirmation. --yes alone never installs dependencies automatically.

The command scans direct children of the current directory for pyvenv.cfg and the platform-specific Python executable. If no environment exists, it offers to create .venv. The system Python interpreter remains available as an option.

After creating an environment, venvm detects requirements.txt, requirements-dev.txt, and pyproject.toml. It asks for confirmation before installing each source.

Project Configuration

Add .venvm.json to the project root to define defaults:

{
  "environment": ".venv",
  "script": "app.py"
}

For a module:

{
  "environment": ".venv",
  "module": "pytest"
}

script and module cannot be used together. Command-line values override the configuration file. When run from a subdirectory, venvm searches parent directories for the nearest .venvm.json and uses its directory as the project root.

Development

Install the repository in editable mode:

python -m pip install -e .

Run the standard-library test suite:

python -m unittest discover -s tests

Roadmap

Planned configuration and project management work is tracked in .github/TODO.md.