There are two ways to install Parsons: for use, and for contribution/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:
If, instead of a Python version number, you get some kind of error like “python not found”, you need to install Python.
To install Python on Windows, follow these instructions (steps 1 through 4 under the heading “Install Python”). 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. Ideally, you want a version that starts with 3, rather than 2. 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.
Mac/Linux Virtual Environments
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.
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. If your version is lower than Python 3.4, you’ll have to install a virtual environment manager like virtualenv. You can do this by typing pip install virtualenv in the command line. (Pip typically is installed along with Python, but some older versions of Python don’t have it. 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 following commands are slightly different depending on whether you’re using Python 3.4+ and venv, or Python < 3.4 and virtualenv.
If you’ve got Python 3.4 or higher:
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.
If you’ve got a lower Python version:
On the command line, type virtualenv $path_to_your_env/$your_env_name Again, the path should be the directory for storing virtual environments, and the env name is a new name.
Regardless of what version you’re on, 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
Windows Virtual Environments
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 cd virtualenvwrapper-win python setup.py install
Then, find the Scriptsdirectory for your Python installation, such as C:\Users\<User>\AppData\Local\Programs\Python\Python37\Scripts\.
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:
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 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 python test.py.
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!
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 when installing. 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:
Error installing psycopg2-binary on Macs with M1 chips (Mac)
building 'psycopg2._psycopg' 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:
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.
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.
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.
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.
(Note: this may also be an issue on Mac with Anaconda, but it’s only been found so far on Windows with Anaconda.)
Extra Info
Using the Command Line ℹ️
Command line interfaces let you do a lot of different things on your computer, including installing and running programs and navigating the directory structure of your computer.
On Macs/Linux the default command line interface is called a Terminal and on Windows it is called the Command Prompt. Command line interfaces are also sometimes called shells. Look for this program on your computer and open it up.
The commands you can use in the command line differ somewhat dependning on whether you’re using Mac/Linux or windows.
Mac/Linux:
You can use pwd (“print working directory”) to figure out where you currently are.
To move around, use cd (for example cd .. means “go up one directory” or cd my_folder which means “go into my_folder”).
Use ls to list all the files and folders in your current directory.
You do not have to type everything on the command line out by hand. You can auto-complete the names of files/folders in your current directory by tapping the tab key. On Mac/Linux you can also tab-complete installed programs. And you can access previous commands via the up and down arrows. Save your hands! Learn these tricks.
Understanding Pip ℹ️
Pip is the Python package manager. Packages (also commonly known as “libraries”) are Python code that have been bundled up in a certain way (“packaged”) so they can be easily installed and used.
By default, pip installs from the Python Package Index or PyPI, but you can tell pip to install from a branch on Github or even from a folder on your machine. All you need is a package with the right files. The specifics of those files, and how to create your own package, is a much more advanced topic.
Essentially when you type pip install parsons[all] (or pip install anything!) you’re saying “Go find this project on PyPI and install it.” (Here’s Parsons on PyPI!)
PATHs vs paths ℹ️
Paths are how we refer to a file or program’s location in the file system. For example, /home/janedoe/virtualenvs says that within the top-level directory home there is a directory named janedoe, and within janedoe there is a directory virtualenvs.
/home/janedoe/virtualenvs is an absolute path because it specifies exactly how to get there no matter where you are in the system. The path janedoe/virtualenvs is a relative path because it only works if you use it from the home directory. Trying to use a relative path from the wrong location is a common source of command line errors!
On Windows, absolute paths look a little different. They start with the letter of the hard drive they’re in, ie C:\Users\JaneDoe\Virtualenvs.
In these instructions we try to use absolute paths, even though they’re a little wordier, because it’s less likely to cause problems for you if you run them from an unexpected place.
In addition to paths, there’s an important environmental variable called $PATH. The $PATH is a list of absolute paths your computer will check when searching for installed libraries and scripts. You can check what’s currently in your $PATH by typing echo $PATH (Mac/Linux) or echo %PATH% (Windows).
When you activate your virtual environment, the path to the environment is placed as the first path. Paths are checked in order from first to last. You can check what packages have been installed in your virtualenv (and thus should be available on the path when the virtualenv is activated) by looking in lib/site-packages.
If you’re trying to run something you’ve installed, but your computer says it doesn’t exist, it may be because the computer doesn’t have the right information in its $PATH. This happens to me all the time when I forget to activate my virtual environment!
