Skip to main content

​
Overview

The Virtual Environment configuration options enable automatic creation and management of Python virtual environments. This ensures your project dependencies are isolated from system-wide packages and other projects.

​
Configuration Options

​
usevenv
boolean
default:"1"
Controls whether a virtual environment will be created and used for running Python scripts.Valid values:
  • 1 - Enable virtual environment (recommended)
  • 0 - Disable virtual environment (use system Python)
When enabled, the launcher will:
  1. Check if the virtual environment already exists
  2. Create it if it doesn’t exist
  3. Activate the virtual environment before running your script
Virtual environments are strongly recommended for all Python projects to avoid dependency conflicts.
​
venvname
string
default:"pyvenv"
Specifies the name of the virtual environment directory that will be created in your project folder.Common values:
  • pyvenv - Default generic name
  • venv - Common convention
  • .venv - Hidden directory (recommended for version control)
  • env - Another common convention
  • project-env - Project-specific naming
The virtual environment will be created at .\{venvname}\ relative to the launcher location.
If this directory already exists, the launcher will use the existing virtual environment without recreating it.
​
installrequirementsfile
boolean
default:"1"
Controls whether dependencies from a requirements file should be automatically installed when creating a new virtual environment.Valid values:
  • 1 - Install requirements automatically
  • 0 - Skip requirements installation
Important behavior:
  • Packages are ONLY installed when creating a NEW virtual environment
  • Existing virtual environments are NOT updated
  • This prevents unexpected package updates on every run
To update packages in an existing virtual environment, delete the {venvname} directory and let the launcher recreate it, or manually run pip install -r {requirementsfile} inside the activated environment.
​
requirementsfile
string
default:"requirements.txt"
Specifies the path to the requirements file that contains project dependencies.Valid values:
  • requirements.txt - Standard convention
  • requirements-dev.txt - Development dependencies
  • requirements-prod.txt - Production dependencies
  • %cd%\config\requirements.txt - Relative path to subdirectory
  • C:\shared\requirements.txt - Absolute path
The file should follow the standard pip requirements format:
package-name==1.0.0
another-package>=2.0
This setting is only used when installrequirementsfile is set to 1.

​
Usage Examples

The default configuration works well for most projects: 
::Create and use a virtual environment with automatic dependency installation
set usevenv=1
set venvname=pyvenv
set installrequirementsfile=1
set requirementsfile=requirements.txt
This will:
  1. Create pyvenv\ directory on first run
  2. Install packages from requirements.txt
  3. Activate the environment before running your script

​
Using .venv (Version Control Friendly)

Many developers prefer hidden virtual environment directories: 
::Use .venv directory (commonly added to .gitignore)
set usevenv=1
set venvname=.venv
set installrequirementsfile=1
set requirementsfile=requirements.txt
Add .venv/ to your .gitignore file to keep virtual environments out of version control.

​
Disable Virtual Environment

For simple scripts or when using system-wide packages: 
::Run directly with system Python (not recommended for projects)
set usevenv=0
set venvname=pyvenv
set installrequirementsfile=1
set requirementsfile=requirements.txt
Disabling virtual environments can lead to:
  • Dependency conflicts between projects
  • Difficulty reproducing environments
  • System-wide package pollution

​
Manual Dependency Management

Create the virtual environment but don’t auto-install dependencies: 
::Create venv but handle dependencies manually
set usevenv=1
set venvname=venv
set installrequirementsfile=0
set requirementsfile=requirements.txt
Useful when:
  • You want to manually control when packages are installed
  • You’re testing different package versions
  • Your project doesn’t use a requirements file

​
Multiple Requirements Files

Use different requirements files for different environments:

​
Development

::Development environment with testing tools
set usevenv=1
set venvname=venv-dev
set installrequirementsfile=1
set requirementsfile=requirements-dev.txt

​
Production

::Production environment with minimal dependencies
set usevenv=1
set venvname=venv-prod
set installrequirementsfile=1
set requirementsfile=requirements-prod.txt
Create separate launcher files (e.g., PythonLauncher-Dev.bat, PythonLauncher-Prod.bat) for different environments.

​
Custom Requirements Location

If your requirements file is in a subdirectory: 
::Requirements file in config directory
set usevenv=1
set venvname=venv
set installrequirementsfile=1
set requirementsfile=%cd%\config\requirements.txt

​
Virtual Environment Lifecycle

​
First Run (New Project)

  1. Launcher checks if {venvname}\ directory exists
  2. Directory doesn’t exist → Create new virtual environment
  3. If installrequirementsfile=1, install packages from {requirementsfile}
  4. Activate virtual environment
  5. Run Python script

