Python venv Explained — For Java Developers on Windows

1. What is venv? (The Concept)

Think of it like this:
Maven/Gradle project scope → venv in Python
Local Maven repository → venv's site-packages
pom.xml dependencies → requirements.txt
Java version in project → Python version in pyvenv.cfg

The Problem venv Solves

Without venv (danger):

All Python packages install to C:\Python313\Lib\site-packages\
All projects share the same packages
Package version conflicts break your code
Hard to know what packages a project actually needs

With venv (safe):

Each project gets its own site-packages folder
No version conflicts between projects
requirements.txt documents exactly what the project needs
Easy to replicate on another machine (like cloning a Maven project)

What venv Actually Does

venv creates a lightweight copy of Python that points to your project folder:

myenv/
├── Scripts/
│   ├── python.exe      ← Still the system Python binary
│   ├── pip.exe         ← Package manager
│   └── activate.bat    ← Switches environment variables
├── Lib/
│   └── site-packages/  ← YOUR packages go here
└── pyvenv.cfg          ← Config: "Use C:\Python313\ as parent"

2. The venv Workflow

Start a new project

Step 1:
Create venv
python -m venv myenv

↓

Step 2:
Activate venv
myenv\Scripts\activate

↓

Step 3:
Install packages
pip install requests

↓

Step 4:
Save versions
pip freeze > requirements.txt

Resume a project later

Activate venv
myenv\Scripts\activate

↓

Restore packages (new machine)
pip install -r requirements.txt

↓

Code away
All packages available

3. Windows Step-by-Step Setup

Step 1: Open Command Prompt or PowerShell

In VS Code / Cursor: Ctrl + ` → Terminal → PowerShell or cmd

Or press Win + R, type cmd, press Enter

Step 2: Navigate to Your Project Folder

cd C:\Users\YourName\Documents\my_python_project

Step 3: Create Virtual Environment

python -m venv myenv

Takes a few seconds. A new myenv/ folder appears.

Step 4: Activate It

Command Prompt:

myenv\Scripts\activate

PowerShell (if execution policy blocks scripts):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then:

myenv\Scripts\Activate.ps1

Success: Your terminal prompt shows (myenv) at the start.

Step 5: Verify Activation

where python

Should show a path containing myenv\Scripts\python.exe

Step 6: Install Packages

pip install requests numpy pandas

Step 7: Freeze Dependencies

pip freeze > requirements.txt

Lists packages and versions — share this with teammates.

Step 8: Deactivate

deactivate

Back to system Python. The (myenv) prefix disappears.

4. VS Code & Cursor Integration

VS Code Setup

Option 1: Auto-Detection

Create and activate venv (steps 3–4 above)
Open your project folder in VS Code
If prompted to select a Python environment, choose ./myenv/Scripts/python.exe
VS Code remembers this per workspace

Option 2: Manual Selection

Bottom-right: click the Python version indicator
Choose or type ./myenv/Scripts/python.exe

Option 3: settings.json

Ctrl + Shift + P → “Preferences: Open Workspace Settings (JSON)”
Add:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/myenv/Scripts/python.exe"
}

Verify: Open a Python file → click the Python version in the status bar. It should show your venv path.

Cursor Setup

Cursor uses the same VS Code Python extension, so the steps match:

Step 1: Create venv in Terminal

python -m venv myenv
myenv\Scripts\activate

Step 2: Open Project in Cursor

File → Open Folder → select your project

Step 3: Select Python Interpreter

Bottom-right: click Python version → choose ./myenv/Scripts/python.exe

Step 4: Use Cursor's Terminal

Ctrl + ` — the terminal should auto-activate your venv once the interpreter is set.

Tip: With the venv selected, Cursor’s context can see packages you installed — useful when asking it to use project dependencies.

5. Common Windows Problems & Fixes

Problem 1: python: command not found

Error: python: command not found

Solution:

Python not installed or not on PATH
Test with python --version
If it fails, reinstall from python.org
During install, check “Add Python to PATH”

Problem 2: (myenv) does not appear after activation

Diagnosis:

where python

If it shows C:\Python313\python.exe (not your myenv folder), activation failed.

