Elena' s AI Blog

Python Virtual Environments

24 Jan 2025 (updated: 03 Jul 2026) / 9 minutes to read

Elena Daehnhardt


 Midjourney: A minimalist illustration of a Python snake slithering through a series of interconnected boxes, each representing a virtual environment --v 6.1


TL;DR:
  • Always use a Python virtual environment for every project. Create it with 'python3 -m venv .venv', and activate it with 'source .venv/bin/activate'. It prevents dependency conflicts and keeps your global Python installation clean.

📚 This post is part of the "Python Projects & Utilities" series

Series: Python Projects & Utilities (Part 5 of 8)

Previous: Part 4 — Logging in Python

Next: Part 6 — Python Flask TODO App

What Is a Python Virtual Environment?

A Python virtual environment is an isolated, per-project folder that holds its own Python interpreter and installed packages, so dependencies for one project never conflict with another or with your global system Python.

If you have ever tried to run two Python projects that required different versions of the same library, you already know the pain of dependency conflicts.

The solution is simple: virtual environments. A virtual environment is a lightweight, isolated folder where you can install Python packages specifically for one project, without affecting your global system Python installation or breaking any of your other projects.

Using isolated environments helps you:

  • Prevent conflicts: Install exactly the versions you need for one project without breaking another.
  • Collaborate cleanly: Share your requirements.txt so anyone else can recreate the exact same setup.
  • Clean up safely: Because all dependencies are stored in one local folder, you can simply delete it when you’re done. No lingering junk on your system.

Using venv to Create an Isolated Python Environment

Using virtual environments is good practice, especially as projects grow in complexity and require different libraries that may not be compatible. The standard-library module venv allows each project to have its customised environment.

The venv module creates a virtual environment: a folder containing scripts and a link to the Python interpreter. Virtual environments offer two main benefits:

  1. You can install project-specific libraries in isolation for better control.
  2. When sharing your project, use “pip freeze > requirements.txt” to create a list of necessary libraries, keeping your environment clean.

Creating a Virtual Environment

Here’s how to create a virtual environment:

  1. Open your terminal or command prompt.
  2. Navigate to your project directory.

  3. Create the environment:

     python3 -m venv .venv

    This creates a directory named .venv (you can choose any name) containing a copy of the Python interpreter, pip, and other necessary files.

Activating the Environment

Before installing packages or running your project, you need to activate the environment:

  • On Linux/macOS:

    source .venv/bin/activate

  • On Windows:

    .venv\Scripts\activate

You’ll see the environment name in your terminal prompt, indicating it’s active.

Installing Packages

Now, you can use pip to install packages within the environment. They will be isolated from your global installation.

pip is Python’s package manager. It installs and manages Python packages from the Python Package Index (PyPI) or other repositories.

For instance, we can install the tiny web framework Flask:

pip install Flask

If you get a message that pip has to be updated, run the upgrade command:

python3 -m pip install --upgrade pip

To install packages from a requirements.txt file:

pip install -r requirements.txt

The flag -r tells pip to read the dependencies from a file instead of specifying them individually in the command line.

The requirements.txt is a plain text file that typically contains a list of package names and their versions. This is so useful for sharing project dependencies with others.

Fixing “error: externally-managed-environment”

On Debian, Ubuntu, and recent macOS Homebrew Python builds, running pip install against the system interpreter raises error: externally-managed-environment (defined by PEP 668). The cause is that the system Python is marked as managed by the OS package manager, so pip refuses to modify it. The fix is exactly the workflow in this post: create and activate a virtual environment first, then install inside it.

python3 -m venv .venv
source .venv/bin/activate
pip install Flask

Deactivating the Environment

When you’re finished working on your project, deactivate the environment:

deactivate

This returns you to your global Python environment.

Deleting a Virtual Environment

To delete a virtual environment, simply delete its directory. Make sure the environment is deactivated first.

rm -rf .venv

This action is irreversible, so ensure you don’t need the environment anymore.

Renaming a Virtual Environment

You might be tempted to just rename your environment directory using the mv command. Do not do this.

Virtual environments contain activation scripts and executable shebangs (#!) that hardcode the absolute path to the environment folder. If you simply rename the directory, these paths will break.

If you really need a new name for your environment, the only safe way is to delete the old one and recreate it:

  1. Deactivate the current environment.
  2. Freeze your current packages: pip freeze > requirements.txt
  3. Delete the old environment: rm -rf .venv
  4. Create the new one: python3 -m venv new_env_name
  5. Activate it and reinstall: pip install -r requirements.txt

Example Workflow: A Flask Project in a Virtual Environment

Let’s say you’re starting a new web TODO app project with Flask:

  1. Create a project directory: mkdir my_todo
  2. Navigate to the directory: cd my_todo
  3. Create a virtual environment: python3 -m venv .venv
  4. Activate the environment: source .venv/bin/activate
  5. Install necessary packages: pip install Flask
  6. Write your TODO app code.
  7. Deactivate the environment when done: deactivate

Virtual Environment Best Practices: requirements.txt, pipenv, and poetry

My few tips on how to use the virtual environments:

  • Use virtual environments for every Python project when appropriate. I also use Docker quite a lot :), so I don’t always have to use a virtual environment.
  • Include a requirements.txt file to define the project dependencies. You can use pip freeze > requirements.txt to generate it.
  • Consider using a tool like pipenv or poetry. These tools provide advanced features for managing dependencies and environments.

Personally, Docker and Pip work well for me. But it is your freedom to choose what best fits you.

Python Virtual Environments FAQ

How do I create a Python virtual environment?

Navigate to your project directory and run python3 -m venv .venv. This creates a .venv folder containing an isolated Python interpreter and pip. Activate it with source .venv/bin/activate on Linux/macOS or .venv\Scripts\activate on Windows.

What is the difference between venv and pip?

venv creates the isolated environment (a folder with its own Python interpreter), while pip installs packages into whichever environment is currently active. You activate a venv first, then use pip to install project-specific dependencies inside it.

Can I rename a virtual environment folder?

No. Activation scripts and executable shebangs hardcode the absolute path to the environment folder, so renaming it with mv breaks them. Instead run pip freeze > requirements.txt, delete the old folder, create a new one with python3 -m venv new_name, and reinstall with pip install -r requirements.txt.

How do I delete a virtual environment?

Deactivate it first with deactivate, then remove its directory with rm -rf .venv. Because all dependencies live inside that one folder, deleting it removes the environment completely with no leftover system files.

Conclusion

A Python virtual environment is the standard, reproducible unit of dependency isolation in Python: it keeps each project’s packages separate, avoids version conflicts, and makes collaboration easier through a shared requirements.txt. Create one per project, activate it before installing packages, and delete the folder when you are done.

Did you like this post? Please let me know if you have any comments or suggestions.

Posts about development tools and Python coding

References

1. venv — Creation of virtual environments

2. pip documentation

3. Pipenv: Python Dev Workflow for Humans

4. Poetry documentation

desktop bg dark

About Elena

Elena, a PhD in Computer Science, simplifies AI concepts and helps you use machine learning.

Citation
Elena Daehnhardt. (2025) 'Python Virtual Environments', daehnhardt.com, 24 January 2025. Available at: https://daehnhardt.com/blog/2025/01/24/virtual-environments-in-detail/
All Posts
Copyright © Elena Daehnhardt
Privacy and Terms