Guide on virtual environments in Python
Start your free 7-days trial now!
What is a virtual environment?
Virtual environments are used for isolating the dependencies (e.g. libraries, Python version) of every application. By default, the packages we install using
pip install will end up in what's known as the global site-packages folder. For my MacOS, this folder is located in the following directory:
Now, suppose we have an Python application that depends on the latest version (say
2.0) of a library called
pandas. If we run
pip install pandas, then the
pandas library will be installed into the global-site packages folder. Now, in our Python application, we will be able to import this library:
import pandas as pd
When Python runs this script, it will retrieve the
pandas library from the global-site packages.
Now, suppose we have another Python application that can only use an outdated version of
pandas, say version
1.0. In other words,
2.0 that we have installed in our global-site packages is not compatible with this application. Calling
import pandas in our script will therefore break the application.
One quick fix is to install the desired version of
pandas like so:
pip install pandas==1.0
Running this command will install
1.0 and overwrite the previously installed
pandas library in the global site-packages folder. The problem with this approach is that the second application now runs fine but the first application does not because it depends on another version of
This is where virtual environments come into play. Instead of using the libraries installed in global site-packages, every application will use libraries installed specifically for its application. More precisely, every application will have its own virtual environment and calling
pip install pandas will install the library in this virtual environment instead of the global-site packages. Running
import pandas in the application's script will import
pandas installed in the virtual environment instead of the one in global-site packages. Going back to our example, the two applications can now safely each use its own version of
Suppose our application contains a
main.py file. In our terminal, head over to the application's directory:
Let's create a virtual environment:
python -m venv my_venv
This will create a new virtual environment in the form a folder called
my_venv in the current directory:
Note that the version of Python used by our virtual environment will be the same as the one used by your terminal by default. For instance, my terminal uses the following version of Python:
python --versionPython 3.9.6
This means that my virtual environment
my_venv will use Python version
3.9.6. We will later see how we can change the Python version when creating the virtual environment later.
Now that we've created a virtual environment, we now must activate it:
my_venv\Scripts\activate # For Windowssource my_venv/bin/activate # For Linux and MacOS
source command reads and run the script file
my_venv/Scripts/activate in the current terminal environment. Running the above command will activate the virtual environment:
(my_venv) (base) isshininada@Isshins-MBP tutorial %
Notice how we now see the virtual environment that is now active (
my_venv in this case). Let's first see what python packages are already installed for use in our virtual environment:
(my_venv) (base) isshininada@Isshins-MBP pytest_tutorial % pip listPackage Version--------------- -------pip 21.1.3setuptools 56.0.0
We see that
pip is installed, which means that we can start installing Python packages!
Now, let's install the latest
pip install pandas
This will install the
pandas library (along with all its dependencies like
numpy) into the folder
my_venv folder like so:
main.pymy_venv/├── bin├── include└── lib/└── python3.9/└── site-packages/├── pandas├── numpy└── ...
Notice how the packages are installed under Python version 3.9 - this is because my virtual environment was created using version 3.9 as discussed earlier.
Now, within our
main.py file, we can import this latest version of
pandas like so:
import pandas as pdprint(pd.__file__)/Users/isshininada/Desktop/pytest_tutorial/my_venv/lib/python3.9/site-packages/pandas/__init__.py
pd.__file__ represents the location of pandas that this script has imported. We can see that it's imported the library from our
my_venv folder as expected!
Sharing and reproducing virtual environments
Suppose we wanted to share our code to someone else, say Alex. A common practice when sharing code is to distribute:
the source code of our application.
text file called
requirements.txtthat lists all the packages and their versions required for the application to run.
We rarely ever share the virtual environment folder itself because:
it works only on our machine. Some of the files in the virtual environment folder contain paths that are specific to our machine. This means that the virtual environment will not work properly on someone else's machine.
we can save bandwidth and storage space by distributing only our application's source code without the source code of all the libraries installed within the virtual environment. Others who wish to run the application must install the libraries by themselves - we will cover this later.
To be able to run the code, Alex should create his own virtual environment for this application and install all the packages (e.g.
pandas) of the right version in that virtual environment. We must therefore provide Alex with a
requirements.txt that contains this information.
To obtain a list of packages currently installed in our virtual environment:
We can output this list as a text file called
requirements.txt in our current folder like so:
pip freeze > requirements.txt
By convention, the
requirements.txt file contains all the packages as well as their versions required for the application to run.
We now pass our application's source code and this
requirements.txt file to Alex. To set up his virtual environment, he first has to create one and activate it like so:
python venv -m MY_VENVMY_VENV\Scripts\activate # For Windowssource MY_VENV/bin/activate # For Linux and MacOS
Finally, he can install all the packages listed in
requirements.txt like so:
pip install -r requirements.txt
-r flag tells
pip to install all the libraries installed in
requirements.txt. Great, Alex now has a virtual environment with the same packages installed!
Deactivating and deleting virtual environments
To deactivate our virtual environment:
deactivate(base) isshininada@Isshins-MBP pytest_tutorial %
To delete our virtual environment, we can delete its folder like so:
rm -rf ./my_venv
rmis the remove command.
-rflag stands for recursive and is for removing a folder and all its content.
-fflag allows us to specify the folder name to delete.