ElectionGuard: the specification site behind verifiable election software

What end-to-end verifiability is supposed to mean

The README describes ElectionGuard as an open source software development kit that makes voting more secure, transparent and accessible, and it was announced at the Build developer conference under the Microsoft Defending Democracy Program.

The technical claim rests on homomorphic encryption. The README states that the SDK uses it to ensure that votes recorded by electronic systems of any type remain encrypted, secure and secret. Homomorphic encryption is what lets a tabulation run on encrypted ballot data without decrypting individual votes, which is the difference between a system that can prove its totals without revealing how anyone voted and one that cannot.

Two outputs follow from that design. The SDK enables end-to-end verification of elections, and it supports publication of results from ballot comparison audits. The description calls the latter a publishable artifact for ballot comparison audits, and the README adds the operational detail: results can be published online or made available to third-party organizations for secure validation, which is what allows individual voters to confirm their votes were correctly counted.

The point of the publishable artifact is worth pausing on. It is the part of the design that treats verification as a separate activity performed by people other than whoever ran the election. An independent party takes a published artifact and checks it against the election record, rather than trusting the tabulation that produced it.

This repository is the documentation site, not the SDK

The first thing to understand about the repository is what it actually contains. The README describes this repository as a living document to help everyone interact with ElectionGuard. The top level listing matches that description. There is a docs/ directory, an mkdocs.yml configuration file, an overrides/ directory for theme customisation, an includes/ directory and a data/ directory, alongside a Makefile, a Pipfile and a Pipfile.lock.

There is no library source here, no package directory and no test suite for the cryptography. The code lives in sibling repositories, and the README points at them: an ElectionGuard Core implemented in C++ to support ballot encryption and all phases of the Guardian key and tally ceremonies, including creation of the election package and production of the election record, plus source, package and documentation links for that core, and separate links for the ElectionGuard UI source code and its documentation. The Makefile in this repository confirms the family of projects by listing label sync targets for electionguard-cpp, electionguard-python, electionguard-api-python and electionguard-ui.

So the right mental model is a specification and documentation hub. That matters for anyone deciding whether to depend on this repository: it gives you the specifications, the road map and the published site, not an importable module.

Building the site with pipenv and make

The site is built with MkDocs and a theme plugin for it, and the README says the official ElectionGuard site is built from the /docs folder with mkdocs and mkdocs-material. To build it you need Python 3.8 or newer.

The repository uses pipenv for package and environment management, and the README includes a warning that will matter if you are following an older copy of the instructions: disregard the requirements.txt file as it will be removed in a subsequent release. The listing shows both a Pipfile and a Pipfile.lock, which is the pipenv pair, and also a legacy requirements.txt:

jinja2==3.0.0
mkdocs==1.2.3
mkdocs-material==7.2.8
mkdocs-mermaid2-plugin==0.5.2
mkdocs-redirects==1.0.3

The setup sequence is three steps. Install packages:

pipenv install

Build the site from within the virtualenv:

pipenv run make build

Then serve it locally:

pipenv run make serve

The Makefile shows what those targets do. The default target is install followed by serve, lint and build both run mkdocs build, serve runs mkdocs serve, and deploy runs mkdocs gh-deploy --force. The file carries a comment that the deploy target requires the GITHUB_ACCESS_TOKEN environment variable to be set, which is the one step that touches a credential.

There is also a release-zip-sample-data target that packages the data directory into sample-data.zip, which is how the sample data in the repository gets distributed.

Repository hygiene: security reporting, conduct and label synchronisation

Two conventions in this repository are worth knowing before you contribute, because both are policies rather than code.

The first is vulnerability reporting. The README says the developer and security community are encouraged to conduct research, report issues and suggest improvements, but asks that security vulnerabilities not be reported in public GitHub comments, unlike performance or feature bugs. Each repository has a SECURITY file with instructions on responsibly reporting security vulnerabilities under Microsoft's CVD process. A SECURITY.md file sits at the root here. This is the correct arrangement for a project whose output is used to verify ballots, and it is also the arrangement a contributor will hit first if they find a problem in the specification or the site tooling.

The second is label management. The Makefile installs github-label-sync globally and then runs it against a labels file for each of the five repositories in the family, including this one and the electionguard-cpp, electionguard-python, electionguard-api-python and electionguard-ui projects. Labels are therefore kept identical across the whole set, which is how a single issue taxonomy applies to specifications, implementations and the user interface alike.

