Flask Development Environment: Virtual Environment Setup and Dependency Management

Why Virtual Environments Are Needed?¶

When developing Python projects, we often encounter scenarios where different projects require different versions of dependency libraries. For example, Project A may need Flask 2.0, while Project B requires Flask 1.0. If we install these directly into the system-wide Python environment, upgrading or downgrading Flask could break other projects. Virtual environments isolate the Python runtime environment for different projects, allowing each project to have its own independent “small repository” without interference.

1. Choosing a Virtual Environment Tool: venv (Built-in with Python)¶

Python 3.3+ includes a built-in virtual environment tool venv, which requires no additional installation and is ideal for beginners.

2. Setting Up a Virtual Environment (Using venv as an Example)¶

Step 1: Create a Project Directory¶

First, create a new folder (e.g., flask_demo) in your desired project location:
- Windows: Open Command Prompt (CMD) or PowerShell and run:

  mkdir flask_demo
  cd flask_demo

• Mac/Linux: Open Terminal and run:

  mkdir flask_demo
  cd flask_demo

Step 2: Create the Virtual Environment¶

In the project directory, execute the following command to create a virtual environment (named venv; this name can be customized):

python -m venv venv

• If both Python 2 and Python 3 are installed, use python3 -m venv venv to explicitly use Python 3.
• After execution, a venv folder will appear in the project directory, containing the isolated Python environment.

3. Activating the Virtual Environment¶

A virtual environment must be activated before use. Activation commands vary by operating system:

Windows (CMD/PowerShell):¶

• CMD:

  venv\Scripts\activate.bat

• PowerShell:

  venv\Scripts\Activate.ps1

After activation, the command line will show (venv), indicating the virtual environment is active.

Mac/Linux:¶

source venv/bin/activate

The (venv) prefix will appear in the command line.

4. Installing Dependencies: Flask¶

With the virtual environment active, install Flask (it will only be installed in the current virtual environment):

pip install flask

• If pip or pip3 is outdated, upgrade first: pip install --upgrade pip.

5. Verifying Flask Installation¶

After installation, verify success with:

flask --version

If output like Flask 2.3.3, Python 3.9.7 appears, the installation is successful.

6. Dependency Management: Exporting and Restoring¶

Exporting Dependencies (Generating requirements.txt)¶

To share or deploy the project, export all dependencies to requirements.txt:

pip freeze > requirements.txt

A requirements.txt file will be created, containing lines like:

Flask==2.3.3
Werkzeug==2.3.7
Jinja2==3.1.2
...

Restoring Dependencies (Installing from requirements.txt)¶

To recreate the environment elsewhere, activate the virtual environment and run:

pip install -r requirements.txt

This installs all dependencies in one command.

7. Deactivating the Virtual Environment¶

To exit the virtual environment, run:

deactivate

The (venv) prefix will disappear, returning to the system-wide Python environment.

8. Common Issues and Solutions¶

1. Activation Commands Differ by OS:
   - Windows CMD: venv\Scripts\activate.bat; PowerShell: venv\Scripts\Activate.ps1 (if scripts are blocked: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser).
   - Mac/Linux: source venv/bin/activate.

2. What if the Virtual Environment is Corrupted?
   Delete the venv folder and recreate it:

   rm -rf venv  # Mac/Linux
   # OR delete via file explorer on Windows
   python -m venv venv  # Recreate

3. Why Distinguish pip and pip3?
   - pip typically maps to Python 2, and pip3 to Python 3. Use python -m pip to ensure compatibility with the current Python version (e.g., python -m pip install flask).

By following these steps, you’ve mastered the core skills for Flask development: environment isolation, dependency installation, and version management. In subsequent development, simply activate the virtual environment and run pip install to avoid dependency conflicts, ensuring project stability and reproducibility.