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.

Conclusion

🔒 Subscribe to keep reading.

References

🔒 Subscribe to keep reading.