Pinout.xyz: the Raspberry Pi pinout as source data, overlays and translations

The pinout site as a data pipeline

Pinout.xyz is the successor to the popular Pi pinout website originally hosted at pi.gadgetoid.com/pinout, and this repository holds the source files that build it. The contents are used to build pinout.xyz and its translations, which are published as subdirectories such as pinout.xyz/de/.

The project states three aims: to build a consistent workflow behind the front end, to gather useful information about the Raspberry Pi GPIO interface and add-on boards, and to invite board manufacturers to produce their own overlay files describing which pins their add-ons use. The last of those is the interesting one, because it is the reason the data is open. A manufacturer who ships a display or a relay hat knows which pins it uses, and a pinout site that only covered the Raspberry Pi's own header would be a poorer reference.

The repository layout follows the pipeline. The src/ directory holds the pages and the overlay files, common/ holds shared content, resources/ holds the orientation graphic and the flags, graphics/ holds the horizontal pinout graphics, api/ and data.json sit alongside them, draft/ is where incoming board submissions are reviewed, and pinoutxyz/ is the Python package that does the building, with tools/ for helper scripts and a Makefile for the common tasks.

The Python package metadata says it plainly: the project name is pinoutxyz, its description is Build and maintain Pinout.xyz, and it requires Python 3.9 or later with only Markdown and PyYAML as hard dependencies.

The overlay model and what a translation may change

The translation design is the most transferable idea in the repository, and it is worth understanding precisely.

Board metadata lives once, in src/en/overlay. A translation is an overlay on top of it: a file at src/<languagecode>/overlay/<board>.md that holds only the text you have changed. Anything you leave out falls back to English, which means a board with no file at all still gets a page in your language. There is no duplication of pin tables, no synchronisation problem, and a translation cannot drift out of date in the parts it does not touch.

The constraint is that only four things are yours to change: the name, the description, the page URL, and the name of each pin or I2C device. The README shows the whole of the German translation of the Display-o-Tron as a short Markdown file with a front matter block carrying the description and the pin names, and the rest of the file is the page body.

That constraint is the point. A translation layer that could rewrite any field would allow a translator to change a pin's function or a board's name in a way that contradicts the manufacturer, and the site would then be publishing incorrect hardware information. Restricting translations to names and prose keeps the technical content single sourced.

The same overlay idea is reused for board submissions, where a manufacturer starts from the template at draft/overlay/template.md and pushes the result into the /draft folder for review before publication.

The pinoutxyz CLI: build, serve, publish, unpublish

The package installs a command called pinoutxyz, and the Makefile wraps it in a set of named targets that are worth reading because they describe the whole workflow.

Building is either a single language or a whole site. make html runs the build for one language, make site runs the full site build, and make dist builds the site with minification. Serving has the same two forms, with make serve running the server and make watch serving with a rebuild whenever anything under src, common or resources changes.

There are also two check targets that have no build output at all. make translations runs a check on the translations, and make links runs a check on links, which is the sort of task that keeps a documentation site from rotting once it has hundreds of pages and dozens of languages.

The board submission loop is driven by the command line rather than the Makefile. A contributor publishes their draft overlay into the live tree to preview it, which is what the README asks you to do before opening a pull request:

python3 -m pinoutxyz boards publish myboard
make serve

You then open http://127.0.0.1:8080 in your browser, check that the page renders as intended, and file the overlay back into the draft folder:

python3 -m pinoutxyz boards unpublish myboard

The README notes the two practical snags: you need several Python modules installed, which the dependencies target handles with pip install -r requirements.txt from the top of the tree, and a preview that looks wrong is often a browser cache problem, fixed by erasing the image and cache file only.

Running the site in a container with a language variable

The Dockerfile builds the site as a Python package and serves it with the same CLI the local workflow uses, and the image exposes port 8080.

The build is short because the work is done by the builder rather than by hand. It installs the package in editable mode with the serve and api extras, and the container command runs the server with the watch flag and a language taken from an environment variable, defaulting to English.

