open-source software for tallying ranked-choice voting elections

ballot, choice, election, ranked, rcv, single, tally, transferable, stv, vote, voting
pip install OpenRCV==0.0.1-alpha



Build Status Coverage Status Read the Docs Status

OpenRCV is an open source software project for tallying ranked-choice voting elections like instant runoff voting and the single transferable vote. It also supports auditing, reporting, and ballot file conversion. It can be used both as a command-line tool or as a Python library.

OpenRCV is distributed for free on PyPI. The project page and source code are on GitHub. Project documentation is hosted on Read the Docs.

It is licensed under a permissive open source license. See the License section for license details.

To report a bug or request a feature, visit the issue tracker. You can also contact the author listed below.

Note (as of December 2014): This project is not yet usable, but we are actively working on it.


  • Completely open and extensible.
  • Tested against the publicly available test cases in the open-rcv-tests repository.
  • Exposes both a command-line API and a Python API.
  • Both APIs support neutral input and output text formats to allow interoperability with other applications and programming languages. For example, round-by-round results can be output as JSON to be--
    • Passed to a custom "pretty" HTML renderer, or
    • Checked numerically (i.e. independent of presentation) against test data.
  • Detailed logging while counting contests.


OpenRCV can be run using Python 3.4 (preferably 3.4.2 or later).

If you do not already have Python 3.4, you can download it here.


$ pip install openrcv

If you see an error like the following in the logs, you can safely ignore it:

build/temp.macosx-10.9-x86_64-3.4/check_libyaml.c:2:10: fatal error: 'yaml.h' file not found
    #include <yaml.h>
    1 error generated.

    libyaml is not found or a compiler error: forcing --without-libyaml

Running It

To count the ballots for one or more contests, pass the path to an OpenRCV contests file:

$ rcv count data/sample.yaml

For detailed command-line help:

$ rcv --help

Testing It

$ python -m unittest discover openrcv


For information on contributing technically to the project or developing applications that interact with OpenRCV, see the Development page.


This project is licensed under the permissive MIT license. See the LICENSE file for the actual license wording.


Chris Jerdonek began writing the code on September 27, 2014.


Chris Jerdonek (