---

Build a dedicated Python project using VSCode + venv to create a professional Python development environment, integrated with Git version control, so you can develop good habits from day one!

Have you ever encountered these situations?

• “It works on my computer, why not yours?” — Package version conflicts causing chaos in team development.
• “I just updated one package, and the whole project broke!” — Global environment pollution, different projects interfering with each other.
• “Which packages does this project need? I forgot…” — Lack of dependency management making environment reproduction a nightmare.

These pain points are experienced by 90% of Python developers.
The solution is actually simple: virtual environments + project structure + Git version control.

What is a Python Virtual Environment?

A Python virtual environment is an isolated Python execution environment that allows you to create separate environments for different projects on the same machine. Each virtual environment has its own:

• Python binary files
• Package installation directory
• Independent global variables
• Environment variable settings

The benefits of using a virtual environment include:

• Facilitates team collaboration and ensures environment consistency
• Allows different projects to use different versions of Python and packages
• Prevents the system Python environment from being polluted

Virtual Environments vs. Containerization

Although container technologies like Docker can also solve environment isolation issues, virtual environments are more lightweight:

• No need to install Docker
• Fast startup
• Low resource consumption
• Suitable for local development

How to Use a Virtual Environment?

Creating and using a venv is very simple:

# Create a virtual environment
python -m venv my_project_env

# Activate virtual environment (Linux/macOS)
source my_project_env/bin/activate

# Activate virtual environment (Windows)
my_project_env\Scripts\activate

# Install packages
pip install package_name

# Deactivate virtual environment
deactivate

Development Environment

Operating System

• macOS / Linux / Windows are all supported

Python Installation

• Recommended versions: Python 3.9 – 3.12
• Check if Python is installed:

python3 --version

If Python is not installed, download and install it from the official Python website.

Install VSCode

• Download: Visual Studio Code
• Install the Python extension (officially provided by Microsoft)

Git (for version control)

• Check if Git is installed:

git --version

If Git is not installed, download it from the official Git website.

Create a Python Project

Create a project folder
First, create a folder in your working directory, for example:

mkdir my_python_project
cd my_python_project

Project Structure

my_python_project/       # Project root directory
├── my_project_env/      # venv folder (not pushed to Git)
├── app.py               # Main script
├── requirements.txt     # Package dependency list
└── .gitignore           # Git ignore rules

Create a Virtual Environment
In the terminal, enter:

python3 -m venv my_project_env

This will create a my_project_env folder inside your project, containing the Python interpreter and packages specific to the project.

Activate the virtual environment
macOS / Linux:

source my_project_env/bin/activate

Windows（PowerShell）：

my_project_env\Scripts\Activate.ps1

After activation, your terminal prompt will show (my_project_env), indicating that you are now inside the project’s virtual environment.

Open the project in VSCode

code .

• Install the Python extension
• VSCode will detect the virtual environment in my_project_env. Select the correct interpreter in the bottom-left corner.

Create a test file app.py
Add a new file app.py in the project root directory:

print("Hello World from my_project_env!")

Run the program
Make sure your terminal is inside the virtual environment (my_project_env):

python app.py

You will see:

Hello World from my_project_env!

Exit the virtual environment (my_project_env)
In the terminal where the virtual environment is activated, enter:

deactivate

• The (my_project_env) at the beginning of the terminal prompt will disappear.
• You have now returned to the system’s global Python environment.
• The deactivate command works the same way on all operating systems (macOS / Linux / Windows).

Do Not Push the “venv Folder” to Git

• Takes up a lot of space (hundreds of MB)
• Not compatible across different systems
• Can be rebuilt using requirements.txt

After creating a .gitignore file, add the following:

my_project_env/

Save Installed Packages (pip freeze)

Inside the virtual environment, enter:

pip freeze > requirements.txt

It will generate something like this:

PySide6==6.5.2
numpy==1.25.1
pandas==2.0.3

Rebuild the Environment

After someone clones your project:

python3 -m venv my_project_env
source my_project_env/bin/activate # 啟動虛擬環境
pip install -r requirements.txt

If using Windows PowerShell, the command to activate the virtual environment changes to:

.\my_project_env\Scripts\Activate.ps1    # Activate the virtual environment (Windows PowerShell)

This way, you can obtain an identical development environment.

Conclusion

Using VSCode + venv, we have successfully created a clean, isolated, and reproducible Python development environment. By managing code versions with Git, we can avoid the old problems of package version conflicts and global environment pollution.

Remember these key practices:

• Create a separate virtual environment for each project
• Use .gitignore to exclude the virtual environment folder
• Save package versions with pip freeze > requirements.txt
• Reproduce the environment in a new setup with pip install -r requirements.txt

This workflow is not only suitable for beginners but also forms the foundation for professional teams to maintain project stability and portability.

From today onward, you can say goodbye to the awkward “It works on my computer” problem.

---