The documented commands are three. You build the image with docker build -t pinout.xyz ., you run it with docker run -p 8080:8080 pinout.xyz, and you browse to http://127.0.0.1:8080. For development you mount the repository over the application directory so the container rebuilds when you edit:

docker run -p 8080:8080 -v "$(pwd):/app" pinout.xyz

The language is a runtime variable, so serving German is a flag rather than a different image:

docker run -p 8080:8080 -e PINOUT_LANG=de pinout.xyz

Two conveniences follow from the builder being installed in the image. The pinoutxyz command is on the path inside the container, so you can list translations and boards with docker exec, and a draft board can be baked into the image at build time with the PUBLISH_DRAFT build argument, which the Dockerfile applies only when the argument is not empty.

CC-BY-SA with photography carved out

The licensing is the part of the README that requires the most care, and it is deliberately split.

The repository is under a Creative Commons Attribution-ShareAlike 4.0 International License. The README explains why: to support translation efforts, and to allow people to build documentation and tools with the data. The licence was previously explicitly non-commercial, and the change is explained in issue 481.

Two carve-outs make the data usable in published work. The pinout-graphic-horizontal files in the graphics directory and the pi-orientation graphic in resources are included under the same licence specifically to permit commercial use, including publication in books and magazines with appropriate attribution. The flags in resources/flags come from the flag-icons project and are MIT licensed, and the Spanish flag is the civil version with the coat of arms removed to keep the file small.

Then there is what the licence does not cover. All board photography is excluded, whether it was supplied by manufacturers or customers via a pull request without an explicit licence grant, or supplied under the implicit permission of the author's employment at Pimoroni. Re-use of product photography is normally assumed to be implicitly permitted for resale or promotional purposes, but the README is blunt that an implicit licence cannot be passed on. YMMV is the summary.

For anyone building a derivative site, the README asks for attribution in the page footer, naming the original site and its author and the maintainer of the fork, and it mentions the project's funding options for commercial ventures.

Where Pinout.xyz is the wrong tool

Three cases point elsewhere.

The first is a project that needs the product photography or the silkscreen artwork, because the photographs are outside the licence. A documentation site that shows the board itself rather than a diagram has to source its own images.

The second is a case where the pinout data is not the hard part. If your project needs the GPIO electrical characteristics, the pin's drive strength or the board's power requirements, a pinout table is a reference to the header, not to the silicon, and the vendor's own documentation and the GPIO specification remain the sources you need.

The third is a single board with no translation plans. The machinery here, the overlay model, the language checks, the link checks and the multi language build, exists to support a site with dozens of boards in many languages. For one page about one hat, it is a large amount of infrastructure.

One maintenance observation is worth recording. The repository publishes no GitHub releases, so the version history is the commit history, and the package version in pyproject.toml is 1.0.0. The changelog lives in changelog.md at the root, the TODO list in TODO.md, and there is a phatstack/ directory whose purpose the README does not describe. For a project whose value is the data rather than the code, that is a reasonable shape, but it does mean the data and the site are versioned together in a way a consumer of the API should keep an eye on.

Editorial conclusion

Adopt Pinout.xyz if you are building documentation, a tool or a teaching aid around Raspberry Pi GPIO pinouts and want the data in a form you can translate, script and republish under an open licence. Do not adopt it expecting board photography you can reuse, because the licence explicitly excludes it, and do not use it as a substitute for the vendor's own pinout data where accuracy is critical. Verify three things first: that the board you care about is actually covered, since coverage depends on manufacturer contributed overlays; how the translation overlay model handles the fields you want to change, because only four things are translatable, namely the name, the description, the page URL and the name of each pin or I2C device; and what the build pipeline gives you, since the CLI can build a single language, build a whole site or minify a distribution. The licence is CC-BY-SA-4.0, the last push was on 2026-09-28, and the repository publishes no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-SA-4.0
3. pinout-xyz/Pinout.xyz on GitHub
4. Project website
5. README