When people start learning Python, they often will come across a package they want to try and it will usually start with "just pip install it!" The problem with that advice is it's a very simplistic view of how to manage packages and can actually lead to problems down the road. And while there is a tutorial on installing packages at packaging.python.org, it might be a bit intimidating for some if they are just looking to quickly get up and going.

If you just want to start poking at Python and want to avoid the pitfalls to installing packages globally, it only takes 3 steps to do the right thing.

Summary

1. Create a virtual environment, e.g. python3.8 -m venv .venv (substitute py -3.8 for python3.8 if necessary)
2. Activate the virtual environment, e.g. source .venv/bin/activate.fish (assuming you are using the fish shell)
3. Install the packages you want, e.g. python -m pip install --upgrade pip if you wanted to install the latest version of pip (which you probably do)

Do note that there is a fancier version of step 1 explained below. This post also covers versions of step 2 for other shells.

Details

Step 1: Create a virtual environment

The first step is creating a virtual environment. You want this because you want to isolate what you install from your global Python installation. Thanks to Python being widely used to run operating sytems now you can actually break your OS if you install directly into your global interpreter. So please, always use some form of isolated environment (I will be using virtual environments because they are built into Python itself, they are lightweight, and VS Code has great support for them 😁).

I will also say that when creating your virtual environment you should always do it by specifying the specific version of Python that you want. You will notice below that I use commands like python3.9 or python3.8 and not simply python3. That's to make sure you are getting the version of Python you want.

Also, don't commit your virtual environment to your version control system. If you want to protect yourself against doing this then the commands below will create a .venv directory where you can put a .gitignore file that contains nothing more than * (if you are using UNIX you can do this with echo "*" > .venv/.gitignore after you create your virtual environment).

Lastly, below you will notice me using the --prompt flag. It's totally optional and can be left out on any OS. All it does is make your shell prompt a little more informative for step 2 later on by giving your virtual environment the base name of your current directory, so it's a nice touch but if you don't want to bother with the flag it won't affect anything.

Warning for Debian/Ubuntu users

If you are using a Debian-based OS (e.g. Ubuntu) and you are using the OS-installed version of Python, make sure to install python3-venv via apt. If you installed from python.org or any other means then you will very likely have what you need.

Note for Windows users

Below I use py as that is what comes with the python.org installer. If for some reason it isn't installed then don't worry and substitute e.g. py -3.8 with python3.8.

Python 3.9 and newer

As of this writing Python 3.9 is not out yet, but it will be come October 2020 and hopefully this blog post will still be around by then, so I cover a neat new feature that's coming which makes --prompt easier to use.

UNIX

python3.9 -m venv --prompt . .venv

Windows

py -3.9 -m venv --prompt . .venv

Python 3.8 and older

fish shell

python3.8 -m venv --prompt (basename $PWD) .venv

bash shell

python3.8 -m venv --prompt `basename $PWD` .venv

PowerShell

py -3.8 -m venv --prompt "$(Split-Path -Leaf -Path (Get-Location).Path)" .venv

Step 2: Activate your virtual environment

Activating your virtual environment makes it so that when you type python it will point to the interpreter in your virtual environment (as well as making any tools that get installed by any packages you install later available). This step is completely optional but it is rather handy. If you used --prompt in step 1 then your shell prompt will say the directory name that contains the virtual environment to remind you what python points at.

If at any point you want to turn off the activation of your shell you can run deactivate (closing/quitting your shell also works as activations are not permanent).

fish shell

source .venv/bin/activate.fish

bash shell

source .venv/bin/activate

PowerShell

You will notice that there are two commands here. The first command only needs to be run once and it lowers the security level of PowerShell to allow PowerShell scripts which are signed but whose signing key isn't installed in the OS to be run (the activation script is signed by the Python Software Foundation as of Python 3.8). If you don't run this command you will get an error. It's no big deal and you can still go and change the execution policy as needed.

Set-ExecutionPolicy RemoteSigned
.venv\Scripts\Activate.ps1

Step 3: Install your package(s)

If you have seen instructions to "just" run pip to install something, you may notice my suggestion below is a little different. I have an entire blog post on why, but the short answer is you want to make sure you are installing into your virtual environment and not your global installation of Python by accident (and the whole reason the first two steps of this blog post exist).

I am also using pip as the example project to install with an extra --upgrade flag so that you upgrade pip in your virtual environment. Chances are there's a new version of pip available compared to what gets installed by default and thus this is not only illustrative but also does something useful for you. Plus it's an easy way to make sure your virtual environment is working as expected.

If you activated your environment

python -m pip install --upgrade pip

If you didn't activate your environment

UNIX

.venv/bin/python -m pip install --upgrade pip

Windows

.venv\Scripts\python -m pip install --upgrade pip

That's it!

Following the steps above you ended up with:

1. A virtual environment which isolated what you installed from your global installation of Python
2. A shell that's activated for the virtual environment to make it a little easier to use Python
3. An updated installation of pip

If at any point you don't want your virtual environment anymore you can simply delete the .venv directory that the environment was kept in. And if you want to use a newer version of Python later on, just delete the .venv directory and create a new virtual environment (they are meant to be throw-away things). And remember not to commit your virtual environment to source control.

Please note there are ways to properly manage your package dependencies long-term if this is not a throw-away virtual environment just for experimentation. That topic deserves its own blog post, so I am not even going to attempt to delve into it here. Just know that if you are doing work that is meant to persist you will want to use something that will help you keep track of what packages your code depends on.

I also fully admit that this blog post is opinionated. It's short and bare-bones on purpose using my preferred way to quickly get up and going. Just be aware that there are tools which can help automate these 3 steps if you want. There are even alternative isolation environments other than virtual ones that might fit your needs better. We are rather lucky in the Python community to have so many passionate users that if something feels awkward then someone has probably come up with a solution that might improve the experience for you.