Python Virtual Environments and pip: One Project, One Environment

Every Python project should have its own virtual environment. Not most projects. Every one. A virtual environment is a folder that holds its own copy of the Python interpreter settings and its own installed packages, so what you install for one project stays in that project.

Why this matters

Without virtual environments, every project on your computer shares one set of packages. Project A needs version 1 of a library. Project B needs version 2. You upgrade for B, and A breaks. Nothing in A changed, so the error makes no sense when you see it weeks later.

It gets worse on Linux and macOS, where the system itself uses Python. Installing packages into the system Python can break tools the operating system depends on. That is why newer Linux versions refuse pip install outside an environment and show an "externally-managed-environment" error. That error is not a bug. It is the system protecting itself.

First, check which Python you have

Before creating anything, confirm the version. Virtual environments use whatever Python created them.

python3 --version

Python 3...

On Windows, the command is usually py --version or python --version. If you get "not found", go back to the installation lesson in Python for Beginners. Everything below assumes Python 3.9 or newer.

Create the environment

Go to your project folder and run:

python3 -m venv .venv
ls .venv

bin
include
lib...
pyvenv.cfg

.venv is just a folder name. You can call it anything, but .venv is the common convention, and editors like VS Code find it automatically. On Windows, you will see Scripts instead of bin.

Activate it

Activating means your terminal uses the environment's Python and pip instead of the system ones, until you close the terminal or run deactivate.

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (Command Prompt)
.venv\Scripts\activate.bat

Your prompt usually changes to show (.venv) at the start. Don't trust the prompt alone. Check where Python is coming from:

source .venv/bin/activate
python -c "import sys; print(sys.prefix)"

.../.venv

If the path ends in your project's .venv folder, you are inside the environment. If it shows something like /usr or C:\Program Files\Python312, you are not.

Install packages with python -m pip

With the environment active, install what the project needs:

source .venv/bin/activate
python -m pip install --quiet requests
python -m pip list

Package            Version
------------------ ---------...
requests           2...

Use python -m pip instead of plain pip. It guarantees the package goes into the Python you are actually running. Plain pip can belong to a different Python that happens to be first on your PATH, and then you install into one place and run from another. That mismatch is the most common reason behind "I installed it, but it says No module named...".

Proof that the environments are separate

Create a second environment and check for the same package:

python3 -m venv other-env
other-env/bin/python -c "import requests"

Traceback (most recent call last):
  File "<string>", line 1, in <module>
...ModuleNotFoundError: No module named 'requests'

Same computer, same Python version, different environment. requests exists in the first one and not in the second. That is the whole point.

A real-world example

You maintain two scripts. One is an old reporting script that needs an old version of a library. The other is a new project that needs the newest version of the same library. Without environments, you can only have one version installed, so one of the two is always broken. With environments, each folder has its own .venv and its own version, and you never have to think about it again.

What not to do with the .venv folder

• Don't commit it to Git. Add .venv/ to .gitignore. It is big, and it contains paths specific to your computer.
• Don't copy or move it. An environment remembers where it was created. If you move the project folder, delete .venv and create a new one.
• Don't edit files inside it. If something inside is broken, delete the folder and recreate it. It takes a minute.

Troubleshooting

• "No module named venv" (Debian/Ubuntu): the venv module is a separate system package there. Install python3-venv with your package manager.
• Installed a package but the import fails: check sys.prefix as shown above. You are probably running a different Python than the one you installed into.
• VS Code ignores the environment: open the Command Palette, choose "Python: Select Interpreter" and pick the one inside .venv.

What happens if you skip this step

Nothing, at first. Your first project works. Your second project works too. Then you upgrade something for the third project, and the first one stops working, and you don't connect the two because months passed in between. Creating an environment takes one command. Untangling a shared global install can take a whole afternoon.

If you deleted your .venv folder right now, could you rebuild it with exactly the same packages?