Skip to main content

Installation Guide

a comprehensive guide to installing and running Parsons

Published onJul 28, 2022
Installation Guide

You're viewing an older Release (#9) of this Pub.

  • This Release (#9) was created on Sep 21, 2023 ()
  • The latest Release (#10) was created on Jul 19, 2024 ().

There are two ways to install Parsons: for use, and for contribution and development. This guide focuses on installing Parsons for use in your Python scripts. Instructions on how to install for development are in the Contributing Guide.

This guide is meant to be comprehensive. For instance, we tell people how to install Python, even though often peoples’ computers come with Python pre-installed. We also often provide different instructions for Windows and for Mac/Linux. So you will likely end up skipping sections.

We try to provide background information where we can. Click on links with this symbol ℹ️ to learn more about a tool or concept.

We also recommend you check out the Common Installation Problems section at the end if you run into trouble. And of course, you can always ask for help in the #getting-help channel on Slack!

With that said, let’s get started!

Installing Python

Some people’s operating systems come with Python pre-installed. To check whether you’ve got Python installed, go to your command line. (Not comfortable with the command line? Check out ℹ️ our command line guide.)

Once you’re at the command line, type python --version:

The Python version number tells you which version/release of Python you’re using. If, instead of a Python version number, you get some kind of error like “python not found”, you need to install Python.

Parsons currently only supports versions 3.8 through 3.10. It may work with older versions, but you’re much more likely to run into difficulties if you use an older version. ( ℹ️ Learn more about Python versions/releases, including how to pick a Python version/release.)

To install Python on Windows, download Python for Windows from (You can also try to install Python through the Windows app store by following steps 1-4 under the heading “Install Python” in these instructions, but this approach has caused issues for some users.)

Note that there is a known issue on Windows where, sometimes, Python needs to be added to the system path after being installed. (ℹ️ Learn more about paths.)

Python usually comes pre-installed on Macs, however sometimes it’s an older, deprecated version. To install Python on Mac, or update from 2.7 to 3+, try these instructions.

Python also usually comes pre-installed on Linux. If it’s not, you can install Python on Linux with these instructions.

Setting Up Your Virtual Environment

Normally, tools like pip install Python libraries directly to your system. When your Python programs run, they look for the libraries they depend upon in your system. But this can cause problems when different programs need different versions of the same library.

To address this, we recommend you use virtual environments to install Parsons. Virtual environments allow you to install libraries into an isolated environment specific to a project. That way you can use different versions of the same libraries for different projects.

If you’ve never created a virtual environment before, you’ll have to decide where you want to store yours. Some people keep their virtual environment in the same folder as their project. Other people put all their virtual environments together in the same place. It doesn’t matter which you choose, but for the purposes of this guide we’ll assume you’re keeping all your virtual environments together in the same place.

To do this, create a directory to store your virtual environments:

mkdir /home/username/virtualenvs

Note that the path you use in the above command will probably be different for you. Remember that you can figure out the exact path to where you are using the command pwd (Mac/Linux) or dir (Windows). Whatever the path ends up being, we’ll refer to it as $path_to_your_env below.

Now it’s time to create and activate your virtual environment which you will install Parsons into. The process is different for Mac/Linux and for Windows.

Mac/Linux Virtual Environments

The next step is to create your virtual environment within this directory. To do this, you’ll need a virtual environment manager. Python 3.4+ comes with a virtual environment manager called venv.

On the command line, type:
python -m venv $path_to_your_env/$your_env_name

The path should be the directory you created to store the virtual environments, and the environment name is a new name chosen by you.

You can activate your virtual environment by entering the following command on the command line: source $path_to_your_env/$your_env_name/bin/activate

You can tell that the environment has been activated by looking at the start of the line where it should now say (venv) (or whatever your virtual environment name is):

Windows Virtual Environments

Some Windows systems have a virtual environment manager, virtualenv, preinstalled. You can try to use it with the following two commands:

python -m virtualenv venv

The first command creates a virtual environment named “venv” and the second activates it.

If the above commands work, you can skip the rest of this section. Otherwise, you may need to install a virtual environment manager yourself.

The Windows virtual environment manager is called virtualenvwrapper. We’re going to install it from source using git.

You may need to download git if you’ve never used it before on your computer. You can check whether git is installed by typing git --version into the command line and seeing if you get a version number or an error. Some folks need to take an extra step and add git to system path.

Once you’ve got git installed, you can use it to get virtualenvwrapper with the following commands:

git clone
cd virtualenvwrapper-win
python install

Then, find the Scriptsdirectory for your Python installation, such as C:\Users\<User>\AppData\Local\Programs\Python\Python37\Scripts\.

Add the Scriptsdirectory to your $PATH. If you’ve never done this before, check out this guide to adding environmental variables to $PATH on Windows.

Next, create a virtual environment for Parsons, by running the following command on the command line: mkvirtualenv parsons

Finally, you can activate this virtual environment for use by running the following command on the command line: workon parsons

Download and Install Parsons

Downloading and installing Parsons should be as simple as making sure your virtual environment is activated and then typing pip install parsons into the command line.

The above approach gets the most recent stable release of Parsons on PyPI. This is almost always the version of Parsons that you’ll want.

However, in some cases you may want the very latest version. For instance, perhaps you need a new integration that was just added, or a fix that was just fixed. To get the latest version of Parsons from Github, use the command:

python -m pip install git+

Don’t have pip installed? Some older versions of Python don’t come with pip. If you get an error like ‘pip not found’, go ahead and install pip by following the instructions here. You can also ℹ️ learn more about pip.

Test That Installation Worked

The final step is to test that the installation process worked. You can test this by importing Parsons within a Python script, or through a Python interpreter.

Option 1: Test via Python Script

To write a Python script that imports Parsons, you’ll need to open up an editor. You can use a plain text editor or a command line editor, but we recommend you use a code editor (or “integrated development environment”/IDE ) like Visual Studio, Sublime Text, PyCharm, or Notepad++. (Pour one out for Atom, a great code editor killed by Microsoft’s monopolistic practices.)

Once you’ve got your editor set up, create a file with it called (You can call it whatever you like, actually, just make sure it ends in .py.) Add the following code:

from parsons import Table

print(“You have successfully installed Parsons!”)

You can then save and run the file. Some code editors have a “run” button, feel free to use that. Alternatively, you can run the code by going to the command line and typing python

If you get a “file not found” error, you may be in the wrong directory. Make sure to run python from the directory the file is in.

If you get a ModuleNotFoundError “no module named Parsons”, double check that your virtual environment is activated. (I frequently forget, and get errors because of it all the time!) If the virtual environment is activated, then this error means there was a problem with the install. See the “Common Installation Problems” section below and if none of those apply, please reach out for help.

If you see the success message: congrats! You have, in fact, successfully installed Parsons!

Option 2: Test via the Python interpreter

The Python interpreter is an interactive interface that you can type Python commands into. It looks like this:

To enter the Python interpreter from the command line, just type python. To leave the interpreter and go back to the command line, type exit().

Once you’re in the Python interpreter, you should be able to import Parsons. Type:

from parsons import Table

If this runs without error, congrats! You’ve successfully installed Parsons. If you get ModuleNotFoundError: No module named 'parsons’ then there was a problem with the install. See the “Common Installation Problems” section below and if none of those apply, please reach out for help.

Common Installation Problems

Psycopg2 Problems

The psycopg2 package is a common pain point for installs. Unfortunately, it is necessary for connecting to postgres and Redshift. If you don’t want to use that functionality, we are working on an alternative install process—please reach out if you’d like to use it.

In the meantime, here are some known problems and workarounds:

General problems with psycopg2, psycopg2-binary, postgres, and pg_config (all operating systems)

Try uninstalling and reinstalling each of the following libraries. In some cases, you may get told there was no library to uninstall, which might actually have been the issue itself!

Psycopg2 (most likely the issue)

pip uninstall psycopg2

pip install psycopg2 


pip uninstall postgres

pip install postgres 


pip uninstall psycopg2-binary

pip install psycopg2-binary 

You can also try installing each of the above libraries with the --no-cache-dir flag:

pip install psycopg2-binary --no-cache-dir

Errors referencing psycopg and psycopg2-binary on Macs with M1 chips (Mac)

(Check if your Mac has an M1 chip.)

If your M1 Mac gives you an error like pg_config executable not found try this command:

brew install postgresql

Additionally, Macs with M1 chips seem to have their own special problems with psycopg2. When trying to install Parsons, you may see errors like:

Encountered error while trying to install package psycopg2-binary

library not found for -lssl.

Unfortunately, there is no one solution for this problem. Here are three things to try—if neither works for you, please ask for help on the Slack.

Approach 1

First run: brew install openssl

Then run: env LDFLAGS="-I/opt/homebrew/opt/openssl/include -L/opt/homebrew/opt/openssl/lib" pip install psycopg2-binary

Then run: env LDFLAGS="-I/opt/homebrew/opt/openssl/include -L/opt/homebrew/opt/openssl/lib" pip install parsons

You may also need to pip uninstall psycopg2-binary before running those steps.

Approach 2

Run this set of commands:

brew install libpq --build-from-source brew install openssl export LDFLAGS="-L/opt/homebrew/opt/[email protected]/lib -L/opt/homebrew/opt/libpq/lib" export CPPFLAGS="-I/opt/homebrew/opt/[email protected]/include -I/opt/homebrew/opt/libpq/include" pip3 install psycopg2

Approach 3

Run this set of commands:

export CPPFLAGS=-I$(brew --prefix openssl)/include  

export LDFLAGS=-L$(brew --prefix openssl)/lib

Psycopg2 extension error (Windows)

Parsons relies on a library called psycopg2-binary that allows it to connect to Postgresql databases. If you are getting an error that includes these lines:

      building 'psycopg2._psycopg' extension
      error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools":

then you need to install the Microsoft C++ compiler so that pip can compile the library. To do so visit the link in the error message or this Microsoft website. Download the build tools, and install it without any extra options. (You can include extra options if you also plan on developing C++ code, but only the basic install is required for Parsons.)

When the installation is done, repeat the Parsons installation process and the error should be fixed.

issues with Python 3.10

Some users have reported issues with Python 3.10. Some of Parsons’s dependencies may not work with 3.10, so if you’re having issues you can’t otherwise fix, try uninstalling 3.10 and installing 3.9.

Other Problems

Lack of permissions on work computers

Some people, when trying to install Parsons on their work computer, find they lack the appropriate permissions. Unfortunately there’s no workaround for this; you’ll need to contact your administrator to see about getting access.

Sometime even when you do have the appropriate permissions, you aren’t able to execute a command unless you run it as an administrator. On Windows, running a command as an administrator should look like this:

Please note that when changing permissions settings, you may need to restart the command line or application you are using in order for the new settings to take effect.

Python not found on Windows after installing

If you’ve installed Python but aren’t able to run it, try adding it to the Windows PATH by following this guide.

Python vs Python3 command

On some computers, you’ll need to use python3 instead of python when running Python from the command line.

Using Visual Studio Code

Visual Studio Code has a command line/terminal window built in to the app. You can use either this build-in command line interface, or your operating system’s command line interface, whichever you prefer.

If you chose to use the build-in command line interface, and you’re getting import errors (ie ModuleNotFoundError: No module named ‘parsons’) it may be because VS Code isn’t accessing your virtual environment. Try these instructions to get your virtual environment working with VS Code.

Problems with grpcio (Mac)

grpcio errors often look like this:

Try the following from this guide:



pip install grpcio

installing Parsons with Anaconda (Windows)

When using Anaconda on Windows, you may run into trouble when you install Parsons using something other than the Anaconda terminal. For example, one person got the error: ImportError: DLL load failed while importing _psycopg: The specified module could not be found.

Following these instructions will hopefully fix the issue.

installing Parsons with Anaconda (Mac)

If you would like to install Parsons using Anaconda and you have a Mac (especially a Mac with an M1 chip) try this guide.

error in pyparsing dependency (Windows)

If you are getting AttributeError: module 'pyparsing' has no attribute 'downcaseTokens' try updating the version of pyparsing:

pip install pyparsing==2.4.2

More information on this error can be found here.

issue with Long Paths (Windows)

You may get an error which contains this advice:

HINT: This error might have occurred since this system does not have Windows Long Path support enabled. You can find information on how to enable this at

You can enable long paths by following these instructions.

No comments here
Why not start the discussion?