# mlb-led-scoreboard drives an LED matrix with live MLB data

> mlb-led-scoreboard is a Python application that renders live Major League Baseball scores onto an RGB LED matrix attached to a Raspberry Pi through the GPIO pins, with pregame screens, division standings, editorial blurbs and custom layouts. It suits a fan who wants the game on the wall, and it needs specific board dimensions and a Pi that is not a Zero.

**MLB-LED-Scoreboard/mlb-led-scoreboard** — An LED scoreboard for Major League Baseball :baseball:

- Repository: https://github.com/MLB-LED-Scoreboard/mlb-led-scoreboard
- Stars: 721 · Forks: 131
- Language: Python
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/mlb-led-scoreboard-mlb-led-scoreboard

## The hardware defines the feature set

mlb-led-scoreboard is an LED scoreboard for Major League Baseball that displays a live scoreboard for your team's game on that day, and it requires a Raspberry Pi and an LED board hooked up via the GPIO pins. The board sizes are listed with a caveat that is worth reading before you buy anything, because the smallest one gives you noticeably less. The 32x32 is described as having a limited number of features, the 64x32 is the most supported, and there are also 64x64, 128x32 and 128x64 boards. The 64x64 and the wide boards exist for the multi game and standings layouts, while the 32x32 is the one that forces compromises elsewhere in the software. There is also a note about a specific platform, that Raspberry Pi Zero has had numerous reports of slowness and unreliability during installation and running the software, which is a strong signal that the Pi Zero is not a target. The README links a sample parts list from Adafruit, and the topic tags name Adafruit, Raspberry Pi and RGB LED, so the hardware list is the first thing to get right.

## The refresh cadence is fixed and worth knowing

The live game display can show games in action and can optionally rotate every 15 seconds through each game of the day, and the board refreshes the list of games every 15 minutes. Those two numbers are the defining characteristic of the project. The software is not pushing updates as they happen, it is polling an MLB data source on a fifteen minute cycle and drawing whatever the current state is. That has consequences. A scoring play appears on your wall when the next refresh lands, not when it happens. A game that ends while the board is showing a different matchup is not noticed until the rotation reaches it. It also means the display can be left running indefinitely on a cheap data connection. The pregame screen is the other half of the live behaviour, since if a game has not started yet, a pregame screen will be displayed with the probable starting pitchers, which is the screen most visible for most of the day, since most of a game day is spent waiting for the first pitch.

## Standings alternate because a small board cannot show both numbers

The division standings feature shows a constraint-driven design decision that says something about the whole project. It can display standings for the provided division, and since the 32x32 board is too small to display wins and losses together, the wins and losses are alternated on the board every 5 seconds. You can also specify NL Wild Card or AL Wild Card as a division to see the top 5 teams in each league's wild card race. So on a small board, the standings screen is an animation rather than a table, and the same design carries the schedule display and the pregame and postgame screens. The editorial blurbs follow the same pattern of fitting text to a constrained display. The scoreboard pulls the MLB.com editorial blurb, a headline and subhead, from the game_content endpoint and appends it to the scrolling text on the pregame and postgame screens. Recap blurbs appear on Final games and are usually published within about 30 minutes of the last out, and most games get one. Preview blurbs are wired up the same way but MLB only rarely publishes editorial previews for regular-season games, so you should expect them mostly on playoff or nationally-broadcast matchups, and the feature stays silent the rest of the time. It can be turned off by setting editorial_blurb to false in your config.json.

## Installation is a script, and it takes a quarter of an hour

The install path assumes you have Git and PIP, and the first step is the system packages:

```sh
sudo apt-get update
sudo apt-get install git python3-pip
```

Then clone and run the install script:

```sh
git clone https://github.com/MLB-LED-Scoreboard/mlb-led-scoreboard.git
cd mlb-led-scoreboard/
sudo ./install.sh
```

The documentation sets expectations on time, saying the installation process will take about 10-15 minutes, and that Raspberry Pis are not the fastest of computers, so be patient. What the script does is create a Python virtual environment, located at mlb-led-scoreboard/venv/, and install the required dependencies. It also installs the rgbmatrix binaries, taken from another open source library, the hzeller rpi-rgb-led-matrix project, and those binaries control the actual rendering of the scoreboard onto the LEDs. The requirements file shows the Python side, with MLB_StatsAPI for the data, Pillow for image work, RGBMatrixEmulator, tzlocal for timezone handling, bdfparser for fonts, and four local packages, bullpen, standings and news, which are directories in the repository rather than external dependencies. The emulator in that list is what allows the software to be developed and tested without the physical board attached.

