Python Virtual Environments Explained

A virtual environment is a private folder of packages belonging to one project. Install something inside it and only that project sees it.

python -m venv .venv          # create it
.venv\Scripts\activate        # activate it (Windows)
source .venv/bin/activate     # activate it (macOS / Linux)
pip install requests          # installs into this project only

That is the whole idea. The rest of this page is why it matters and what goes wrong.

The problem it solves#

Without one, every pip install goes into a single shared pile used by every Python project on your machine. That is fine until it is not:

• Project A needs version 1 of a library. Project B needs version 3. Only one can be installed.
• You upgrade a package for a new project, and an old project stops working.
• You want to hand your project to someone else and cannot say which of your ninety installed packages it actually needs.
• On some systems, installing globally needs administrator rights or interferes with tools the operating system uses.

A virtual environment gives each project its own pile. The projects stop being able to break each other.

Creating one#

From inside your project folder:

python -m venv .venv

That creates a .venv folder containing a private copy of Python and a private site-packages. The leading dot is only a naming convention — it keeps the folder out of the way and is what most tools expect.

On macOS and Linux you may need python3 -m venv .venv.

Activating it#

You know it worked because your prompt gains a prefix:

(.venv) C:\projects\my-app>

That prefix is the whole signal. If it is not there, you are not in the environment and pip install is going somewhere else.

To leave:

deactivate

Installing packages#

With the environment active, install normally:

python -m pip install requests
python -m pip list

python -m pip rather than plain pip guarantees you are installing for the interpreter that will actually run your code. It is the single habit that prevents most “I installed it but it says no module named” confusion.

requirements.txt#

Recording what your project needs is what makes it runnable by anyone else, including you on a different machine.

python -m pip freeze > requirements.txt

That writes a file listing every installed package and its exact version:

certifi==2026.1.31
charset-normalizer==3.4.1
idna==3.10
requests==2.32.3
urllib3==2.3.0

Someone else then recreates your setup in two commands:

python -m venv .venv
python -m pip install -r requirements.txt

Regenerate the file whenever you add a package, and commit it. It is small, it is text, and it is the difference between a project that runs and one that does not.

Never commit the environment itself#

The .venv folder is thousands of files, specific to your operating system, and completely rebuildable from requirements.txt. Add it to .gitignore before your first commit:

.venv/
__pycache__/
*.pyc
.env

See Git and GitHub explained.

Making VS Code use it#

VS Code keeps its own interpreter setting, separate from whatever your terminal has activated. If it is pointing elsewhere you get red underlines on imports that run perfectly well.

1. Press Ctrl + Shift + P
2. Run Python: Select Interpreter
3. Choose the one showing .venv

The selected interpreter appears in the status bar at the bottom. New terminals you open inside VS Code will then activate it automatically. More in VS Code problems beginners hit.

Do you need one on day one?#

Honestly, no. If you are writing single-file scripts with no external packages, a virtual environment adds a step and solves a problem you do not have yet.

Start using them when either of these becomes true:

• You are installing packages with pip
• You have more than one project on the go

That usually lands somewhere around your second or third real project, which is exactly the right time.

Where to go next#

• Reading and writing files in Python
• Git and GitHub explained — what to commit and what to ignore
• VS Code problems beginners hit