gcp-hockey-results/motm_app/VIRTUAL_ENV_GUIDE.md

MOTM Application - Virtual Environment Guide

🎯 Why Use Virtual Environments?

Virtual environments provide isolated Python environments for your projects, which means:

• ✅ No conflicts between different project dependencies
• ✅ Reproducible environments across different machines
• ✅ Clean separation of project requirements
• ✅ Easy deployment with exact dependency versions

🚀 Quick Start

Windows Users

1. Open Command Prompt (not PowerShell initially)

2. Navigate to motm_app directory:

   cd path\to\motm_app
   

3. Create virtual environment:

   python -m venv venv
   

   If this fails, try py -m venv venv or find your Python installation

4. Activate virtual environment:

   venv\Scripts\activate.bat
   

   You should see (venv) at the beginning of your command prompt

5. Install dependencies:

   pip install --upgrade pip
   pip install -r requirements.txt
   

6. Run the application:

   python main.py
   

Mac/Linux Users

1. Open Terminal

2. Navigate to motm_app directory:

   cd path/to/motm_app
   

3. Create virtual environment:

   python3 -m venv venv
   

4. Activate virtual environment:

   source venv/bin/activate
   

   You should see (venv) at the beginning of your command prompt

5. Install dependencies:

   pip install --upgrade pip
   pip install -r requirements.txt
   

6. Run the application:

   python main.py
   

📁 What Gets Created

When you create a virtual environment, you'll see a new venv folder:

motm_app/
├── venv/                    # Virtual environment (don't edit this)
│   ├── Scripts/            # Windows activation scripts
│   ├── bin/                # Unix activation scripts  
│   ├── Lib/                # Installed packages
│   └── pyvenv.cfg          # Environment configuration
├── main.py                 # Your application
├── requirements.txt        # Dependencies list
└── ...                     # Other files

🔧 Daily Usage

Starting Your Work Session

1. Activate the virtual environment:

   • Windows: venv\Scripts\activate.bat
   • Mac/Linux: source venv/bin/activate

2. Verify activation - you should see (venv) in your prompt:

   (venv) C:\path\to\motm_app>
   

3. Run your application:

   python main.py
   

Ending Your Work Session

Deactivate when done:

deactivate

The (venv) indicator will disappear

📦 Managing Dependencies

Installing New Packages

1. Activate virtual environment first

2. Install the package:

   pip install package-name
   

3. Update requirements.txt:

   pip freeze > requirements.txt
   

4. Commit the updated requirements.txt to version control

Updating Existing Packages

pip install --upgrade package-name

Viewing Installed Packages

pip list

Removing Packages

pip uninstall package-name

🛠️ Troubleshooting

"Python not found" Error

Windows:

• Install Python from python.org
• During installation, check "Add Python to PATH"
• Try using py command instead of python

Mac/Linux:

• Install Python 3: brew install python3 (Mac) or use package manager
• Use python3 instead of python

Virtual Environment Won't Activate

Windows:

# Try running Command Prompt as Administrator
# Or use PowerShell with:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Permission Errors:

# Remove and recreate
rmdir /s venv          # Windows
rm -rf venv            # Mac/Linux
python -m venv venv    # Recreate

Packages Not Found After Installation

1. Make sure virtual environment is activated (look for (venv))
2. Check if packages are installed: pip list
3. Reinstall requirements: pip install -r requirements.txt

Application Won't Start

1. Activate virtual environment
2. Check all dependencies: pip install -r requirements.txt
3. Test imports: python -c "import flask"
4. Check error messages in the console

🔄 Working with Teams

Sharing Your Environment

1. Commit requirements.txt to version control
2. Don't commit the venv folder (add to .gitignore)

Setting Up on New Machine

1. Clone the repository
2. Create virtual environment: python -m venv venv
3. Activate it: venv\Scripts\activate.bat (Windows) or source venv/bin/activate (Unix)
4. Install dependencies: pip install -r requirements.txt

🚀 Deployment Considerations

Production Environment

• Use the same Python version as development
• Install exact dependencies: pip install -r requirements.txt
• Set up environment variables for database connections
• Use a proper web server (nginx, Apache)
• Consider using Docker for containerization

Docker Example

FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "main.py"]

💡 Best Practices

1. Always use virtual environments for Python projects
2. Activate before working on the project
3. Keep requirements.txt updated when adding packages
4. Use descriptive commit messages when updating dependencies
5. Test your application after installing new packages
6. Document any special setup requirements

🆘 Getting Help

If you're still having issues:

1. Check Python version: Should be 3.7 or higher
2. Verify virtual environment: Should be activated (see (venv) in prompt)
3. Review error messages: Look for specific error details
4. Test step by step: Create a simple test script to verify Python works
5. Check internet connection: Required for installing packages

---

Remember: The virtual environment isolates your project dependencies from your system Python installation, making your project more reliable and portable! 🎉