Introduction

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

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

Venv creates a virtual environment, a folder containing scripts and a link to the Python interpreter. It offers two main benefits:

You can install project-specific libraries in isolation for better control.
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:

Open your terminal or command prompt.
Navigate to your project directory.
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.

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:

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

Example Workflow

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

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

Best Practices

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

Using virtual environments helps you manage Python projects better. It keeps your code clean and organised, avoids dependency problems, and makes collaboration easier.