How to Create a Python Virtual Environment: Complete Guide

A Python virtual environment gives one project its own installed packages. That sounds simple, but it solves one of the most frustrating problems in Python: two projects needing different versions of the same library.

For example, an older application may require one version of Django while a new project needs another. Installing everything globally can create conflicts. A virtual environment keeps dependencies separated, so changing one project does not unexpectedly break another.

Python includes a built-in tool called venv. You do not need a separate package to create a basic environment.

What is a virtual environment?

A virtual environment is an isolated directory containing a Python interpreter and its project-specific packages. When it is activated, commands such as python and pip point to that environment instead of the system-wide installation.

A typical project can look like this:Copy

my_project/
├── .venv/
├── app.py
└── requirements.txt

The .venv folder contains generated environment files. It should usually not be committed to Git because it is platform-specific and can become large. Commit the dependency list instead.

Check your Python installation

Open a terminal and run:Copy

python --version

On some Windows installations, use:Copy

py --version

On macOS and Linux, python3 may be the correct command:Copy

python3 --version

If Python is not found, install Python and make sure it is available on your system path. On Windows, selecting the option to add Python to PATH during installation usually prevents many command-line issues.

Create a virtual environment on Windows

Move into your project folder:Copy

cd path\to\my_project

Create the environment:Copy

py -m venv .venv

If the py launcher is unavailable, try:Copy

python -m venv .venv

The command creates a folder called .venv. You can choose another name, but .venv is widely recognised by editors and developers.

Create a virtual environment on macOS or Linux

Open a terminal and move into your project:Copy

cd path/to/my_project

Create the environment:Copy

python3 -m venv .venv

If your system uses python for Python 3, this also works:Copy

python -m venv .venv

Activate the environment

On Windows PowerShell:Copy

.venv\Scripts\Activate.ps1

On Windows Command Prompt:Copy

.venv\Scripts\activate.bat

On macOS or Linux:Copy

source .venv/bin/activate

After activation, your terminal usually shows (.venv) at the beginning of the prompt. Confirm that Python points to the environment:Copy

python -c "import sys; print(sys.executable)"

The output should contain your project’s .venv directory.

Install packages inside the environment

Once activated, install a package normally:Copy

python -m pip install requests

Using python -m pip is safer than calling pip directly because it ensures pip belongs to the Python interpreter you selected.

Check installed packages:Copy

python -m pip list

Show details for one package:Copy

python -m pip show requests

Save dependencies in requirements.txt

When a project works, record its dependencies:Copy

python -m pip freeze > requirements.txt

Another developer can recreate the environment with:Copy

python -m pip install -r requirements.txt

For a small project, requirements.txt is practical. Larger projects may benefit from a dedicated dependency manager and a lock file, but the basic workflow remains useful everywhere.

Deactivate the environment

When you finish working, run:Copy

deactivate

This returns your terminal to the system Python. Deactivation does not delete the environment or uninstall packages.

Configure your code editor

If your editor reports that an installed package cannot be imported, it may be using the wrong interpreter. In VS Code, open the Command Palette and choose Python: Select Interpreter, then select the interpreter inside .venv.

The exact interface differs between editors, but the principle is the same: choose the Python executable inside the project environment. Restarting the editor can help it refresh package information.

Fix: “No module named venv”

Some Linux distributions split the venv module into a separate system package. If python3 -m venv .venv fails with a message about ensurepip or the virtual environment module, install the package provided by your distribution, then run the command again.

The package name varies by operating system and Python version, so use your distribution’s official documentation rather than copying a command for a different system.

Fix: PowerShell execution policy error

PowerShell may block activation scripts and display an execution-policy error. You can avoid activation and call the environment’s Python directly:Copy

.venv\Scripts\python.exe -m pip install requests

This works because activation is a convenience that changes command lookup; it is not required for the environment to function.

If you control the computer and understand the security implications, you can adjust PowerShell’s policy for your user account. Do not weaken security settings blindly on a managed or shared computer.

Fix: pip installs into the wrong place

Check which Python and pip are active:Copy

python -c "import sys; print(sys.executable)"
python -m pip --version

The pip output should reference the same .venv directory as the Python executable. If it does not, activate the environment again or use the full path:Copy

.venv/bin/python -m pip install package_name

On Windows:Copy

.venv\Scripts\python.exe -m pip install package_name

Add .venv to Git ignore rules

Create or update .gitignore:Copy

.venv/
__pycache__/
*.py[cod]

Commit requirements.txt, not the environment folder. Other developers should create their own environment from the dependency list.

Recreate an environment cleanly

Virtual environments are disposable. If dependency state becomes confusing, remove the folder and recreate it.

macOS or Linux:Copy

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

Windows PowerShell:Copy

Remove-Item -Recurse -Force .venv
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Do not delete an environment before saving the dependency list if you need to reproduce its installed packages.

Best practices for everyday use

Create one environment per project. Name it .venv so editors can detect it. Use python -m pip to avoid interpreter mismatches. Keep dependencies recorded in version control, and rebuild the environment rather than manually repairing a badly tangled installation.

Activate the environment before running tests, scripts, and development servers. A common mistake is installing a package in one environment and running the program in another.

Final takeaway

The standard workflow is straightforward: create .venv with python -m venv .venv, activate it, install packages, save dependencies, and deactivate it when finished. When something goes wrong, inspect the Python executable first. Most virtual-environment problems are really interpreter-selection or working-directory problems, not problems with the library you are trying to install.