Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



Local Turk implements Amazon's Mechanical Turk API on your own machine.

It's handy if you want to:

  1. Develop a Mechanical Turk template
  2. Do some repetitive tasks on your own, without involving Turkers.

You could use it, for instance, to generate test and training data for a Machine Learning algorithm.

Quick Start


npm install -g localturk


cd localturk/sample
localturk transcribe.html tasks.csv outputs.csv

Then visit http://localhost:4321/ to start Turking.

Templates and Tasks

Using Local Turk is just like using Amazon's Mechanical Turk. You create:

  1. An HTML template file with a <form>
  2. A CSV file of tasks

For example, say you wanted to record whether some images contained a red ball. You would make a CSV file containing the URLs for each image:


Then you'd make an HTML template for the task:

<img src="${image_url}" />
<input type=radio name=has_button value="yes" /> Has a red ball<br/>
<input type=radio name=has_button value="no" /> Does not have a red ball<br/>

Finally, you'd start up the Local Turk server:

$ localturk path/to/template.html path/to/tasks.csv path/to/output.csv

Now you can visit http://localhost:4321/ to complete each task. When you're done, the output.csv file will contain


Image Classification

The use case described above (classifying images) is an extremely common one.

To expedite this, localturk provides a separate script for doing image classification. The example above could be written as:

classify-images --labels 'Has a red ball,Does not have a red ball' *.png

This will bring up a web server with a UI for assigning one of those two labels to each image on your local file system. The results will go in output.csv.

For more details, run classify-images --help.

Tips & Tricks

It can be hard to remember the exact format for template files. localturk can help! Run it with the --write-template argument to generate a template file for your input that you can edit:

localturk --write-template tasks.csv > template.html

When you're going through many tasks, keyboard shortcuts can speed things up tremendously. localturk supports these via the data-key attribute on form elements. For example, make yourer submit button look like this:

<input type="submit" name="result" value="Good" data-key="d">

Now, when you press d, it'll automatically click the "Good" button for you. Note that this feature is not available on mechanical turk itself!


To make changes to localturk, clone it and set it up using yarn:


You can run localturk.ts or classify-images.ts directly using ts-node:

ts-node localturk.ts path/to/template.html path/to/tasks.csv path/to/output.csv

To type check and run the tests:

yarn tsc
yarn test

To publish a new version on npm, run:

yarn tsc
yarn publish