QVenv - Python Virtual Environment Manager

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

PyPI Package: https://pypi.org/project/qvenv/

Features

• Automatic activation/deactivation (when sourcing qvenv.sh)
• Recursive venv search (searches up to 5 levels deep in subdirectories)
• Automatic Python version detection
• Requirements file detection and installation (requirements.txt, requirements.pip)
• Cross-platform support (Windows, macOS, Linux)
• Environment recreation and rebuilding
• Timestamped logging
• Compatible with bash and zsh

Installation

PyPI Installation (Recommended)

Install qvenv directly from PyPI:

pip install qvenv

or for user installation:

pip install --user qvenv

After installation, the qvenv command will be available globally.

For automatic activation/deactivation (optional): Add this line to your ~/.bashrc or ~/.zshrc:

# Enable qvenv auto-activation
eval "$(pip show -f qvenv | grep qvenv.sh | head -1 | awk '{print "source " $NF}')"

Or manually find and source qvenv.sh from your Python site-packages.

Development Installation (Recommended for Latest Features)

Clone the repository and install using the Makefile:

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

The installation will:

• Make qvenv.py and qvenv.sh executable
• Create a symlink in /usr/local/bin or ~/.local/bin
• Automatically configure your shell for instant activation/deactivation
• Prompt you before making changes to your shell config

After installation, reload your shell:

source ~/.zshrc  # or ~/.bashrc for bash

Makefile Commands

make install    # Install qvenv globally
make uninstall  # Remove qvenv completely
make build      # Build distribution packages
make publish    # Publish to PyPI
make clean      # Remove build artifacts
make help       # Show all commands

Manual Installation

chmod +x qvenv.py qvenv.sh
ln -s "$(pwd)/qvenv.py" /usr/local/bin/qvenv
# Then manually add to your shell config:
echo 'source /path/to/qvenv.sh' >> ~/.zshrc

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 Activate the nearest virtual environment.

# If you sourced qvenv.sh (auto-activation enabled):
qvenv activate                    # Activates instantly! ✨

# Without sourcing qvenv.sh:
eval "$(qvenv activate --quiet)"  # Activate with eval

qvenv deactivate Deactivate the current virtual environment.

# If you sourced qvenv.sh (auto-activation enabled):
qvenv deactivate                  # Deactivates instantly! ✨

# Without sourcing qvenv.sh:
eval "$(qvenv deactivate --quiet)"  # Deactivate with eval

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

activate/deactivate command options:

• -q, --quiet - Output only the command (for use with eval)

Typical Workflow

With Auto-Activation (Recommended)

After sourcing qvenv.sh in your shell config:

# Create a new virtual environment
qvenv make

# Activate it instantly
qvenv activate

# Install dependencies
qvenv install

# Later, rebuild environment if needed
qvenv remake

# Deactivate when done
qvenv deactivate

Without Auto-Activation

# Create a new virtual environment
qvenv make

# Activate with eval
eval "$(qvenv activate --quiet)"

# Install dependencies
qvenv install

# Deactivate with eval
eval "$(qvenv deactivate --quiet)"

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

qvenv searches the current directory and up to 5 levels deep in subdirectories for:

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

Run qvenv make to create a new virtual environment if none exists.

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 MIT License. See the LICENSE file for details.

Related Tools

Part of the GSuite collection of development tools.