Fixes:

Command Prompt: myenv\Scripts\activate.bat
PowerShell: set execution policy, then myenv\Scripts\Activate.ps1
Git Bash: source myenv/Scripts/activate (forward slashes)

Problem 3: pip installs to the wrong place

Check whether venv is active:

pip --version

Should include myenv\Lib\site-packages. If it shows system Python, activate first.

Problem 4: ModuleNotFoundError but pip list shows the package

Python is running from the wrong interpreter (system, not venv).

Activate: myenv\Scripts\activate
In the IDE: select ./myenv/Scripts/python.exe
Restart the IDE terminal

Problem 5: Works in terminal, fails in IDE

Click Python version (bottom-right)
Confirm it points at ./myenv/Scripts/python.exe
Close and reopen the Python file

Problem 6: PowerShell execution policy

cannot be loaded because running scripts is disabled on this system

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problem 7: No module named venv

Reinstall Python from python.org
During install, keep tcl/tk and IDLE and py launcher checked

6. FAQ

Do I need to activate venv every time?

Yes for a raw terminal. In VS Code/Cursor, configure the interpreter once and the IDE can auto-activate.

Can I rename the venv folder?

Yes. env, .venv, or any name — just update the activation path.

Should I commit venv to Git?

No. Add to .gitignore:

venv/
myenv/
env/
.venv/

Commit requirements.txt. Teammates run pip install -r requirements.txt.

One venv per project or one for all?

One per project. Shared venvs become version hell. Two folders can even use different Python versions at once — see section 10.

venv vs conda?

venv: built-in, lightweight, pip. Best for Python-only work.

conda: separate tool; handles non-Python deps. Common in data science/ML.

Start with venv — enough for most projects.

Multiple venvs in one project?

Technically possible; avoid it. One venv = one environment.

How do I update packages?

pip install --upgrade package-name
python -m pip install --upgrade pip

I accidentally installed into system Python

Activate your venv
Reinstall: pip install package-name
Inside the venv, that copy takes priority

venv vs virtualenv?

Similar idea. venv is built into Python 3.3+. Prefer venv.

What about uv?

uv is a fast modern tool that can create venvs and install deps. For pinning a Python version (e.g. 3.10), use uv python install 3.10 then uv venv --python 3.10 .venv — see section 9.

7. Complete Java → Python Translation

Java / Maven	What it does	Python / venv	What it does
`pom.xml`	Declares dependencies	`requirements.txt`	Lists installed packages
`mvn install`	Downloads to local repo	`pip install -r requirements.txt`	Installs from file
Local Maven repo (~/.m2)	JAR cache	`venv/Lib/site-packages/`	Package cache for this env
`mvn clean`	Removes build artifacts	`deactivate` then delete `myenv`	Removes the environment
`CLASSPATH`	Where .class files live	`PYTHONPATH`	Where .py modules live
Java version in pom	Project Java version	`pyvenv.cfg`	Project Python version
Project-scoped dependency	Only this project	Packages in venv	Only when activated
`mvn dependency:tree`	Shows dependency tree	`pip list`	Shows installed packages

Mental model

Activate venv = enter the project’s Maven scope

pip install X = add X and download it locally

requirements.txt = pom.xml equivalent

site-packages/ = this project’s local repo

Deactivate = leave project scope, back to system

8. Real Example: Web Scraper Project

Scenario: build a scraper with BeautifulSoup.

# Step 1: create project folder
mkdir my_scraper
cd my_scraper

# Step 2: create venv
python -m venv myenv

# Step 3: activate (PowerShell)
myenv\Scripts\Activate.ps1

# Step 4: install dependencies
pip install beautifulsoup4 requests lxml

# Step 5: verify
pip list

# Step 6: write your script in VS Code / Cursor

# Step 7: freeze
pip freeze > requirements.txt

# Teammate setup after clone:
# cd my_scraper
# python -m venv myenv
# myenv\Scripts\activate
# pip install -r requirements.txt

Key insight: Same idea as Maven — everyone builds with the same dependency versions.

9. Real Example: project1 — Pin Python 3.10 with uv

