Use Virtual Environments for Python

Different Python projects need different packages, and sometimes different versions of the same package. Without isolation, installing a package for one project can break another. Virtual environments solve this by giving each project its own Python environment.

This article assumes you know how to install packages with pip and have at least a single-file Python project to work with.

What a virtual environment is

A virtual environment is a folder that contains a copy of the Python interpreter and its own site-packages directory. When you activate the environment, any packages you install go into that folder, not into your global Python installation.

Think of it as a clean room for each project. Project A can use requests version 2.28 and Project B can use requests version 2.32, and they never interfere with each other.

Without virtual environments, all packages go into one global location. Install something for one project and it affects every other Python script on your machine.

Create a virtual environment

Python includes a built-in module called venv for creating virtual environments. Open a terminal, navigate to your project folder, and run:

bash

python -m venv .venv

On systems where Python 3 uses python3:

bash

python3 -m venv .venv

This command creates a folder called .venv inside your project directory. The dot at the start keeps it hidden on macOS and Linux (similar to .git folders). You can name it anything, but .venv is the most common convention.

The .venv folder contains:

• A copy of the Python interpreter
• A lib/ directory with site-packages for installed packages
• Activation scripts for different shells
• pip, the package installer

The folder is typically a few megabytes. You can safely delete and recreate it at any time because it contains no project code, only the environment.

Activate the virtual environment

Creating the environment is not enough. You must activate it so your terminal uses the isolated Python instead of the global one.

macOS and Linux:

bash

source .venv/bin/activate

Windows (Command Prompt):

plaintext

.venv\Scripts\activate

Windows (PowerShell):

plaintext

.venv\Scripts\Activate.ps1

After activation, your terminal prompt changes to show the environment name:

plaintext

(.venv) user@computer:~/projects/number-guesser$

This is the visual cue that the environment is active. Now python and pip commands use the virtual environment.

Verify the environment is active

Check which Python you are using:

bash

which python

On macOS/Linux, this should point to .venv/bin/python inside your project. On Windows, use where python instead.

Also check pip:

bash

python -m pip --version

The output should show pip installed inside your .venv folder.

Install packages inside the environment

With the environment active, install packages normally:

bash

python -m pip install requests

The package installs into .venv/lib/site-packages and is available only when this environment is active. Other projects on your machine do not see it.

Verify with:

bash

python -m pip list

Save the package list for your project:

bash

python -m pip freeze > requirements.txt

This records the exact versions, which is important when you share the project or come back to it later.

Deactivate the environment

When you are done working on the project, deactivate:

bash

deactivate

Your terminal prompt returns to normal. The python command now points to your global installation again.

Deactivation does not delete anything. Your .venv folder and all installed packages remain intact. Reactivate whenever you return to the project.

Recreate an environment from requirements.txt

If you clone a project from GitHub or move to a new computer, you do not copy the .venv folder. You recreate it:

bash

git clone https://github.com/user/number-guesser.git
cd number-guesser
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

This gives you an identical environment with the exact same package versions the project was built with.

Add .venv to .gitignore

Never commit the .venv folder to version control. It is large, platform-specific, and can be recreated from requirements.txt. Create a .gitignore file in your project root and add:

plaintext

.venv/
__pycache__/

The __pycache__/ entry ignores compiled bytecode caches that Python generates. These should also stay out of version control. For more on bytecode, see how Python runs your code.

Common workflows

Starting a new project:

bash

mkdir my-project
cd my-project
python -m venv .venv
source .venv/bin/activate

Returning to an existing project:

bash

cd my-project
source .venv/bin/activate

Adding a new dependency:

bash

# Make sure the environment is active
python -m pip install pandas
python -m pip freeze > requirements.txt

Switching between projects:

bash

# In project A
deactivate
cd ../project-b
source .venv/bin/activate

Always deactivate one environment before activating another. Having two environments active in the same terminal is not possible, but it is easy to forget which one is active. Check your terminal prompt.

When not to use a virtual environment

For a quick one-off script that you plan to delete after running it once, a virtual environment is unnecessary. The same goes for experimenting in the interactive REPL.

But any project you plan to keep, share, or work on for more than a day deserves a virtual environment. The overhead is tiny -- one command to create, one to activate -- and it prevents hours of debugging mysterious package conflicts later.

Editor integration

Most editors can detect virtual environments and activate them automatically. In VS Code, open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P), run "Python: Select Interpreter", and choose the path inside .venv. After that, running code from the editor uses the virtual environment automatically.

In PyCharm, the IDE usually detects and offers to use a .venv folder when you open a project. Accept the prompt and PyCharm handles activation behind the scenes.

Next steps

With virtual environments set up, you have all the tools needed for a professional Python workflow. The next article covers how to debug installation problems, and after that, set up your complete Python workspace for daily coding.

When your environment is ready, move on to Python syntax and indentation to start learning the language itself.