The Beginners Guide to Python Virtual Environments

When developing Python applications, managing dependencies can become a daunting task, particularly when different projects require different versions of the same package. This is where virtual environments come in handy. They allow you to create isolated spaces for your projects, ensuring that each project has its own dependencies without interfering with others. In this article we guide you through the basics of using virtual environments with Python.

Prerequisites

In this article we are going to walk you through the basics on how to set up virtual environments but we make a few assumptions:

• You have installed Python 3.5 or newer
• You have pip (Python package manager)

We will provide commands throughout the article for macOS, Linux, and Windows; These are to be run your terminal of choice.

If you want a powerful code editor setup read The Ultimate VS Code Setup for Python.

Why Use Virtual Environments?

Imagine you’re working on two projects: a blog app and a notes app. The blog is compatible up to version 1.0 of a library, but you want your notes app to take advantage of the latest features in version 2.0 of the library. Without virtual environments, you’d be stuck in a difficult situation, trying to juggle multiple versions of the same library. You can’t install version 2.0 because it would break your blog and you can’t use version 1.0 because your notes app will be missing great features from the newer library version. Virtual environments solve this problem by allowing you to create separate environments for each project, each with its own set of installed packages.

Options for Managing Virtual Environments

There are several tools available for managing virtual environments in Python and each has their own benefits:

1. venv: A built-in module in Python 3.3 and later, venv is the simplest way to create virtual environments.
2. virtualenv: An older tool that works with both Python 2 and Python 3, offering more features than venv.
3. virtualenvwrapper: A set of extensions that add to virtualenv for even easier virtual environment management.
4. conda: Part of the Anaconda distribution, conda can create virtual environments and manage packages for Python and other languages.

venv covers a great deal of use cases and is simple to get started with so we will use it for this guide. If you need support for Python 2 you might consider virtualenv or perhaps virtualenvwrapper if you consider yourself a power user. Follow us to be notified when we release articles on those tools soon!

Install venv

Forgive us for a bit of a fib here with the section title. Venv is bundled with Python starting in Python 3.5 so there is no need to install it. You can check your Python version to be sure you have a compatible version.

python3 --version

If your terminal returns anything later than Python 3.5 you’re all set.

Create a Virtual Environment

Typically, you will create a new virtual environment for each project you work on. To do this we use the venv command and provide a name for our to-be-created environment.

As an example, let’s create an environment for a project called Venv Tutorial. There is no agreed upon standard for naming your virtual environments but one common approach is to use the project name in snake case. You can use whatever name you like.

For macOS and Linux:

python3 -m venv venv_tutorial

For Windows:

python -m venv venv_tutorial

This creates a new virtual environment in your current working directory named venv_tutorial .

Activate a Virtual Environment

You will likely be working on multiple projects on your system so you need a good way to switch between the various virtual environments you create for them. This process of switching to a virtual environment is called “activating” or sometimes “sourcing”. To activate our newly created environment run the activate script from the directory that contains the virtual environment you just created. If you chose to name your environment differently than ours you’ll want to update your command accordingly.

For macOS and Linux users:

source venv_tutorial/bin/activate

For Windows:

venv_tutorial\Scripts\activate

Depending on how you have your terminal configured you will likely see the name of your virtual environment, (venv_tutorial) in this case, in the command prompt. This lets you know that you have successfully activated the virtual environment. If you’re not seeing the virtual environment name you may still have successfully activated it. Your terminal may simply not be configured to display the name. You can confirm that you have activated the environment by checking the python path.

which python3

If you are in a virtual environment your python3 path will point to the Python binary inside the venv directory and not your system Python.

../venv_tutorial/bin/python3

Your path may differ depending on what directory you created the virtual environment. The important bit is that the path contains the virtual environment name.

Install Packages

What good is an empty virtual environment? You can install whatever you like but for our example let’s install the requests package so that we can see it work.

For macOS, Linux, and Windows:

python -m pip install requests

This installs the requests package into the virtual environment so that it does not conflict with any other versions across your system.

Deactivate a Virtual Environment

Once done with a virtual environment you should exit it so that you get back to your system environment. This is done with the deactivate command.

For macOS, Linux, and Windows:

deactivate

Since you are back in your system environment any interactions you have with Python or pip will now be in your globally configured environment. Be ware of this and activate a virtual environment if you begin working on a project again.

Delete a Virtual Environment

At some point you might be completely done with a virtual environment and wish to remove it. Since the virtual environments are directories on your system you simply delete the directory.

For macOS and Linux:

rm -r venv_tutorial

For Windows Powershell:

Remove-Item venv_tutorial

For Windows Command Prompt:

rmdir venv_tutorial

Conclusion

You can now create, activate, deactivate, and delete virtual environments! But, this is just the beginning. Look at tools such as virtualenv or virtualenvwrapper for even more powerful virtual environment management. If you have any questions reach out on Twitter/X at @OrdinaryInds.

The phrase “virtual environment” is stated 37 times in this article. I’m sorry.