## The source layout separates rendering from data

The top level of the repository is where the structure of the software becomes clear. There are renderers/ for the drawing code and driver/ for the hardware interaction, colors/ for the colour definitions, coordinates/ for the board layout maths, and data/ for the cached and fetched data. There are also standings/, news/ and bullpen/ as separate packages, and the last of those three is unusual enough to be worth noticing, since it is a local package in the requirements file. The configuration lives in a config.example.json with a schemas/ directory alongside it and a validate_config.py script, so configuration is validated against a schema rather than parsed hopefully. There is a cli.py and a main.py at the top level, an install.sh, a version.py, and a pyproject.toml that configures black with a line length of 120 and mypy against Python 3.13 with a set of strict-ish flags including warn_return_any and no_implicit_reexport. There is also an upgrade_to_v9.py script, which matches the important warning at the top of the README telling users upgrading to v9.0 to read the upgrading wiki page for how to convert custom configurations. That warning is the first thing in the document, which tells you the v9 configuration format was a breaking change for anyone with a custom layout.

## Personalisation runs through layouts, colours, weather and plugins

Beyond the game data, the repository supports a fair amount of personalisation, and the table of contents lists it as a section of its own. Custom board layout is the one that requires the most work and is the reason the v9 migration matters, since the layout is described in coordinates/ and a custom one has to be expressed in those terms. Custom colors come from the colors/ directory. Weather is another add-on, which for a scoreboard in a room with a window is a reasonable extra. Plugins are the extension point, and the tree has a scripts/ directory and a tests/ directory alongside them, so plugins are treated as first class. The README also has sections on running on other platforms, on controlling the display through screen rotation, on synchronizing with broadcasts, and on additional features, plus a section on command line flags. There is a Discord for support, an accuracy disclaimer in the sources section, and a section for other cool projects. Licensing is GPL-3.0, and the release history shows v9.2.2 on 2026-09-08, v9.2.1 on 2026-08-19 and v9.2.0 on 2026-08-18, with the last push on 2026-10-12.

## Conclusion

Adopt mlb-led-scoreboard when you want a wall-mounted board that shows your team's game live, and when you are prepared to assemble the matrix, run the install script on a Raspberry Pi and configure the layout yourself. Do not adopt it on a Pi Zero, because the documentation lists that model as having numerous reports of slowness and unreliability, and do not expect a browser based equivalent. Verify first that your board dimensions are one of the five supported sizes, that the 64x32 board is the one you want since it has the most supported features, and that you read the v9.0 upgrading wiki page if you are coming from an older configuration.

## FAQ

### What hardware does mlb-led-scoreboard need?

A Raspberry Pi and an LED board hooked up via the GPIO pins. The supported board sizes are 32x32, which has a limited number of features, 64x32, which is the most supported, 64x64, 128x32 and 128x64, and a sample parts list is linked from the README.

### How often does mlb-led-scoreboard update the games?

The board refreshes the list of games every 15 minutes, and when live games are shown it can optionally rotate every 15 seconds through each game of the day. The data source is the MLB StatsAPI through the MLB_StatsAPI package.

### How do I install mlb-led-scoreboard software?

Install git and python3-pip, then clone the repository and run sudo ./install.sh. The script creates a Python virtual environment at mlb-led-scoreboard/venv/ and installs the dependencies including the rgbmatrix binaries that drive the LEDs, and the process takes about 10-15 minutes.

### Can I disable the editorial blurbs in mlb-led-scoreboard?

Yes. The scoreboard appends the MLB.com headline and subhead from the game_content endpoint to the scrolling text on the pregame and postgame screens, and setting editorial_blurb to false in your config.json turns the behaviour off. Recap blurbs appear within about 30 minutes of the last out, while previews are rare outside playoff and nationally broadcast games.

## Sources

- [Issues](https://github.com/MLB-LED-Scoreboard/mlb-led-scoreboard/issues)
- [License: GPL-3.0](https://github.com/MLB-LED-Scoreboard/mlb-led-scoreboard/blob/master/LICENSE)
- [MLB-LED-Scoreboard/mlb-led-scoreboard on GitHub](https://github.com/MLB-LED-Scoreboard/mlb-led-scoreboard)
- [README](https://github.com/MLB-LED-Scoreboard/mlb-led-scoreboard/blob/master/README.md)
- [Releases](https://github.com/MLB-LED-Scoreboard/mlb-led-scoreboard/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mlb-led-scoreboard-mlb-led-scoreboard