Spoolman tackles a problem many 3D printing enthusiasts and operators face: how to keep accurate, real-time track of filament spools across multiple printers and platforms. The challenge is not just inventory management but synchronizing spool weight updates as prints proceed, especially when dealing with several printers concurrently. Spoolman provides a self-hosted Python web service that centralizes filament inventory, offers real-time updates via WebSocket, and integrates seamlessly with popular 3D printing environments.
what spoolman does and how it works
At its core, Spoolman is a REST API-driven backend written in Python, designed to manage filament spool inventory for 3D printers. It supports real-time synchronization of spool usage data using WebSocket connections, which means as a print job progresses on any connected printer, the spool weight updates propagate instantly to the central inventory.
The service supports multiple database backends including SQLite, PostgreSQL, MySQL, and CockroachDB. This flexibility allows Spoolman to run in lightweight setups with SQLite or scale up to more robust distributed SQL databases like CockroachDB for multi-node deployments.
Integration with the 3D printing ecosystem is a key feature. Spoolman connects with Moonraker (the Klipper API server), OctoPrint, OctoEverywhere, and Home Assistant, among others. This means it can listen to print progress events and spool usage from different platforms concurrently, updating the central spool inventory accordingly.
The built-in web client provides a user-friendly interface for managing spools, printing QR code labels for easy scanning, and supports custom fields to track additional spool metadata. Multi-language support via Weblate spans 18 languages, indicating a mature community-driven localization effort.
Prometheus integration adds the ability to collect metrics on filament usage over time, enabling historical analysis and monitoring.
what makes spoolman’s real-time sync and multi-backend approach interesting
The standout technical aspect of Spoolman is how it handles concurrent updates from multiple printers across different platforms, all feeding spool usage data in real time through WebSockets. Managing concurrent state mutations on shared resources like spool weights is notoriously tricky, especially in distributed environments.
Under the hood, Spoolman maintains a centralized spool database and listens to live updates via WebSocket streams. When a print job consumes filament, the corresponding spool’s weight is decremented immediately and broadcast to all connected clients. This keeps every interface, from the web UI to integrated platforms, perfectly in sync.
Supporting four database backends introduces complexity but also flexibility. The code abstracts database operations via an ORM or similar layer to unify interactions. However, database-specific quirks and transactional guarantees differ, which can affect concurrency handling and consistency. For example, SQLite is simple but limited in concurrency, while CockroachDB offers distributed consistency but adds operational overhead.
The integration with multiple 3D printing platforms means Spoolman must normalize differing event streams and API models into a consistent internal representation. This requires careful design to avoid race conditions and ensure accurate spool tracking when multiple printers might consume from the same filament spool simultaneously.
The codebase reflects these tradeoffs with clear modularity around database adapters and platform connectors. The WebSocket implementation uses asynchronous Python libraries to handle multiple live connections efficiently.
On the downside, the need to support multiple backends means increased maintenance burden and potential edge cases in concurrency. Also, as a self-hosted service, it requires some setup and infrastructure knowledge, especially for advanced databases beyond SQLite.
explore the project
The repository organizes its code into backend API components, database adapters, and platform integration modules. The README points to a detailed Installation page on the project Wiki for getting started, which covers setup steps for different environments.
Key resources include the REST API documentation, WebSocket protocol details, and configuration guides for connecting Moonraker, OctoPrint, and Home Assistant.
The web client source is bundled with the backend, offering QR code label printing and multi-language UI. The localization files are managed through Weblate, enabling community contributions.
Metrics integration via Prometheus is documented, allowing users to set up monitoring and historical usage visualization.
verdict
Spoolman is a solid choice if you manage multiple 3D printers and want a centralized, real-time filament inventory system that integrates with your existing platform stack. Its support for multiple databases means it can scale from simple home setups to more complex distributed environments.
The real-time synchronization across multiple printers and ecosystems via WebSocket is well-implemented, solving a real pain point for 3D printing operators who juggle filament tracking manually or with fragmented tools.
Limitations include the complexity of self-hosting and the added maintenance overhead from supporting several database backends. For users comfortable with Python environments and willing to invest some time in setup, Spoolman offers a pragmatic and extensible solution.
The 18-language support and QR code labeling add polish that benefits usability and adoption.
Overall, Spoolman is worth exploring if your workflow involves diverse 3D printing platforms and you need accurate, concurrent filament inventory management in production or at scale.
Related Articles
- Pydoll: Async-native Chromium automation with typed extraction for web scraping — Pydoll is a Python library for Chromium automation using Chrome DevTools Protocol. It offers async-native APIs and Pydan
- Scrapy: a modular Python framework for scalable web scraping — Scrapy is a Python framework designed for efficient and extensible web scraping, featuring a powerful selector system an
- Crawlee Python: a flexible dual-crawler framework for web scraping and automation — Crawlee Python offers a dual approach to web scraping with lightweight HTML parsing and headless browser automation, bal
- Browser Harness: a self-healing LLM agent for browser automation via Chrome DevTools — Browser Harness enables LLMs to automate browsers by dynamically generating helper functions using the Chrome DevTools P
- Scrapling: adaptive web scraping with AI integration for resilient data extraction — Scrapling offers an adaptive web scraping framework with AI integration to handle site changes and anti-bot systems, sup
→ GitHub Repo: Donkie/Spoolman ⭐ 2,415 · Python