a comprehensive guide to installing and running Parsons
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!
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
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 Python.org. (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.)
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.
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:
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
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.
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:
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):
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 https://github.com/davidmarble/virtualenvwrapper-win.git
python setup.py install
Then, find the Scriptsdirectory for your Python installation, such as
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:
Finally, you can activate this virtual environment for use by running the following command on the command line:
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+https://github.com/move-coop/parsons.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.
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.
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
test.py. (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
If you get a “file not found” error, you may be in the wrong directory. Make sure to run
python test.py 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!
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
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.
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:
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
pip install psycopg2-binary --no-cache-dir
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.
brew install openssl
env LDFLAGS="-I/opt/homebrew/opt/openssl/include -L/opt/homebrew/opt/openssl/lib" pip install psycopg2-binary
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.
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
Run this set of commands:
export CPPFLAGS=-I$(brew --prefix openssl)/include
export LDFLAGS=-L$(brew --prefix openssl)/lib
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.
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.
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.
If you’ve installed Python but aren’t able to run it, try adding it to the Windows PATH by following this guide.
On some computers, you’ll need to use
python3 instead of
python when running Python from the command line.
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.
grpcio errors often look like this:
Try the following from this guide:
pip install grpcio
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.
If you would like to install Parsons using Anaconda and you have a Mac (especially a Mac with an M1 chip) try this guide.
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.
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 https://pip.pypa.io/warnings/enable-long-paths
You can enable long paths by following these instructions.