> ## Documentation Index
> Fetch the complete documentation index at: https://kaiser.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Steps>
  <Step title="Detection">
    Scans for existing virtual environments:

    * `.venv/` directory
    * `venv/` directory
    * `env/` directory
    * Custom paths specified in configuration
  </Step>

  <Step title="Creation">
    Creates a new virtual environment if none exists:

    ```bash theme={null}
    # PPM runs this internally
    python -m venv .venv
    ```
  </Step>

  <Step title="Activation">
    Automatically activates the environment for Python operations:

    ```bash theme={null}
    # Windows
    .venv\Scripts\activate

    # Unix/Linux/macOS
    source .venv/bin/activate
    ```
  </Step>

  <Step title="Installation">
    Installs Python dependencies within the isolated environment
  </Step>
</Steps>

### Environment Lifecycle

PPM manages the complete lifecycle:

```mermaid theme={null}
graph LR
    A[ppm init] --> B[Create .venv/]
    B --> C[Activate environment]
    C --> D[Install dependencies]
    D --> E[Generate lock file]
    
    F[ppm install] --> C
    G[ppm run python] --> C
    H[ppm run <python-script>] --> C
```

## Configuration Options

### Basic Configuration

Configure virtual environments in `project.toml`:

```toml theme={null}
[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

```toml theme={null}
[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:

```toml theme={null}
[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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```toml theme={null}
[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:

```bash theme={null}
# 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:

```toml theme={null}
[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 theme={null}
# 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:

```yaml theme={null}
# .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

<AccordionGroup>
  <Accordion title="Virtual environment not activated">
    **Problem:** Python packages not found or wrong version used

    **Solution:**

    ```bash theme={null}
    # Check current environment
    ppm venv info

    # Manually activate if needed
    ppm venv activate

    # Rebuild environment
    ppm venv rebuild
    ```
  </Accordion>

  <Accordion title="Permission errors on Windows">
    **Problem:** Cannot create virtual environment due to permissions

    **Solution:**

    ```powershell theme={null}
    # Enable execution policy
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

    # Or use different directory
    ppm init --venv-dir %USERPROFILE%\.venv-myproject
    ```
  </Accordion>

  <Accordion title="Python version not found">
    **Problem:** PPM cannot find specified Python version

    **Solution:**

    ```bash theme={null}
    # Check available versions
    ppm python versions

    # Use available version
    ppm venv create --python 3.10

    # Or install Python from python.org
    ```
  </Accordion>

  <Accordion title="SSL certificate errors">
    **Problem:** pip cannot download packages due to SSL errors

    **Solution:**

    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

### Debugging Commands

```bash theme={null}
# 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:

```toml theme={null}
[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:

```bash theme={null}
# 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.