Installing pliers

The easiest way to install pliers is with pip. For the latest stable release:

pip install pliers

Or, if you want to work on the bleeding edge:

pip install pliers git+


By default, installing pliers with pip will only install third-party libraries that are essential for pliers to function properly. These libraries are listed in requirements.txt. However, because pliers provides interfaces to a large number of feature extraction tools, there are literally dozens of other optional dependencies that may be required depending on what kinds of features you plan to extract (see optional-dependencies.txt). To be on the safe side, you can install all of the optional dependencies with pip:

pip install -r optional-dependencies.txt

Note, however, that some of these Python dependencies have their own (possibly platform-dependent) requirements. Most notably, python-magic requires libmagic (see here for installation instructions), and without this, you’ll be relegated to loading all your stims explicitly rather than passing in filenames (i.e., stim = VideoStim(‘my_video.mp4’) will work fine, but passing ‘my_video.mp4’ directly to an Extractor will not). Additionally, the Python OpenCV bindings require OpenCV3 (which can be a bit more challenging to install)–but relatively few of the feature extractors in pliers currently depend on OpenCV, so you may not need to bother with this. Similarly, the TesseractConverter requires the tesseract OCR library, but no other Transformer does, so unless you’re planning to capture text from images, you’re probably safe.

API Keys

While installing pliers itself is usually straightforward, setting up some of the web-based feature extraction APIs that pliers interfaces with can take a bit more effort. For example, pliers includes support for face and object recognition via Google’s Cloud Vision API, and enables conversion of audio files to text transcripts via several different speech-to-text services. While some of these APIs are free to use (and virtually all provide a limited number of free monthly calls), they all require each user to register for their own API credentials. This means that, in order to get the most out of pliers, you’ll probably need to spend some time registering accounts on a number of different websites. The following table lists all of the APIs supported by pliers at the moment, along with registration URLs:

Transformer class Web service Environment variable(s) Variable description
WitTranscriptionConverter speech-to-text API WIT_AI_API_KEY Server Access Token
IBMSpeechAPIConverter IBM Watson speech-to-text API IBM_USERNAME, IBM_PASSWORD API username and password
GoogleSpeechAPIConverter Google Cloud Speech API GOOGLE_APPLICATION_CREDENTIALS path to .json discovery file
GoogleVisionAPITextConverter Google Cloud Vision API GOOGLE_APPLICATION_CREDENTIALS path to .json discovery file
GoogleVisionAPIFaceExtractor Google Cloud Vision API GOOGLE_APPLICATION_CREDENTIALS path to .json discovery file
GoogleVisionAPILabelExtractor Google Cloud Vision API GOOGLE_APPLICATION_CREDENTIALS path to .json discovery file
GoogleVisionAPIPropertyExtractor Google Cloud Vision API GOOGLE_APPLICATION_CREDENTIALS path to .json discovery file
GoogleVisionAPIWebEntitiesExtractor Google Cloud Vision API GOOGLE_APPLICATION_CREDENTIALS path to .json discovery file
ClarifaiAPIExtractor Clarifai image recognition API CLARIFAI_API_KEY API key

Once you’ve obtained API keys for the services you intend to use, there are two ways to get pliers to recognize and use your credentials. First, each API-based Transformer can be passed the necessary values (or a path to a file containing those values) as arguments at initialization. For example:

from pliers.extractors import ClarifaiAPIExtractor
ext = ClarifaiAPIExtractor(app_id='my_clarifai_app_id',

Alternatively, you can store the appropriate values as environment variables, in which case you can initialize a Transformer without any arguments. This latter approach is generally preferred, as it doesn’t require you to hardcode potentially sensitive values into your code. The mandatory environment variable names for each service are listed in the table above.

from pliers.extractors import GoogleVisionAPIFaceExtractor
# Works fine if GOOGLE_APPLICATION_CREDENTIALS is set in the environment
ext = GoogleVisionAPIFaceExtractor()