From Week-02 AI Learning: this project targets Python 3.10. A venv cannot change its Python version in place — if you need a different version, recreate it. Prefer .venv and uv for a modern workflow.

1. Set version constraints

In pyproject.toml:

requires-python = ">=3.10"

Or pin to 3.10 only:

requires-python = "==3.10.*"

In .python-version:

3.10

2. Install Python 3.10 (if needed)

python3.10 --version

If that fails:

uv python install 3.10

3. Remove any existing venv

Recreate when switching Python versions:

Remove-Item -Recurse -Force .venv

4. Create a new venv with 3.10

uv venv --python 3.10 .venv

5. Activate and verify

.\.venv\Scripts\activate
python --version

Success: You should see Python 3.10.x.

6. Install dependencies

uv sync

or:

uv pip install -e .

Notes (gotchas)

Prefer >=3.10, >=3.10,<3.11, or ==3.10.* in requires-python — not a bare = "3.10".
pip install python 3.10 does not install Python; use uv python install 3.10 (or the official installer).
uv init creates a project folder, not a virtual environment. Use uv venv for the venv.

Java parallel: requires-python / .python-version ≈ pinning the JDK in pom.xml / toolchain.
uv venv --python 3.10 ≈ creating a project scoped to that JDK — if you change the JDK, you rebuild the environment, you don’t “upgrade in place.”

10. Demo: Two Projects, Two venvs, Two Python Versions

Each project folder owns its own .venv. Those venvs can point at different Python versions at the same time — like two Java projects using JDK 17 and JDK 21 side by side. Activating one never changes the other.

Folder layout

C:\dev\
├── project-a\          ← needs Python 3.10
│   ├── .venv\          ← isolated env for A only
│   ├── .python-version
│   ├── pyproject.toml
│   └── app.py
└── project-b\          ← needs Python 3.13
    ├── .venv\          ← isolated env for B only
    ├── .python-version
    ├── pyproject.toml
    └── app.py

Create both (PowerShell)

Install both interpreters once (if needed), then create a venv inside each project folder:

# Install interpreters (once on the machine)
uv python install 3.10
uv python install 3.13

# --- project-a → Python 3.10 ---
mkdir C:\dev\project-a
cd C:\dev\project-a
Set-Content .python-version "3.10"
uv venv --python 3.10 .venv

# --- project-b → Python 3.13 ---
mkdir C:\dev\project-b
cd C:\dev\project-b
Set-Content .python-version "3.13"
uv venv --python 3.13 .venv

Side-by-side: activate and prove the versions differ

project-a

PYTHON 3.10

Open a terminal in project-a:

cd C:\dev\project-a
.\.venv\Scripts\activate
python --version
# → Python 3.10.x

where python
# → ...\project-a\.venv\Scripts\python.exe

project-b

PYTHON 3.13

Open a second terminal in project-b:

cd C:\dev\project-b
.\.venv\Scripts\activate
python --version
# → Python 3.13.x

where python
# → ...\project-b\.venv\Scripts\python.exe

Proof in one terminal (switch folders):

cd C:\dev\project-a
.\.venv\Scripts\activate
python --version          # 3.10.x
deactivate

cd C:\dev\project-b
.\.venv\Scripts\activate
python --version          # 3.13.x — different project, different Python

Packages installed in project-a\.venv are invisible to project-b, and vice versa. Same rule as two Maven projects with different JDKs and different ~/.m2-scoped deps.

What must stay true

One venv per project folder — never share .venv across projects.
Activate after cd into that project — python then resolves to that folder’s interpreter.
Changing Python version = recreate the venv — do not try to “upgrade” an existing .venv in place.
In the IDE, pick project-a\.venv\Scripts\python.exe for A and project-b\.venv\Scripts\python.exe for B (separate windows/workspaces).

Takeaway: Two project folders → two .venv folders → can run Python 3.10 and 3.13 at the same time without fighting over system Python.

You've got this

venv is simple once the mental switch flips:

venv = Maven-style dependency isolation for Python

Activate → install → freeze to requirements.txt → done. With uv: pin the version → uv venv → uv sync. Each project folder keeps its own .venv — and its own Python version.

← Back to Learning · Next: Python Basics