The repository also carries a CODE_OF_CONDUCT.md and a CONTRIBUTING.md, and the README invites questions on a discussions page rather than by email, with GitHub Issues as the place for questions in the open.

Release history: the tags track specifications, not software

The tags on this repository are unusual and the naming makes the reason clear. There are three releases, and each title says what it is: v2.1 is described as the Election Guard Specification and Serialization Specification, v2.0 as the Specification, and v1.1 as the Specification. The dates are 2024-08-15, 2023-09-05 and 2022-08-25 respectively.

So the versioning rhythm here is a document versioning rhythm. A specification release changes what a ballot comparison audit artifact means and how it is serialised, which is exactly the kind of change that breaks a downstream verifier if you ignore it. The serializers and the artifact format have their own version line, separate from the election specification line, and v2.1 bundles both.

The gap between the tags is wide: v1.1 in August 2022, v2.0 in September 2023, v2.1 in August 2024. The last push to the repository was on 2026-06-10, so work on the documentation continues between specification releases. The README also links a road map page on the electionguard.vote site, which is the place to look for what is planned rather than what has shipped.

For an implementer, the practical consequence is that a specification tag is a compatibility boundary. The links section points to Microsoft Research's Verifiable Secret-Ballot Elections paper by Josh Benaloh, which is the underlying research the specification rests on.

What this repository cannot do for you

The limits follow from what the repository is, and they are worth stating plainly because the project's marketing language is ambitious.

There is no voting system here. This is a documentation and specification repository with a MkDocs site, and the code for key generation, ballot encryption and tallying is in the separate C++ core, the Python implementation and the API repository. If your goal is to run an election, this repository gives you the specifications to build against and nothing to run.

There is also no operational evidence here. The README describes what the SDK enables, and it links to third-party projects, including InfernoRed, Voting Works, the Center for Civic Design and Oxide Design, but none of that is a record of an election being run under this scheme. A reader who wants to know whether end-to-end verifiable elections have been used at scale should look for that evidence elsewhere.

The documented output is also narrower than the phrase end-to-end verification might suggest. The artifact described is for ballot comparison audits: it lets a third party compare the published ballots against the recorded results and confirm that individual votes were counted as cast. That is a specific and meaningful guarantee. It is not the same as a guarantee that the voting equipment correctly captured what the voter marked, which is a different problem, and the README does not claim otherwise.

One more practical constraint: the documentation toolchain is pinned to versions from 2021, with MkDocs 1.2.3 and the theme plugin at 7.2.8, and the README asks for Python 3.8 or newer while the repository also ships a runtime.txt and a get-pip.py at the root, suggesting the site was built for a specific interpreter version.

Choosing between the specification path and the research path

The most useful alternative comparison in the README is not a competing product but a different starting point for the same problem, and it is linked directly: Microsoft Research's Verifiable Secret-Ballot Elections paper by Josh Benaloh, referenced in the links section.

The difference in approach is between writing a specification and reading one. The research path gives you the protocol and its security argument in a form you can evaluate as a scholar: what the scheme assumes, what it proves, what an adversary is allowed to do, and where the proof stops. The specification path gives you the operational version, the serialization format and the artifact structure, which is what you need if you are writing code that consumes or produces a ballot comparison audit artifact. Working from the specification alone means accepting the security argument as settled; working from the paper alone means you still have to decide on formats and implementations yourself.

There is a second axis, and it is about who verifies. ElectionGuard's design lets you publish an artifact and have third-party organizations validate it, which spreads verification work outward. A system designed around the paper's protocol with a single trusted verifier keeps the verification inside one implementation and one process. The first is harder to adopt and easier to audit; the second is easier to build and depends more heavily on the party running it.

Either way, the choice of specification version matters, since v2.1 is the most recent tag and the serialization format changed across the v2 line. Whatever you build against, pin the specification version and make your artifact reader reject versions it does not understand rather than guessing.

Editorial conclusion

Adopt this repository if you are integrating with ElectionGuard, writing a verifier against its published artifacts, or following the specification versions as they move. Do not expect a runnable election system here, since the SDK, the C++ core and the user interface live in separate repositories, and the site itself only serves documentation. Verify first which specification version your ballot comparison audit code targets, since v2.1 is the most recent tag and the release titles refer to the specification and serialization documents rather than to code releases.

Frequently asked questions

Official sources

1. Election-Tech-Initiative/electionguard on GitHub
2. License: MIT
3. Project website
4. README
5. Releases