Learn how to create and use a Python virtual environment with venv. This guide covers setup on Windows, macOS, and Linux, package installation, project sharing, and common fixes.
A Python virtual environment gives one project its own place to store Python packages. That means packages installed for one project do not change the setup of another project or your computer’s main Python installation.
For most projects, Python’s built-in venv tool is a simple way to create this separate space. You can use it to install packages, run your code, and record which packages the project needs. This guide walks through each step on Windows, macOS, and Linux.
A virtual environment is a folder that holds a project’s Python tools and installed packages. When you turn it on, commands such as python and pip point to the versions inside that folder instead of the system-wide ones.
Think of each project as having its own toolbox. A website project might need one version of a package, while a data project might need another. Keeping their toolboxes separate helps prevent one project from breaking when you update or add a package for another.
A virtual environment does not copy every part of Python into a project. It uses the Python installation that created it, then keeps project packages separate. You still need Python installed on your computer.
Without an environment, packages may be installed in a shared location. This can cause confusing problems: a package update for an older project might affect a newer one, or a project may work on your computer but fail elsewhere because its package needs were never recorded.
A virtual environment helps you:
For a small script that uses only Python’s built-in features, you may not need an environment. But for most projects that install packages, using one is a good habit.
Open a terminal or command prompt and check that Python is installed. On Windows, try:
py –version
On macOS or Linux, try:
python3 –version
You should see a Python version number. If the command is not found, install Python first and make sure the installer adds it to your command path. The command path is the list of places your computer checks when you type a program name.
It also helps to create a folder for your project. In the examples below, the folder is called weather-tool. Use your own project name if you prefer.
First, move into your project folder in the terminal. If the folder does not exist yet, create it, then enter it. On macOS or Linux, you can use:
mkdir weather-tool
cd weather-tool
On Windows, the same commands work in many terminals, including PowerShell. Then create an environment named .venv. The dot at the start is a common way to mark it as a project support folder.
On Windows, run:
py -m venv .venv
On macOS or Linux, run:
python3 -m venv .venv
The -m venv part tells Python to run its built-in environment tool. The final part, .venv, is the folder name. You can choose another name, but use the same name in the activation steps that follow.
If your computer recognizes python as the Python 3 command, you can use python -m venv .venv instead. When unsure, use the command that showed the correct version in your earlier check.
Creating an environment does not automatically turn it on. Activation changes the terminal so package commands use that project’s environment.
Run:
.venv\Scripts\Activate.ps1
Run:
.venv\Scripts\activate.bat
Run:
source .venv/bin/activate
When activation works, the environment name often appears at the start of your terminal line, such as (.venv). This is a useful sign, but the exact display can vary. You can also check which Python command is active: run where python in Windows Command Prompt, or which python on macOS or Linux. The result should point inside the project’s .venv folder.
Tip: Activate the environment each time you open a new terminal for the project. Activation usually applies only to the terminal window where you ran the command.
pip is Python’s tool for installing packages. A package is code that someone has prepared for use in a Python project. With the environment active, install a package by running:
python -m pip install requests
This example installs the requests package, which helps Python programs send web requests. The command uses python -m pip rather than just pip so that pip runs through the active Python. This reduces the chance of installing a package into the wrong place.
To see packages installed in the environment, run:
python -m pip list
You can also install a package from a list of project requirements, which is useful when setting up a project you have received from someone else. If a file called requirements.txt is present, run:
python -m pip install -r requirements.txt
With the environment active and any needed packages installed, run a Python file as usual. For example:
python app.py
If app.py imports a package installed in .venv, Python can find it because the environment is active. If you close the terminal and open another one, activate the environment again before running the project.
You do not have to activate the environment to run its Python executable, but activation is usually easier. For example, on macOS and Linux you could run .venv/bin/python app.py. On Windows, the matching executable is inside .venv\Scripts. This direct method can help in scripts or tools that need an exact Python path.
When a project uses packages, it is helpful to save a list of them. With the environment active, create a requirements file by running:
python -m pip freeze > requirements.txt
This writes the installed package names and versions to requirements.txt. Later, another person can create an environment and install those listed packages with python -m pip install -r requirements.txt.
Keep the file in your project folder, alongside your Python code. When you add or remove packages, update the list again. Remember that the file records packages installed in the environment, so avoid adding unrelated packages to a project environment.
A requirements file helps repeat an install, but it is not a full backup of your project. It does not include your Python code, personal files, or the Python installation itself. Keep those parts safe separately.
Version control tools help you track changes to project files. If you use Git, you normally should not add the entire .venv folder to the project history. It can contain many files, and it can be rebuilt from the project’s requirements.
Instead, add the environment folder name to a .gitignore file. For an environment named .venv, put this line in that file:
.venv/
Do include your source code and, when you use one, your requirements.txt file. This lets another person create a fresh environment without downloading your local environment folder.
To leave an active environment, run:
deactivate
Your terminal returns to using its usual Python commands. Deactivating does not remove packages or delete the environment; it only changes the current terminal session.
If you want to remove an environment, first deactivate it. Then delete the .venv folder using your file manager or terminal. You can create it again later with the venv command and reinstall the listed requirements. Do not delete it while a program is still using files inside it.
Your computer may use a different command, or Python may not be installed. On Windows, try py –version. On macOS or Linux, try python3 –version. If none of these work, install Python and reopen the terminal so it can find the new installation.
Check that you are in the project folder and that .venv exists. Use the activation command for your terminal, not a command copied from another operating system. For example, PowerShell and Windows Command Prompt use different activation files.
In some Windows PowerShell setups, a security setting may block the activation script. If you see a policy message, avoid changing security settings blindly. You can use Command Prompt instead, or ask your system administrator if you use a managed computer.
This often means pip installed the package for a different Python than the one running your code. Activate the environment, then use python -m pip install package-name, replacing the example with the package you need. Check that your editor is also set to use the Python inside .venv.
Virtual environments can store paths that point to their original location. Moving a project folder may leave those paths out of date. A dependable fix is to remove the old .venv, create a new one in the project’s new location, and reinstall packages from requirements.txt.
First check that the environment is active and that your internet connection works. Then read the full error message; it may say that the package does not support your Python version or computer. If the project has setup instructions, check them before trying random fixes.
Many code editors can find a project environment automatically. If yours does not, open its Python interpreter or environment setting and select the Python program inside .venv.
The file path depends on your system. On Windows, it is usually .venv\Scripts\python.exe. On macOS or Linux, it is usually .venv/bin/python. Choosing this interpreter matters: otherwise, the editor may run a different Python from the one in your terminal.
If code works in the terminal but shows an import warning in your editor, check the selected interpreter first. If the editor uses the project environment, restart its terminal or reload the project after creating the environment.
It is usually best to give each project its own environment. That keeps package choices separate and makes it easier to understand what each project needs. You can share an environment between small projects, but changes for one can then affect the other.
Either name works. The name .venv is common and may be hidden in some file views because it starts with a dot. Choose one name and use it consistently in your commands and project settings.
The environment folder itself is not a good way to move a project between computers. Share the project code and its requirement list instead. On the other computer, create a fresh environment with that computer’s Python, then install the packages from the list.
You need to activate it in each new terminal session if you want short commands like python and pip to use it. You can also call the Python program inside the environment by its full path, but activation is easier for everyday work.
Using venv adds only a few steps to starting a Python project: create the environment, activate it, and install what the project needs. In return, your package setup stays separate and is easier to rebuild.
Once you know which Python command your computer uses, the same pattern works for many projects. Keep the environment folder local, record project packages when useful, and check that both your terminal and editor use the project’s Python. These habits make common package problems much easier to spot.
No account yet?
Create an Account
