What you'll learn

  1. Quick answer
  2. The problem it solves
  3. The four commands
  4. requirements.txt makes it reproducible
  5. pip commands worth knowing
  6. The errors you will actually hit
  7. FAQ

Quick Answer

Run python -m venv venv to create an isolated environment, activate it, then pip install inside it. Freeze your dependencies to requirements.txt and commit that file, not the venv folder itself.

The problem it solves

Install packages globally and every project shares one set. Project A needs version 1.0 of a library; project B needs version 2.0, which changed a function name. Installing one breaks the other, and there is no way to have both.

It gets worse in a team or a submission. Your code works, your classmate's identical code does not, and the difference is an invisible version mismatch that neither of you can see because neither of you wrote it down.

A virtual environment gives each project its own private copy of the interpreter's package directory. Two projects, two sets of packages, no interference.

The four commands

Create it — run this once, in your project folder:

python -m venv venv

That makes a venv/ folder holding the isolated environment. The name is conventional, not required.

Activate it — every time you open a new terminal:

# Windows
venv\Scripts\activate

# macOS / Linux / Git Bash
source venv/bin/activate

Your prompt gains a (venv) prefix. That prefix is the signal that python and pip now refer to the project's private copies.

Install — normally, but now scoped to this project:

pip install requests pandas

Deactivate — when you are done: deactivate.

The single most common mistake is forgetting to activate, installing into the global environment, and then getting ModuleNotFoundError despite having "just installed it". Check for the (venv) prefix before installing anything.

requirements.txt makes it reproducible

The environment lives on your machine. To let anyone else reproduce it, record what is in it:

pip freeze > requirements.txt

That writes every installed package with its exact version. Anyone else then runs:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

and has an identical environment. This is what makes a project genuinely shareable, and it is the difference between a repository someone can run and one they give up on.

Commit requirements.txt. Do not commit the venv/ folder — it contains thousands of files, it is specific to your operating system, and it is regenerable in one command. Add it to .gitignore immediately:

venv/
__pycache__/
*.pyc
.env

A committed venv is one of the most common giveaways of an inexperienced repository, and it makes the project unusable on any other platform.

pip commands worth knowing

  • pip install package — latest version
  • pip install package==1.2.3 — an exact version
  • pip install -U package — upgrade
  • pip uninstall package — remove
  • pip list — what is installed here
  • pip show package — version, location and dependencies

Two habits worth adopting. Prefer python -m pip install ... over bare pip, because it guarantees you are using the pip belonging to the Python you think you are using — on machines with several Pythons installed, bare pip is a common source of confusion.

And never run pip install with administrator rights to fix a permissions error. That error usually means you are not in a virtual environment, and installing system-wide as an administrator makes the problem permanent rather than fixing it.

The errors you will actually hit

  • ModuleNotFoundError right after installing. The environment is not activated, or your editor is using a different interpreter. In VS Code, pick the interpreter from the venv via the command palette — see VS Code setup.
  • 'activate' is not recognised. Wrong path for your shell. Windows uses venv\Scripts\activate; everything else uses venv/bin/activate.
  • Permission denied on install. Almost always means you are installing globally. Activate the environment instead of escalating privileges.
  • The venv stops working after you move or rename the folder. Paths inside it are absolute. Delete it and recreate from requirements.txt — that takes seconds and is exactly why you keep that file.

Frequently Asked Questions

Do I need a virtual environment for every project? Yes, as a habit. It takes seconds to create and prevents version conflicts that are painful to diagnose later. The only exception is a throwaway script using nothing beyond the standard library.
What is the difference between venv and virtualenv? venv ships with Python 3 and covers almost all needs. virtualenv is a separate package that predates it and offers extra features. For new projects, use the built-in venv.
Should I commit the venv folder to git? No. It holds thousands of platform-specific files and is fully regenerable from requirements.txt. Add venv/ to .gitignore and commit requirements.txt instead.
Why does my editor say the module is missing when the terminal works? The editor is using a different Python interpreter. Select the one inside your venv folder in the editor's interpreter settings, and the error will clear.
What about conda? conda does the same job and additionally manages non-Python dependencies, which is why it is popular in data science. For general Python work venv and pip are lighter and more universal; use conda when a scientific package is difficult to install otherwise.