The Wiert Corner – irregular stream of stuff

Jeroen W. Pluimers on .NET, C#, Delphi, databases, and personal interests

  • My badges

    Mastodon

  • Twitter Updates

  • My Flickr Stream

    20140508-Delphi-2007--Project-Options--Cannot-Edit-Application-Title-HelpFile-Icon-Theming20140430-Fiddler-Filter-Actions-Button-Run-Filterset-now20140424-VMware-Fusion-6.0.3.-no-reclaimable
    More Photos

  • Pages

  • All categories

  • Enter your email address to subscribe to this blog and receive notifications of new posts by email.

    Join 1,860 other subscribers
«
»

python – What is a virtualenv, and why should I use one? – Stack Overflow

Posted by jpluimers on 2025/01/29

I knew that venv is always needed inside your project directory when using Python, and roughly why, but not exactly why, so the points in the below StackOverflow Q/A sequence and underlying article are important to save in my link archive.

[Wayback/Archive] python – What is a virtualenv, and why should I use one? – Stack Overflow (thanks [Wayback/Archive] Kevin and [Wayback/Archive] Thanh Nguyen).

Q

I am trying to install a Python package with this command

pip install <name of package>

I’m getting permission errors and I’m not sure why. I could run it with sudo, but someone told me that was a bad idea, and I should use a virtualenv instead.

What is a virtualenv? What does it do for me?

C

Read this article: [Wayback/Archive] Installation: virtualenvironments — Flask Documentation (1.1.x)

A

Running with the system Python and libraries limits you to one specific Python version, chosen by your OS provider. Trying to run all Python applications on one Python installation makes it likely that version conflicts will occur among the collection of libraries. It’s also possible that changes to the system Python will break other OS features that depend on it.

Virtual environments, or “virtualenvs” are lightweight, self-contained Python installations, designed to be set up with a minimum of fuss, and to “just work” without requiring extensive configuration or specialized knowledge.

virtualenv avoids the need to install Python packages globally. When a virtualenv is active, pip will install packages within the environment, which does not affect the base Python installation in any way.

In Python 3.3 or later, you can create a virtualenv as follows:

$ python3 -m venv ENV_DIR

For Windows, you should replace python3 with the full path to python.exe:

>C:\Python34\python.exe -m venv ENV_DIR

(This is a typical Python installation; your system may vary.)

In older versions of Python, including Python 2, one of the following commands should work in most cases:

$ virtualenv ENV_DIR
$ venv ENV_DIR
$ pyvenv ENV_DIR
$ pyvenv3 ENV_DIR

ENV_DIR should be a non-existent directory. The directory can have any name, but to keep these instructions simple, I will assume you have created your virtualenv in a directory called venv (e.g. with python3 -m venv ./venv).

To work in your virtualenv, you activate it:

$ . ./venv/bin/activate
(venv)$

Or use this if you have a windows system:

$ venv\Scripts\activate

The (venv) in the shell prompt lets you know which virtualenv you have activated, but you can turn this feature off if you do not like it. You can run all the usual Python commands, and they will be local to your virtualenv:

(venv)$ pip install requests numpy
[...]
(venv)$ python
[...]
>>> import requests
>>> import numpy as np
>>>

python will run the version of Python that you installed into your virtualenv, so (for example) you don’t have to type python3 to get Python 3. The Python that it runs will have access to all the standard library modules and all the packages you installed into the virtualenv, but (by default) none of the packages installed in the system-wide site-packages directory.

This last rule is important: by restricting your virtualenv to only use locally-installed packages, you can ensure that you control exactly which dependencies your project is using, even if some new system-wide package gets installed or updated next week. If you like, you can get a listing of your installed packages:

(venv)$ pip freeze
requests==2.13.0
numpy==1.12.0
(venv)$

pip can also parse this format and install from it, and it will install the same versions, even if updates have been released in the meantime:

(venv)$ pip freeze >requirements.txt

(some-other-venv)$ pip install -r requirements.txt
[...]
(some-other-venv)$ python
>>> import requests
>>> import numpy as np
>>>

You can get out of the virtualenv by deactivating it:

(venv)$ deactivate
$ python
[...]
>>> import requests
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named 'requests'

You can create as many virtualenvs as you like, and they won’t interfere with each other, nor with your system packages. A virtualenv is “just” a directory with a bunch of binaries and scripts under it, so you can remove a virtualenv the same way you remove any directory (rm -r venv on Unix). If the virtualenv is activated when you remove it, you may confuse your shell, so it’s probably a good idea to deactivate first in that case.

It points to [Wayback/Archive] Installation: virtualenvironments — Flask Documentation (1.1.x)

Use a virtual environment to manage the dependencies for your project, both in development and in production.

What problem does a virtual environment solve? The more Python projects you have, the more likely it is that you need to work with different versions of Python libraries, or even Python itself. Newer versions of libraries for one project can break compatibility in another project.

Virtual environments are independent groups of Python libraries, one for each project. Packages installed for one project will not affect other projects or the operating system’s packages.

Python 3 comes bundled with the venv module to create virtual environments. If you’re using a modern version of Python, you can continue on to the next section.

If you’re using Python 2, see Install virtualenv first.

(I know Python version 2 is deprecated, but regrettably still around a lot).

Further reading

  1. [Wayback/Archive] Virtualenv — virtualenv 20.16.3 documentation
  2. [Wayback/Archive] venv — Creation of virtual environments — Python 3.10.6 documentation
  3. [Wayback/Archive] Python virtualenv and venv dos and don’ts | InfoWorld
  4. [Wayback/Archive] Virtualenv and venv: Python virtual environments explained | InfoWorld

Intermezzo

The third one explains why you should use have a venv inside your project directory and not the other way around that.

I found out about that a long time ago when I first used certbot to install and update Let’s Encrypt certificates (I even helped file and solve some issues as back then few people ran it on OpenSuSE: [Wayback/Archive] Issues: jpluimers · certbot/certbot).

Back then, you had to clone the git repository, run cerbout-auto from the root which then would create a venv in the subdirectory venv within the repository:

By now certbot is part of most Linux distribution packages or available via snapd.

It allowed for certbot-auto to be deprecated:

Via

--jeroen

This entry was posted on 2025/01/29 at 12:00 and is filed under Development, Python, Scripting, Software Development. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.

«
»