A Python project rarely uses only the Python standard library. As soon as you install packages for a web framework, data analysis, testing or automation, dependency management becomes part of the project. If every project installs packages into the same global Python environment, versions can conflict and a change made for one application can unexpectedly break another.

A virtual environment gives a project an isolated place for its Python packages. It makes development more predictable, helps teammates reproduce the setup, and reduces accidental changes to the system Python installation.

This guide explains what virtual environments do, how to create and activate them, how to record dependencies, and how to troubleshoot common problems.

1. What problem does a virtual environment solve?

Imagine two projects:

  • Project A uses a library version that supports an older API.
  • Project B requires a newer version of the same library.
  • Both projects use the same global Python installation.

Installing the newer version for Project B may break Project A. Installing the older version again may break Project B. A virtual environment separates the installed packages for each project, so the two applications can use different dependency versions.

A virtual environment does not create a completely separate operating system or necessarily install a new Python interpreter. It creates an isolated package installation area associated with a Python interpreter.

2. Create a project and virtual environment

First, check that Python is installed and available from your terminal.

On Windows, you may use:

py --version

On macOS or Linux, use:

python3 --version

Create a project folder and move into it:

mkdir task-api
cd task-api

Create the virtual environment:

# Windows
py -m venv .venv

# macOS or Linux
python3 -m venv .venv

The command creates a directory named .venv. The leading dot makes it a hidden directory on many Unix-like systems. Naming is a convention, not a requirement; the important part is that the environment is kept separate from your source code.

3. Activate the environment

Activation changes the current shell so that commands such as python and pip use the virtual environment.

Windows PowerShell

.\.venv\Scripts\Activate.ps1

Windows Command Prompt

.venv\Scripts\activate.bat

macOS and Linux

source .venv/bin/activate

After activation, your prompt may show (.venv). Verify which interpreter is being used:

python --version
python -m pip --version

The paths printed by these commands should point inside the project's .venv directory. This check is more reliable than assuming activation succeeded.

If PowerShell blocks the activation script, read the current Python and PowerShell guidance for your environment. Do not change machine-wide execution policy blindly just to activate a project. You can also invoke the environment's interpreter directly without activation.

4. Install packages safely

Install packages using the environment's Python interpreter:

python -m pip install requests

Using python -m pip helps ensure that pip belongs to the same interpreter as the python command. This avoids a common issue where a standalone pip command installs a package into a different Python installation.

For a small API project, you might install a framework and a test tool:

python -m pip install fastapi uvicorn pytest

Check what is installed:

python -m pip list
python -m pip show fastapi

Avoid installing packages you do not need. Every dependency adds maintenance, compatibility and security considerations.

5. Record dependencies for other developers

A virtual environment is local to your machine and should generally not be committed to Git. Teammates need a way to recreate the environment.

For a simple project, create a requirements.txt file:

python -m pip freeze > requirements.txt

The file records installed package versions. Another developer can create a fresh environment and install the listed dependencies:

python -m venv .venv
python -m pip install -r requirements.txt

There is an important distinction between a fully frozen environment and a carefully maintained dependency specification. pip freeze records the installed package set, including transitive dependencies. For a small learning project this can be convenient. For a maintained application, consider a project configuration with declared direct dependencies and a lock or constraints workflow supported by the tools your team uses.

Do not blindly update every package just because a newer version exists. Review release notes, compatibility and security advisories, then run the test suite.

6. Add the environment to .gitignore

The virtual environment contains local executables, installed packages and machine-specific files. It is not source code.

Create or update .gitignore:

.venv/
__pycache__/
*.py[cod]
.pytest_cache/
.env

The .env entry is important if the project uses local secrets. Do not commit API keys, passwords or production credentials. Provide a safe .env.example containing placeholder names instead.

7. A practical end-to-end workflow

A reliable daily workflow looks like this:

  1. Clone the repository.
  2. Create a virtual environment with the project's supported Python version.
  3. Activate it or use its interpreter directly.
  4. Install dependencies from the project's documented dependency file.
  5. Run the test suite.
  6. Make a focused code change.
  7. Add or update tests when behaviour changes.
  8. Update dependency declarations only when dependencies change.
  9. Commit source files and dependency configuration, not the virtual environment.

For example:

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

The activation command shown here is for macOS/Linux. Use the Windows command from the earlier section on Windows.

8. Troubleshooting common problems

The package is installed but Python cannot import it

You may have installed the package into a different interpreter. Check:

python -c "import sys; print(sys.executable)"
python -m pip show package-name

Make sure the interpreter path and package installation belong to the same environment.

The terminal says the activation command does not exist

Confirm that the environment was created successfully and that you are in the project directory. The activation path differs between Windows and Unix-like systems.

A teammate cannot reproduce your setup

Check that the dependency file is committed, the Python version is documented, and setup instructions are current. Some packages also require system libraries or platform-specific tools that pip cannot provide on its own.

A package update breaks the application

Recreate the environment from the last known dependency specification, inspect the package's release notes, and update deliberately. Use automated tests to identify the incompatible change before deploying.

The environment folder was deleted

That is usually recoverable. Recreate the environment and reinstall dependencies from the project's dependency file. This is one reason the environment itself should not be the only record of how the application is configured.

9. Virtual environments and other dependency tools

Python's built-in venv is a good default for many projects. Other tools add features such as dependency locking, project management, multiple Python versions, environment switching or reproducible builds.

Choose based on the team's workflow rather than adopting a tool because it is popular. Check whether the tool is compatible with the project's Python version, deployment platform and CI pipeline. Avoid mixing several environment managers without a clear reason; that can make it harder to know which interpreter and dependency file are authoritative.

Frequently asked questions

Should I create one virtual environment for all my projects?

Usually no. Create one environment per project so dependencies can evolve independently.

Should I commit .venv to GitHub?

No, not for a normal application repository. Commit the dependency configuration and setup instructions so another developer can recreate it.

Does a virtual environment isolate environment variables and secrets?

No. It isolates Python packages and related interpreter paths. Secrets still need a proper configuration and secret-management approach.

Can I use a virtual environment in VS Code?

Yes. Select the interpreter inside the project's .venv directory. Confirm the integrated terminal and test runner use the same interpreter.

Final checklist

  • Create a dedicated environment for each project.
  • Verify the interpreter path before installing packages.
  • Install packages through python -m pip.
  • Record direct dependencies and reproducible versions.
  • Ignore .venv, caches and secret files in Git.
  • Document the Python version and setup commands.
  • Rebuild the environment from scratch periodically to test reproducibility.
  • Run tests after dependency changes.

Virtual environments are a small habit with a large payoff. They make projects easier to maintain, safer to experiment with, and much easier for another developer to run on a clean machine.