Spoolman: the filament inventory that your printers write into

An inventory of manufacturers, filaments and physical spools

Spoolman is a self-hosted web service for keeping track of 3D printer filament spools. The repository description is one line, and the repository agrees with it: around 2,845 stars, 284 forks, 175 open issues, MIT licensed, written in Python, and tagged 3d-printing, database, inventory and service. The default branch is `master` and the last push landed on 2026-09-24.

The data model is the interesting part, and it is three entities rather than one. A manufacturer makes filaments, a filament is a material plus colour plus weight plus density, and a spool is one physical object with a serial number, an initial weight and a current weight. That separation is what makes the service worth running: when you buy the same filament again six months later, you add a new spool against an existing filament record rather than retyping vendor and colour, and the running totals stay meaningful.

The feature list on the README is specific about what sits on top of that model. There is a REST API documented separately at donkie.github.io/Spoolman, live spool updates over websockets during a print, a community filament database maintained in its own SpoolmanDB repository, and Prometheus integration for historical analysis of filament use. Custom fields can be attached to spools, which is how people add status, purchase date or a note about a colour that does not photograph well.

Four database backends behind one FastAPI application

The `.env.example` file is the most informative page in the repository, because it documents every knob the service reads. The database is chosen with `SPOOLMAN_DB_TYPE` and accepts sqlite, mysql, postgres or cockroachdb, defaulting to SQLite when the variable is unset. The rest of the external database settings are a conventional set of host, port, name, username, password and a query string, plus a `SPOOLMAN_DB_PASSWORD_FILE` option for reading the password from a mounted file instead of the environment.

The defaults are sensible for a home server. The service binds all interfaces on port 7912, keeps its data under a per-user directory, and ships automatic nightly backups enabled by default for SQLite. Prometheus metrics are off until you set the flag.

# Host and port to listen on
SPOOLMAN_HOST=0.0.0.0
SPOOLMAN_PORT=7912

# Enable Collect Prometheus metrics at database
# Default: FALSE
#SPOOLMAN_METRICS_ENABLED=TRUE

The dependency list in `pyproject.toml` shows how little is doing the work. FastAPI and Uvicorn provide the HTTP layer, SQLAlchemy carries async drivers for aiosqlite, aiomysql and asyncpg, Alembic handles migrations, and Pydantic validates requests. Python 3.10 or newer is required. The presence of `influxdb-client` and `prometheus-client` alongside `hishel`, an HTTP caching library, suggests the service writes usage history out to a time series store rather than trying to keep that history in the relational database.

Printer integrations that decrement weight as a job runs

This is the part that turns Spoolman from a spreadsheet into a system. The README lists Moonraker and most of the front-ends built on it, including Fluidd, KlipperScreen and Mainsail, then names a separate OctoPrint plugin, OctoEverywhere, a Home Assistant integration, and an MCP server that lets an assistant manage the inventory over the Model Context Protocol. When a printer is connected, Spoolman updates spool weights as printing progresses, and several printers can report at once.

That means the source of truth for remaining filament is the printer firmware reporting progress, not a human remembering to log a finished spool. It also means the correctness of the inventory depends on the weights you entered when you added each spool, since every later number is an offset from the initial weight.

The README points at a wiki page called Filament Usage History for the Prometheus setup, and the `influxdb-client` dependency explains why a time series store appears in the dependency list at all. If you only want to know what is on the shelf, none of that matters. If you want a chart of grams per month per material, that is the axis the maintainer has built for.

A rewritten web client that ships beside the old one

Version 0.26.0, released 2026-07-31, replaced the web interface with a rewrite from scratch, and the repository tree explains the shape of that change. Both `client/` and `client_v2/` sit at the top level, along with `tests_frontend/` and `tests_frontend_v2/`, so the project is carrying two frontends and two test suites at the same time.

What the new client gained is a longer list than the old one had. The manufacturer, filament and spool pages collapsed into a single Library view that no longer fights with wide columns. Adding a spool now takes manufacturer, filament and spool information in one form. Spare spools collapse out of the way so a large collection stays browsable. The Locations page became the Dashboard and can group by any spool-based extra field rather than location alone. Free text search arrived with colour similarity, and the label designer became a real editor instead of a fixed template.

The escape hatch is documented in the README and worth knowing about. Setting `SPOOLMAN_LEGACY_CLIENT=TRUE` returns the previous client. Both ship in every release and talk to the same API, so your data is identical either way, and the README asks you to report the problem if the new client misbehaves. Version 0.26.1 followed a week later with frontend fixes including a sort order correction, a phantom in-use label, and a security fix for unsafe JSON parsing of application settings.

Label printing with QR codes and a community filament list

Labels are the mechanism that keeps the inventory honest. The client can design and print labels with QR codes for spool identification, built from spool, filament or vendor fields, and the screenshot in the README shows a 50 by 25 mm label carrying a QR code, the filament name and a colour swatch. Scanning that code is how a phone gets back to the record you just printed, and the SpoolmanDB project means the filament name on the label can match a shared record rather than something you typed.

The `pyproject.toml` development tasks show what working on Spoolman looks like from the inside. Poe drives the tasks, so the same commands cover starting the app, running the backend tests that need no database, and filling a dev instance with generated data.

[tool.poe.tasks.run]
cmd = "uvicorn spoolman.main:app"
help = "Start Spoolman."

[tool.poe.tasks.test]
cmd = "pytest tests"
help = "Runs the backend unit tests. These need no database or running server."

Two extra tasks exist for data volume: a stress seed that fills a dev instance with a large generated dataset, and a demo seed for a smaller set. Both carry a warning in their help text that they must never be pointed at real data, which is the kind of care a service that also holds your only record of what you own should take.

Where the repository stops and the wiki starts

The README is a feature tour with one short installation paragraph, and that paragraph is a link to the Installation page on the project wiki. Everything you need for a first run, including the reverse proxy advice, is on the other side of it. The README also links the REST API reference, the filament usage history page, and the Weblate project where the interface has been translated into 18 languages.

The release notes fill in the operational detail the README leaves out. Version 0.25.0 fixed Docker problems on armv7, which is a platform worth noting because the `Dockerfile` carries an explicit explanation of why: greenlet ships no 32-bit ARM wheel, so it is compiled from source there and needs libstdc++ linked in by hand. The same release started signing published images with cosign. Version 0.26.0's rewrite was followed quickly enough that 0.26.1 landed a week later, and the release cadence has stayed in the three-releases-per-two-months range.

So the honest split is this. Spoolman is a small, well-shaped service whose data model and integrations you can evaluate in five minutes by reading the README. The operational decisions, such as how to expose it safely and how each printer integration is configured, live in the wiki, and the README itself tells you to go there for installation.

Editorial conclusion

Spoolman is at its best when you own several printers and have already lost track of which spool is which. It keeps a plain inventory model of manufacturers, filaments and spools, lets the printer front-end decrement remaining weight as a job progresses, and stores everything in whichever database you already run. What the README does not settle is the printer-specific setup, which lives on the wiki installation page, and the design of the newest web client, which arrived as a rewrite in v0.26.0. Start by pointing one Moonraker instance at the REST API, add spools by scanning their QR labels, and decide later whether the Prometheus and InfluxDB history is worth wiring up.

Frequently asked questions

Official sources

1. Donkie/Spoolman on GitHub
2. Issues
3. License: MIT
4. README
5. Releases