How to Use virtualenv in Python

Have you tried to install a Python package for a new project, just to see your other projects break because of some compatibility issues? You can avoid this with the help of virtualenv in Python.

virtualenv is a tool that allows you to create virtual environments in Python and manage Python packages. It helps you avoid installing packages globally; global installations can result in breaking some system tools or other packages.

For example, let’s say Project A and  Project B require the same library. While this does not seem like a big deal at first, things can get difficult if you need different versions of the same library between Project A and Project B. This becomes a problem because Python cannot differentiate the version number in the site-packages directory.

This is where setting a virtual environment in Python is very useful. It is also an excellent practice to help you write better Python code.

In this article, we’ll show how to install virtualenv in Python. Then we’ll explore how to set up virtual environments in Python and work with repositories.

Let’s get started!

Install virtualenv in Python

A virtual environment in Python allows you to create an isolated environment for your projects. It means that your projects can have their own dependencies – independent of every other project's dependencies.

With a Python virtual environment for each project, you are free to install different versions of the same Python package for each project. This is because every Python environment is independent of all the others.

At their core, virtual environments in Python are just directories containing a few scripts; consequently, you can set as many Python virtual environments as you like.

Let’s install virtualenv in Python!

virtualenv is easy to install. First, let's update pip.

pip install --upgrade pip

pip --version

My output:

pip 22.0.3

Next, you can install virtualenv:

pip install virtualenv

Now that virtualenv is installed, let's create a virtual environment in Python called mytest:

virtualenv -p python3 mytest

You will get an output similar to this one:

created virtual environment CPython3.8.11.final.0-64 in 10455ms                                                           creator CPython3Windows(dest=C:\Users\xavie\mytest, clear=False, no_vcs_ignore=False, global=False)            
seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=C:\Users\xavie\AppData\Local\pypa\virtualenv)                                                                                              added seed packages: pip==22.0.3, setuptools==60.6.0, wheel==0.37.1                                                   activators BashActivator,BatchActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator 

And here we go! In the next section, we’ll explore using virtualenv in Python. You can find more information about virtualenv in the official Python documentation.

How to Work With and Maintain virtualenv in Python

Before installing or using packages in your new Python virtual environment, you need to activate it. 

In Mac or Unix

If you are a Mac or Unix user, you can do it as follows:

source mytest/bin/activate

Next, you can check that you are in a virtual environment with the following command:

which Python

It should be in the mytest directory:

.../mytest/bin/python

And that's it! Now you can start installing the required packages for your project.

In Windows

If you are a Windows user, you can activate virtualenv this way:

.\mytest\Scripts\activate

Now your prompt should be prefixed with the name of your environment; in this case, it’s mytest.

Next, you can check that you are in your Python virtual environment with the following command:

where Python

Like the Mac or Unix environment, it should indicate the mytest directory:

...\mytest\Scripts\python.exe

Now you can install all the packages you need. You can do so individually or with the help of a requirements.txt file. If you do not know how to do this, refer to my earlier article on how to create a Python requirements file.

But how does virtualenv work under the hood?

Once you activate your Python virtual environment, you get a different path for the Python executable. This is because the $PATH environment variable is modified in the active environment.

After activating your Python virtual environment, the bin directory is now at the beginning of the path, meaning that the shell uses your virtual environment’s instance instead of the Python system version.

Important: Don’t store your Python scripts and your requirements.txt file inside your Python virtual environment.

Deleting Virtual Environments in Python

The easiest way to delete a virtual environment in Python is to delete the folder manually. By leaving your Python scripts outside your virtualenv folder, you avoid the risk of deleting your whole project the next time you want to clear your Python virtual environment.

Also, you might want to use the same virtual environment for different projects. Keeping all your Python scripts outside your folder will make the whole process easier to handle.

If you are new to Python and want to improve your skills quickly, I highly recommend you check out our Python programming track.

What About pyenv and pyenv-virtualenv?

pyenv-virtualenv is a pyenv plugin to manage Python virtual environments. pyenv comes in handy when you need to install and switch between different Python versions; however, we cannot create virtual environments with arbitrary versions of Python.

With pyenv-virtualenv, it’s easier to switch between Python versions within different virtual environments. Feel free to read my article about pyenv if you want to learn more about this topic.

Using virtualenv With Repositories

Now, you might want to push your project on GitHub. After you’ve finished working in your Python virtual environment, you first need to initialize the repository:

git init

Then, you need to include the mytest folder in a .gitignore file. This way, the Python virtual environment will be ignored in source control.

echo 'mytest' > .gitignore 

Once this is done, we can place our project’s dependencies in a requirements.txt file:

pip freeze > requirements.txt

The freeze command will read the dependencies and create a text file containing a list of dependencies and their version number.

Once this is done, we add the file to be pushed to the repository:

git add requirements.txt 

And finally, we commit the files and push the project to our repository.

I want to emphasize the importance of the requirements.txt file here. When the file is not there, it can be challenging for another person to use a project.

For example, let’s say you have an Open3D project to work on point clouds and you use the JVisualizer to run visualizations in Jupyter Notebook. You use Open3D 0.12.0 to build your project; later, you decide to upload the project on GitHub to share it with your friends. If you do not add a requirements.txt file and let your friends simply install the latest version of Open3D (0.14.1), they will not be able to run your Jupyter Notebook.

By providing the information to recreate the same virtual environment you used for your project, you will make everything run more smoothly for others. This will save you from headaches – after they've created their virtual environment, your colleagues would only need to enter the line below:

pip install -r requirements.txt

If you need more information on using GitHub, you can read Kateryna's quick guide to Git here. And if you haven't been keeping your requirements.txt file up to date, check out my article for an easy fix.

Closing Thoughts on virtualenv in Python

In this article, we learned how to set up a virtual environment in Python using virtualenv and why it’s important. We’ve also learned how to use a virtual environment in conjunction with GitHub.

virtualenv will make your life as a developer easier and help you write cleaner code. If you’re not yet doing so, I encourage you to develop the habit of setting up Python virtual environments when you start a new project.

Last but not least, you can find more tips to write better Python code here. And remember to visit LearnPython.com for more content.