qvenv 1.0.0

A command-line tool for managing Python virtual environments

QVenv - Python Virtual Environment Manager

A command-line tool for managing Python virtual environments with automatic requirements detection and installation.

Features

• Automatic Python version detection
• Requirements file detection and installation (requirements.txt, requirements.pip)
• Cross-platform support (Windows, macOS, Linux)
• Environment activation helpers
• Environment recreation and rebuilding
• Timestamped logging

Installation

Run the installation script to create a global symlink:

git clone https://github.com/GriffinCanCode/QVenv.git
cd QVenv
./install.sh

The script will automatically:

• Make qvenv.py executable
• Create a symlink in /usr/local/bin or ~/.local/bin
• Provide instructions if PATH configuration is needed

Manual Installation

chmod +x qvenv.py
ln -s "$(pwd)/qvenv.py" /usr/local/bin/qvenv

Usage

Commands

qvenv make [path] Create a new virtual environment.

qvenv make                    # Creates ./venv
qvenv make myenv              # Creates ./myenv
qvenv make myenv -f           # Force recreate if exists
qvenv make myenv --complete   # Create and install requirements

qvenv activate Display activation instructions for the nearest virtual environment.

qvenv activate

qvenv deactivate Display deactivation instructions.

qvenv deactivate

qvenv install Install requirements from requirements.txt or requirements.pip into the existing virtual environment.

qvenv install

qvenv build Alias for qvenv install. Installs requirements into the existing virtual environment.

qvenv build

qvenv remake Remove and recreate the virtual environment with fresh packages from requirements file.

qvenv remake

Options

make command options:

• path - Path for the virtual environment (default: venv)
• -f, --force - Force recreation if environment already exists
• --complete - Detect and install requirements after creation

Typical Workflow

# Create a new virtual environment
qvenv make

# Activate it (copy and run the command shown)
source venv/bin/activate

# Install dependencies
qvenv install

# Later, rebuild environment if needed
qvenv remake

Requirements Detection

The tool searches for requirements files in this order:

1. requirements.txt
2. requirements.pip

The first available file will be used for package installation.

Platform Support

Unix and macOS

• Uses python3 by default
• Activation: source venv/bin/activate
• Symlink location: /usr/local/bin/qvenv or ~/.local/bin/qvenv

Windows

• Falls back to python if python3 is unavailable
• Activation: venv\Scripts\activate
• Manual PATH configuration may be required

Prerequisites

• Python 3.6 or higher
• Python venv module (typically included with Python)
• Write permissions for the target directory

Troubleshooting

Python venv module not available

python3 -m pip install --user virtualenv

Permission denied during installation

sudo ./install.sh

Or manually specify a user directory:

ln -s "$(pwd)/qvenv.py" "$HOME/.local/bin/qvenv"
export PATH="$PATH:$HOME/.local/bin"

Virtual environment not found

Ensure you're in a directory containing one of these:

• .venv
• venv
• .env
• env
• virtualenv
• .virtualenv

Contributing

Contributions are welcome. Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/feature-name)
3. Commit your changes (git commit -m 'Add feature')
4. Push to the branch (git push origin feature/feature-name)
5. Open a Pull Request

License

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

Related Tools

Part of the GSuite collection of development tools.