coquibot/coqui-toolkit-python-env

Python virtual environment and dependency management toolkit for Coqui — create, inspect, install, and remove venvs using pip, conda, or uv

v0.1.0 2026-04-08 23:37 UTC

Requires

• php: ^8.4

Requires (Dev)

• carmelosantana/php-agents: ^0.7
• pestphp/pest: ^3.0
• phpstan/phpstan: ^2.0

MIT

• Carmelo Santana

• toolkit
• python
• pip
• uv
• php-agents
• coqui
• virtualenv
• venv
• conda

README

Manage Python virtual environments and dependencies through Coqui. Supports pip (venv), conda, and uv backends.

Installation

composer require coquibot/coqui-toolkit-python-env

Coqui discovers the toolkit automatically via composer.json metadata.

Requirements

• PHP 8.4+
• Python 3.8+ (system-installed)
• One or more Python environment backends:
  • venv + pip — included with Python (default)
  • conda — Miniconda or Anaconda
  • uv — Astral's uv (fast alternative)

Tools

Tool	Description
python_env_detect	Scan a project directory for dependency files, existing environments, and system tools
python_env_create	Create a new virtual environment (venv, conda, or uv)
python_env_status	Check environment health: Python version, pip version, package count, CUDA support
python_env_install	Install packages from names, requirements.txt, pyproject.toml extras, or conda env files
python_env_list	List installed packages in table, freeze, or JSON format
python_env_run	Execute inline Python code, scripts, or modules inside the environment
python_env_remove	Delete an environment with safety confirmations

Typical Workflow

1. python_env_detect  → Scan the project, find dependency files
2. python_env_create  → Create a .venv in the project directory
3. python_env_install → Install dependencies from requirements.txt or pyproject.toml
4. python_env_status  → Verify everything is working
5. python_env_run     → Execute code or scripts

Backend Comparison

Feature	venv + pip	conda	uv
Speed	Moderate	Slow	Very fast
Python version management	No	Yes	Yes
Non-Python packages (C libs)	No	Yes	No
GPU/CUDA packages	Via index URL	Native	Via index URL
Disk usage	Low	High	Low
Best for	General projects	Scientific/ML	Modern Python

Examples

Standard Python Project (requirements.txt)

python_env_detect(project_path: "/path/to/project")
python_env_create(project_path: "/path/to/project")
python_env_install(project_path: "/path/to/project", requirements_file: "requirements.txt")

Project with pyproject.toml and Extras

python_env_detect(project_path: "/path/to/jasper")
python_env_create(project_path: "/path/to/jasper")
python_env_install(project_path: "/path/to/jasper", requirements_file: "pyproject.toml")
python_env_install(project_path: "/path/to/jasper", requirements_file: "pyproject.toml[dev,test]")

GPU/CUDA Project (PyTorch)

python_env_create(project_path: "/path/to/project")
python_env_install(
    project_path: "/path/to/project",
    packages: ["torch", "torchvision"],
    index_url: "https://download.pytorch.org/whl/cu121"
)
python_env_install(project_path: "/path/to/project", requirements_file: "requirements.txt")

Conda Environment from environment.yml

python_env_create(project_path: "/path/to/project", backend: "conda")
python_env_install(project_path: "/path/to/project", requirements_file: "environment.yml", backend: "conda")

Using uv for Fast Installs

python_env_create(project_path: "/path/to/project", backend: "uv")
python_env_install(project_path: "/path/to/project", requirements_file: "requirements.txt", backend: "uv")

Parameters Reference

python_env_detect

Parameter	Type	Required	Description
project_path	string	Yes	Absolute path to the project directory

python_env_create

Parameter	Type	Required	Default	Description
project_path	string	Yes	—	Absolute path to the project directory
backend	enum	No	venv	venv, conda, or uv
python_version	string	No	—	Python version for conda/uv (e.g. 3.11)
env_name	string	No	.venv	Environment directory name

python_env_status

Parameter	Type	Required	Default	Description
project_path	string	Yes	—	Absolute path to the project directory
env_name	string	No	.venv	Environment directory name

python_env_install

Parameter	Type	Required	Default	Description
project_path	string	Yes	—	Absolute path to the project directory
packages	array	No	—	List of package specifiers (e.g. ["numpy>=1.26", "pandas"])
requirements_file	string	No	—	Path to requirements.txt, pyproject.toml, or environment.yml
backend	enum	No	pip	pip, conda, or uv
env_name	string	No	.venv	Environment directory name
index_url	string	No	—	Custom package index (e.g. PyTorch CUDA wheels)

python_env_list

Parameter	Type	Required	Default	Description
project_path	string	Yes	—	Absolute path to the project directory
format	enum	No	table	Output format: table, freeze, or json
outdated	bool	No	false	Show only packages with available updates
filter	string	No	—	Filter packages by name substring
env_name	string	No	.venv	Environment directory name

python_env_run

Parameter	Type	Required	Default	Description
project_path	string	Yes	—	Absolute path to the project directory
code	string	No	—	Inline Python code to execute
script	string	No	—	Path to a .py script (relative to project)
module	string	No	—	Module to run (e.g. pytest, http.server)
args	string	No	—	Additional CLI arguments
timeout	number	No	30	Execution timeout in seconds
env_name	string	No	.venv	Environment directory name

python_env_remove

Parameter	Type	Required	Default	Description
project_path	string	Yes	—	Absolute path to the project directory
env_name	string	No	.venv	Environment directory name
confirm	bool	Yes	—	Must be true to proceed

Development

composer install
composer test
./vendor/bin/phpstan analyse

License

MIT