What a virtual environment does and why you need one

A virtual environment is a folder on your computer that holds a separate copy of Python and its packages, isolated from the rest of your system. When you create one, you get a self-contained workspace where you can install packages without affecting your main Python installation or other projects.

The practical reason: different projects need different versions of the same package. Project A might need Django 3.2, while Project B needs Django 4.0. Without virtual environments, you'd have to uninstall and reinstall packages constantly. With a virtual environment for each project, both versions sit side by side without conflict.

Virtual environments also make your projects portable. When you share code or move it to another computer, the virtual environment keeps track of exactly which packages you used, so the code runs the same way everywhere.

Key Takeaways

  • Create a virtual environment by running python -m venv project_name in your terminal, which creates a folder containing an isolated Python installation.
  • Activate the environment with source project_name/bin/activate on Mac or Linux, or project_name\Scripts\activate on Windows.
  • Once activated, pip install package_name installs packages only into that environment, not your system Python.
  • Save your project's package list with pip freeze > requirements.txt, then recreate it elsewhere with pip install -r requirements.txt.
  • Deactivate the environment by typing deactivate to return to your system Python.

Creating a virtual environment from the command line

Open your terminal or command prompt and navigate to the folder where you want your project to live. Then run this command:

python -m venv my_project

Replace my_project with whatever you want to name your environment folder. Python will create a new folder with that name and fill it with the files needed to run Python in isolation. This takes a few seconds and creates no visible output if it succeeds.

On Windows, use python. On Mac or Linux, you might need python3 instead, depending on how Python was installed on your system. If you're unsure which one to use, try python --version first to see what you have.

Activating the environment so you can use it

Creating the environment is only half the work. You also need to activate it, which tells your terminal to use the Python inside that folder instead of your system Python.

On Mac or Linux, run this:

source my_project/bin/activate

On Windows, run this:

my_project\Scripts\activate

After you run the activation command, your terminal prompt will change. You'll usually see the environment name in parentheses at the start of the line, like (my_project) $. That tells you the environment is active. From this point on, any package you install with pip goes into this environment only.

Installing packages into your virtual environment

With the environment activated, use pip install as normal. For example:

pip install requests

The requests package will install into your virtual environment, not into your system Python. You can verify this by running pip list, which shows only the packages in the current environment.

If you need a specific version of a package, you can specify it:

pip install django==4.0

The double equals sign pins the package to that exact version. This is useful when you know your code works with a particular version and you want to avoid surprises from updates.

Saving and sharing your package list

When your project is ready to share or move to another computer, you need a record of which packages you installed. Run this command while your environment is still active:

pip freeze > requirements.txt

This creates a file called requirements.txt that lists every package in your environment and its version number. The file is plain text and looks like this:

requests==2.28.1 django==4.0 flask==2.2.0

When someone else (or you on a different computer) wants to run your project, they create a new virtual environment, activate it, and run:

pip install -r requirements.txt

Pip reads the file and installs every package at the exact version you specified. This ensures the code runs the same way everywhere.

Deactivating the environment when you're done

When you finish working on a project, deactivate the environment by typing:

deactivate

Your terminal prompt will return to normal, and you're back to using your system Python. You can activate the same environment again later by running the activation command again — the environment folder stays on your computer until you delete it.

You don't need to deactivate before switching to a different project. You can activate a different environment, and the new one takes over. But it's good practice to deactivate when you're truly done, to avoid confusion about which environment is active.

Troubleshooting common issues

If you run a Python script and it can't find a package you installed, the environment probably isn't active. Check your terminal prompt — if you don't see the environment name in parentheses, activate it again.

On Windows, if you get an error about execution policies when you try to activate, you may need to run PowerShell as administrator. Alternatively, use the older Command Prompt instead of PowerShell, which usually doesn't have this restriction.

If python -m venv doesn't work, your Python installation might not include the venv module. On some Linux systems, you need to install it separately. For example, on Ubuntu or Debian, run sudo apt install python3-venv first, then try creating the environment again.

Frequently Asked Questions

Do I need a virtual environment for every project?

Not strictly, but it's a good habit. For small scripts or learning exercises, you can skip it. For anything you plan to keep, share, or expand, a virtual environment saves you from package conflicts later and makes your code reproducible on other machines.

Can I delete a virtual environment and create a new one?

Yes. Simply delete the environment folder (for example, rm -r my_project on Mac or Linux, or delete the folder in Windows Explorer). As long as you saved your requirements.txt file, you can recreate the same environment anywhere by running python -m venv my_project and then pip install -r requirements.txt.

What's the difference between venv and virtualenv?

venv is built into Python 3.3 and later, so you don't need to install anything extra. virtualenv is an older third-party tool that does the same thing. For most people, venv is simpler and sufficient.

Can I move a virtual environment folder to a different location?

It's possible but not recommended, because the paths inside the environment are often absolute. It's safer to delete the environment, move your project folder, and create a new environment in the new location using your requirements.txt file.

How do I know which packages are installed in my environment?

Run pip list while the environment is active. This shows every package and its version. You can also look at requirements.txt if you created one, though pip list shows packages you installed indirectly as dependencies too.