PyCharm and Virtualenv: Package Management Basics

Associated YouTube video

PyCharm is a great IDE for Python that works across Mac, Windows, and Linux platforms.

The newer PyCharm releases embrace the use ofbuilt-in virtual environments to isolate the project code dependency on third-party packages from the system python library packages.

Packages are the entities that you refer to when you have import statements in your code.

i.e. import requests
or from bs4 import BeautifulSoup

There are 212 built-in standard packages that are installed with python and over 150 thousand third-party packages available from PyPi.org and installed with the pip install package-name command

You can learn all about the pip package manager command at pip users guide

When you start doing more serious python development, the isolation of packages between projects will become more important since individual packages evolve though versions and depend on other packages in complex relationships.

A package being updated to a new version can break other packages or even project code that you already have.

The creators of PyCharm (JetBrains) have now made virtual environments kind of the 'default' for new projects.

System Python version:

Base or System Interpreter in PyCharm dialogs refer to python interpreter version that you installed that you what to use for your project. Some systems come with a python interpreter such as Mac, and Linux. Windows does not start with an interpreter.

Any installed python versions consist of the executable for the interpreter, a package library, and other tools and resources. We will be dealing with the interpreter and its associated package when talking about virtual environments.

You can add different versions of the python interpreter and have more than one available on your system. This might be important if you what to write code that works across a range of python versions from the old 2.7 to the newest version 3.7 as of this writing.

For PyCharm, you should be a bit familiar the two parts of the python environment that you will be controlling with the virtual environment: 1. The version of python, and 2. the associated packages

Platform	Paths to Interpreter and Packages
Mac (10.13)	Interpreter: `/System/Library/Frameworks/Python.framework/Versions/3.7/bin/python3.7` and `/usr/local/bin/python3.7` -- symlinked to above path Packages: `/System/Library/Frameworks/Python.framework/Versions/3.7/bin/lib`
Win 10	Interpreter: `C:\Users\name\AppData\Local\Programs\Python\Python37-32\python.exe` Packages: `C:\Users\name\AppData\Local\Programs\Python\Python37-32\lib\site-packages\`
Linux	Interpreter: `/usr/bin/python3.7` Packages: `/usr/lib/python3/dist-packages`

Virtual Environments (venv):

Since python 3.3, venv virtual environments have been part of the standard CPython distribution. You can create and manage your virtual environments from the command line with the python tools. (see python.org tutorial on venv) PyCharm will create and manage your virtual environment folders though a few dialogs.

A venv is a folder that holds information that points to the base system interpreter, tools, and resources and a folder which allows isolation of versions of packages from packages in the system packages folder.

By default, PyCharm will create a new project with a venv folder in your project folder that contains a copy of the packages from the system python version used.

Here is a picture of the New Project Dialog Box with the Project Interpreter drop down showing: (Note, the base interpreter is usually the last on you have set)

If you want a new base interpreter, this next dialog shows that PyCharm will try to show you all the installed versions of python to choose from. If you picked a custom location and it does not show in the dropdown, you can click the ... button and browse for the python version.

Default Project Dialog with Interpreter choices

Once you have created the default project without choosing any options, you should get the following setup:

Your choice of project python version
A venv folder at the top level of your project folder
All python code in you project will search the venv folder from you project folder when doing imports of third-party packages
There will be no connection to the python packages from your project. If you need any new python packages for your code, you will need to go to the PyCharm settings or preferences menu and choose Project Interpreter:

Notes: the packages you see are automatically populated into your virtual environment.
You are now free to use the + button at bottom to search and install any package, or update.

Here is a diagram showing this setup: (Note the arrow is showing the venv base interpreter pointing to the system level interpreter.)

Using Inherit global site-packages

If you commonly use a standard set of third-party packages in your projects, you can create a project with the "Inherit global site-packages" turned on as shown:

If you choose the Inherit global site-packages, your project will have the following features:

Your choice of project python version
A venv folder at the top level of your project folder
All python code in you project will search the venv folder from you project folder when doing imports of third-party packages, and if it did not find the package in your project venv, then it will look for it in the base Interpreter package library (a.k.a. global site-packages.)
Any new packages you install or modify from preferences > Project: Project Interpreter will 'shadow' the same package if it is in the installed system library, meaning your code will use the one you installed or modified in your project venv. If you remove the package from your venv area with the minus (-) button, then your project will again find the system package.

Here is a diagram showing this relationship after some changes to the venv packages (in red):

Inherit globals relationship after changes to venv

The Take Away:

Usually, just let PyCharm default to create a venv that is not dependent on the system package library, then just add or change packages as needed for that project.
In the case you want to 'share' your global packages, so you don't have to setup up every project's packages, then use the 'inherit global site-packages' option
PyCharm can manage all your packages nicely from within the IDE dialogs.