​
Subsequent Runs (Existing Environment)

  1. Launcher checks if {venvname}\ directory exists
  2. Directory exists → Skip creation and package installation
  3. Activate existing virtual environment
  4. Run Python script
Packages are never automatically updated in existing environments. This prevents unexpected behavior and ensures reproducibility.

​
Updating Dependencies

To update packages in an existing virtual environment:

​
Option 1: Recreate Environment

# Delete the virtual environment directory
rmdir /s /q pyvenv

# Run the launcher again to recreate with updated requirements
PythonLauncher.bat

​
Option 2: Manual Update

# Activate the environment
pyvenv\Scripts\activate.bat

# Update packages
pip install -r requirements.txt --upgrade

# Deactivate
deactivate

​
Requirements File Format

The launcher uses pip to install packages, so your requirements file should follow pip’s format:

​
Basic Format

numpy==1.24.3
pandas>=2.0.0
requests~=2.31.0
flask

​
With Comments

# Core dependencies
numpy==1.24.3
pandas>=2.0.0

# Web framework
flask==2.3.2
requests~=2.31.0

# Development tools
pytest>=7.0.0

​
Advanced Features

# Install from git repository
git+https://github.com/user/repo.git@v1.0.0

# Install from local path
./local-package

# Install with extras
django[bcrypt]==4.2.0

# Constraints and options
--index-url https://custom.pypi.org/simple
-e ./editable-package
Generate a requirements file from your current environment:
pip freeze > requirements.txt

​
Common Configurations

​
Simple Project

set usevenv=1
set venvname=.venv
set installrequirementsfile=1
set requirementsfile=requirements.txt

​
No Dependencies

set usevenv=1
set venvname=venv
set installrequirementsfile=0
set requirementsfile=requirements.txt

​
System-Wide Packages Only

set usevenv=0
set venvname=venv
set installrequirementsfile=0
set requirementsfile=requirements.txt

​
Multiple Environments

::Create separate launchers for dev/prod
::PythonLauncher-Dev.bat:
set usevenv=1
set venvname=venv-dev
set installrequirementsfile=1
set requirementsfile=requirements-dev.txt

::PythonLauncher-Prod.bat:
set usevenv=1
set venvname=venv-prod
set installrequirementsfile=1
set requirementsfile=requirements-prod.txt

​
Troubleshooting

​
Virtual Environment Creation Fails

If venv creation fails:
  1. Check Python installation: Ensure python -m venv works
  2. Verify permissions: Ensure you can create directories in the project folder
  3. Check disk space: Verify sufficient space for the virtual environment
  4. Try system Python: Test with usevenv=0 to rule out venv issues

​
Requirements Installation Fails

If package installation fails:
  1. Check requirements file: Ensure {requirementsfile} exists and is valid
  2. Test manually: Try pip install -r requirements.txt manually
  3. Check network: Ensure you can reach PyPI (https://pypi.org)
  4. Verify package names: Check for typos in package names
  5. Check constraints: Ensure version constraints are satisfiable

​
Packages Not Updating

If new packages in requirements.txt aren’t installed:
This is expected behavior! The launcher only installs packages when CREATING a new virtual environment.
Solutions:
  1. Delete the {venvname} directory and run the launcher again
  2. Manually install: {venvname}\Scripts\activate.bat && pip install -r requirements.txt

​
Wrong Virtual Environment Used

If the launcher uses the wrong environment:
  1. Check venvname: Verify venvname matches your intended directory
  2. Check directory: Look for multiple venv directories in your project
  3. Recreate: Delete the wrong directory and let the launcher recreate it

​
Best Practices

​
Always Use Virtual Environments

Enable usevenv=1 for all projects to maintain isolation: 
set usevenv=1

​
Use Hidden Directories

Use .venv to keep the directory out of sight: 
set venvname=.venv
Add to .gitignore: 
.venv/

​
Pin Dependencies

Use exact versions in requirements.txt for reproducibility: 
numpy==1.24.3
pandas==2.0.2

​
Document Dependencies

Add comments to requirements.txt explaining why packages are needed: 
# Data processing
numpy==1.24.3
pandas==2.0.2

# Web scraping
requests==2.31.0
beautifulsoup4==4.12.2

​
Separate Dev and Prod Requirements

Maintain separate files: requirements.txt (production): 
flask==2.3.2
requests==2.31.0
requirements-dev.txt (development): 
-r requirements.txt
pytest==7.4.0
black==23.3.0

​
Regular Updates

Periodically recreate virtual environments to get security updates: 
rmdir /s /q .venv
PythonLauncher.bat
  • Python Setup - Configure which Python creates the virtual environment
  • Overview - General configuration principles