Virtual Environments

How PPM manages isolated Python environments in polyglot projects

Virtual Environments

PPM automatically manages Python virtual environments to ensure clean, isolated dependency management alongside your JavaScript packages. This page explains how PPM’s virtual environment system works and how to customize it for your needs.

Why Virtual Environments Matter

The Problem

Python’s global package installation can lead to:

• Dependency conflicts between different projects
• Version incompatibilities when switching between projects
• System pollution with packages not needed globally
• Deployment inconsistencies between development and production

PPM’s Solution

PPM automatically creates and manages virtual environments:

✅ Automatic creation when initializing projects
✅ Intelligent activation for all Python operations
✅ Cross-platform compatibility (Windows, macOS, Linux)
✅ Integration with JavaScript workflows
✅ Zero configuration required for most use cases

How It Works

Automatic Environment Creation

When you run ppm init or ppm install, PPM:

1. Detection

   Scans for existing virtual environments:

   • .venv/ directory
   • venv/ directory
   • env/ directory
   • Custom paths specified in configuration
2. Creation

   Creates a new virtual environment if none exists:

   # PPM runs this internally
   python -m venv .venv
   

3. Activation

   Automatically activates the environment for Python operations:

   # Windows
   .venv\Scripts\activate
   
   # Unix/Linux/macOS
   source .venv/bin/activate
   

4. Installation

   Installs Python dependencies within the isolated environment

Environment Lifecycle

PPM manages the complete lifecycle:

Configuration Options

Basic Configuration

Configure virtual environments in project.toml:

[python]
version = "3.11"              # Preferred Python version
venv_dir = ".venv"           # Virtual environment directory  
venv_prompt = "myapp"        # Custom prompt name
system_site_packages = false # Inherit global packages

Advanced Configuration

[python]
# Python version constraints
version = ">=3.9,<4.0"
version_check = "strict"     # strict|warn|ignore

# Virtual environment settings
venv_dir = "environments/dev"
venv_backend = "venv"        # venv|virtualenv|conda
venv_args = ["--copies"]     # Additional arguments

# Environment variables
[python.env]
PYTHONPATH = "./src"
DJANGO_SETTINGS_MODULE = "myapp.settings.local"

Multiple Environments

Define different environments for different use cases:

[environments.development]
[environments.development.python]
venv_dir = ".venv-dev"
version = "3.11"

[environments.production]  
[environments.production.python]
venv_dir = ".venv-prod"
version = "3.11"
system_site_packages = false

[environments.testing]
[environments.testing.python]
venv_dir = ".venv-test"
version = "3.9"  # Test against older Python

Switch between environments:

# Use development environment (default)
ppm install

# Use production environment
ppm install --env production

# Use testing environment  
ppm install --env testing

Environment Management Commands

Creation and Activation

# Create virtual environment (automatic with ppm init)
ppm venv create

# Create with specific Python version
ppm venv create --python 3.10

# Create with custom name
ppm venv create --name myproject-env

# Activate environment (for manual use)
ppm venv activate

# Show activation command for manual use
ppm venv activate --show

Information and Status

# Show current environment info
ppm venv info

# List all environments in project
ppm venv list

# Show Python interpreter path
ppm venv which python

# Show environment variables
ppm venv env

Maintenance

# Clean environment (remove all packages)
ppm venv clean

# Rebuild environment (delete and recreate)
ppm venv rebuild

# Remove environment completely
ppm venv remove

# Upgrade pip and setuptools
ppm venv upgrade

Python Version Management

Version Detection

PPM automatically detects available Python versions:

# Show available Python versions
ppm python versions

# Show current version
ppm python version

# Show version compatibility
ppm python check

Version Selection Priority

PPM uses this order to select Python versions:

1. Project configuration (project.toml)
2. Runtime argument (--python 3.10)
3. Environment variable (PPM_PYTHON_VERSION)
4. pyproject.toml (if present)
5. .python-version file (pyenv compatibility)
6. System default Python

Multiple Python Versions

Work with multiple Python versions:

[environments.python39]
[environments.python39.python]
version = "3.9"
venv_dir = ".venv-py39"

[environments.python310]
[environments.python310.python]  
version = "3.10"
venv_dir = ".venv-py310"

[environments.python311]
[environments.python311.python]
version = "3.11"
venv_dir = ".venv-py311"

Test across versions:

# Install and test with Python 3.9
ppm install --env python39
ppm run test --env python39

# Install and test with Python 3.10  
ppm install --env python310
ppm run test --env python310

# Install and test with Python 3.11
ppm install --env python311
ppm run test --env python311

Integration Patterns

With JavaScript Tools

PPM seamlessly integrates Python virtual environments with JavaScript tooling:

[scripts]
# Start development server (both Node.js and Python)
dev = [
  "npm run dev &",          # Start JavaScript dev server
  "python manage.py runserver"  # Start Python server (in venv)
]

# Run full test suite
test = [
  "npm test",               # JavaScript tests
  "python -m pytest"       # Python tests (in venv)
]

# Build for production
build = [
  "npm run build",          # Build JavaScript assets
  "python setup.py bdist_wheel"  # Build Python package
]

With Docker

Use PPM virtual environments in Docker:

# Dockerfile
FROM python:3.11-slim

# Install Node.js
RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
RUN apt-get install -y nodejs

# Install PPM
RUN curl -fsSL https://install.ppm.dev/install.sh | sh

# Copy project files
COPY project.toml ./
COPY package.json ./

# Install dependencies (PPM creates and manages venv)
RUN ppm install

# Copy application code
COPY . .

# Run application
CMD ["ppm", "run", "start"]

With CI/CD

GitHub Actions example:

# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.9, 3.10, 3.11]
        node-version: [16, 18, 20]
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
    
    - name: Setup Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    
    - name: Install PPM
      run: curl -fsSL https://install.ppm.dev/install.sh | sh
    
    - name: Install dependencies
      run: ppm install
    
    - name: Run tests
      run: ppm run test

Troubleshooting

Common Issues

Virtual environment not activated

Problem: Python packages not found or wrong version used

Solution:

# Check current environment
ppm venv info

# Manually activate if needed
ppm venv activate

# Rebuild environment
ppm venv rebuild

Permission errors on Windows

Problem: Cannot create virtual environment due to permissions

Solution:

# Enable execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or use different directory
ppm init --venv-dir %USERPROFILE%\.venv-myproject

Python version not found

Problem: PPM cannot find specified Python version

Solution:

# Check available versions
ppm python versions

# Use available version
ppm venv create --python 3.10

# Or install Python from python.org

SSL certificate errors

Problem: pip cannot download packages due to SSL errors

Solution:

# Upgrade certificates
ppm venv upgrade

# Or configure pip
ppm run pip config set global.trusted-host pypi.org
ppm run pip config set global.trusted-host pypi.python.org

Debugging Commands

# Show detailed environment information
ppm venv info --verbose

# Show activation commands for manual debugging
ppm venv activate --show

# Test Python environment
ppm run python -c "import sys; print(sys.executable)"
ppm run python -c "import sys; print(sys.path)"

# Check pip configuration
ppm run pip config list

# Show installed packages
ppm run pip list

# Verify virtual environment integrity
ppm venv check

Best Practices

Project Structure

Organize your virtual environments consistently:

my-project/
├── .venv/              # Main development environment
├── .venv-test/         # Testing environment  
├── .venv-prod/         # Production-like environment
├── project.toml        # PPM configuration
├── src/                # Python source code
│   └── myproject/
├── tests/              # Python tests
├── frontend/           # JavaScript/React code
│   ├── src/
│   └── package.json
└── README.md

Environment Naming

Use descriptive names for multiple environments:

[environments.development]
[environments.development.python]
venv_dir = ".venv-dev"

[environments.testing]  
[environments.testing.python]
venv_dir = ".venv-test"

[environments.ci]
[environments.ci.python]
venv_dir = ".venv-ci"

Dependency Management

Keep virtual environments clean:

# Regular maintenance
ppm venv clean        # Remove unused packages
ppm outdated          # Check for updates
ppm audit             # Security scan

# Before important releases
ppm venv rebuild      # Start fresh
ppm install --frozen  # Install exact versions

Team Collaboration

Ensure consistent environments across team:

1. Commit project.toml and ppm.lock
2. Include .venv/ in .gitignore
3. Document any special setup requirements
4. Use exact Python versions in production
5. Test with multiple Python versions in CI

---

PPM’s virtual environment management eliminates the complexity of Python environment setup while maintaining full compatibility with existing Python tooling. The automatic creation and activation ensures your team never has to worry about environment issues again.