# Barcode Buddy: a Grocy barcode front end for self-hosted inventory > Barcode Buddy takes scanner input and turns it into Grocy actions, so a barcode becomes a consume, add or open event instead of a manual entry. It suits Grocy users with a scanner or an Android phone. **Forceu/barcodebuddy** — Barcode system for Grocy - Repository: https://github.com/Forceu/barcodebuddy - Stars: 607 · Forks: 82 - Language: PHP - License: AGPL-3.0 - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/forceu-barcodebuddy ## What Barcode Buddy solves for Grocy users Grocy is a self-hosted ERP for household stock, and its normal workflow is a web form: search the product, pick the amount, choose consume or add. That is fine at a desk and awkward in a kitchen with a scanner in one hand. Barcode Buddy sits in front of Grocy and accepts the barcode instead. The README states the core loop plainly: "If already in the Grocys system, it will consume/add/open the product there." The product name is never typed by the user in that path. The audience is narrow and specific. You need a running Grocy instance, a Grocy API key, and ideally a barcode scanner or an Android device, all named as prerequisites in the README. If you do not already run Grocy, this project has nothing to offer you, because it is not a stock database. It is a translation layer between a barcode and an API call. The topics on the repository (addon, grocy, self-hosted, ownyourdata) describe that position accurately. ## How a scanned barcode becomes a Grocy action The flow has three stages. Input arrives either manually through the web interface or automatically from a scanner, and the README points to the example directory for the grabbing scripts. The barcode is then checked against Grocy. A known barcode triggers consume, add or open on the matching product. An unknown barcode goes the other way: the README says the product name "will be looked up and a corresponding product can be chosen in the Web UI", with openfoodfacts.org and upcitemdb.com credited as the lookup APIs. The part that is easy to miss is the tag system. The README describes it as: "Tags can be saved, if a new product contains the tag in the name, the product will be already preselected in the drop-down list." That is a heuristic on the product name, not a category match. It saves a click when your naming is consistent and does nothing when it is not. The repository layout confirms the shape of the deployment. There is an api/ directory, an openapi.json describing the HTTP surface, a wsserver.php for the websocket side, and a screen.php plus a screen module shown in the README screenshots. The example directory ships bbuddy-grabInput.service and bbuddy-websocket.service, which tells you the intended production shape is two long-running services alongside the PHP web app. ## Installing Barcode Buddy and running a first scan The README does not walk through installation itself. It says to refer to the documentation at barcodebuddy-documentation.readthedocs.io and claims installation "can be done in a couple of minutes". The repository offers four routes: bare metal on a PHP-capable webserver such as NGINX or Apache, Docker, Kubernetes (marked community support only), and Home Assistant (also community support only). The README carries a warning about the Docker image: the image name has changed, and the badge points at the f0rc3/barcodebuddy-docker repository. Check the current name there before pulling, because a stale name is the most likely reason a first attempt fails. The example directory contains an NGINX configuration and a reverse proxy configuration, plus a config.yaml. The README's own warning about proxies is worth repeating as a setup step: if you use a reverse proxy, disable caching, and it links to the setup page section on reverse proxies for the details. A cached response in front of this app means a scan that appears to do nothing. For the scanner input path, the example folder provides grabInput.py, grabInput.sh and two variants, along with a requirements.txt and a systemd unit. The README does not spell out the invocation arguments; the scripts in example/ are where the input handling lives, and example/bbuddy-grabInput.service shows how to keep the grabber running. Configuration starts from config-dist.php, which you copy and edit before the web setup runs. The two values that matter first are the Grocy URL and the Grocy API key, both listed as prerequisites in the README. Once the web UI loads, scan a product you already have in Grocy and confirm the stock count moves. Then scan something unknown and confirm it appears for selection rather than vanishing. ## Where Barcode Buddy stops being the right tool The dependency on Grocy is absolute. There is no local product catalogue and no fallback inventory. If Grocy is down or the API key is wrong, a scan has nowhere to go, and the README does not document an offline queue or a retry buffer. That is the first failure mode to design around. The second is the unknown-barcode path. Looking up a name through openfoodfacts.org or upcitemdb.com only helps if the lookup returns something useful. The README describes the lookup and the selection drop-down but does not describe what happens when the lookup returns nothing, and it does not document rollback for a scan that was applied to the wrong product. Correcting a mistake means correcting it in Grocy. Third, the tag-based preselection is name matching. A tag that appears inside an unrelated product name will preselect the wrong entry, and the README gives no rule for escaping or excluding a tag. If your product names are inconsistent, this feature quietly stops helping. Finally, the platform support is uneven. The Android client is a first-party project with Play Store and F-Droid listings. Kubernetes and Home Assistant are explicitly labelled community support only. There is no iOS client in the repository, despite that being a common thing people search for. If your household is on iPhones, the practical path is the web UI, not a native app. ## Barcode Buddy against a plain Grocy scanner workflow The honest alternative is Grocy itself. Grocy has its own barcode handling, and if your scans are occasional and you are already in the Grocy web interface, adding a second PHP application, a websocket service and a scanner grabber is more moving parts than the problem deserves. The difference in approach is where the intelligence sits. Grocy treats a barcode as a field on a product. Barcode Buddy treats a barcode as a command: consume, add or open, decided before Grocy is asked to do anything. That distinction is what makes Barcode Buddy worth running for a busy kitchen and unnecessary for a quiet one. The other real difference is the unknown-product path. In plain Grocy you create the product yourself. Barcode Buddy adds an external name lookup and a preselection list, which is the feature that makes bulk onboarding of new groceries tolerable. If you want a standalone barcode inventory tool that does not depend on another application, this is the wrong project. It is an addon by design, and the repository topics say so. ## Maintenance, upgrades and the AGPL-3.0 licence The last push to the default branch was on 2026-09-03, the same date as the v1.9.0.0 release. The release history is not smooth: v1.8.1.7 shipped in 2023, v1.8.1.8 in 2024, and then v1.9.0.0 in 2026. That gap is worth knowing before you build a workflow around it, because it means the project can sit quiet for a long stretch and then move. Upgrade cost is mostly your own environment. The README's Docker image name change is exactly the kind of thing that breaks an unattended upgrade, so pin the image and read the release notes before moving. On bare metal, composer.json and composer.lock are both present, so PHP dependency updates are part of the upgrade path. There is no documented migration tool for the data/ directory in the README, so back that up before upgrading. The licence is AGPL-3.0, described in the README as "AGPL3+ licensed". The practical consequence for most self-hosters is nil. The consequence that matters is if you modify Barcode Buddy and expose it to users over a network: the AGPL's network clause is the reason this licence is chosen for web applications, and it is stricter than MIT or Apache-2.0 in that specific case. Read LICENSE.md rather than taking this paragraph as a summary, and treat licence questions as a matter for your own counsel. ## Conclusion Adopt Barcode Buddy if you already run Grocy, have a scanner or an Android device, and want barcode scans to become consume, add or open actions without typing product names. Do not adopt it if Grocy is not your inventory system: every action here is a Grocy API call, and the README lists a Grocy API key as a prerequisite. Before trusting it with your stock, verify three things: that your Grocy instance answers on the API endpoint you configure, that your reverse proxy disables caching as the README warns, and that an unknown barcode really lands in the web UI preselection list rather than being silently dropped. ## FAQ ### What is the purpose of a barcode in Barcode Buddy? A barcode is the input the program acts on. If it is already in Grocy, Barcode Buddy consumes, adds or opens the matching product; if it is unknown, the product name is looked up and you choose the product in the web UI. ### Can a barcode be tracked in Barcode Buddy? The README describes barcodes being passed to Barcode Buddy and matched against Grocy, with unknown ones looked up through openfoodfacts.org or upcitemdb.com. It does not describe a separate scan history or tracking log. ### How to make money with a barcode scanner? This is not what the project does. Barcode Buddy is a self-hosted addon that turns scanned barcodes into Grocy stock actions, and the README describes no commercial or revenue use. ### Can a person read a barcode? The README does not cover reading barcodes by eye. It covers passing barcodes to the program from a scanner, an Android device, or manual entry in the web interface. ## Sources - [Forceu/barcodebuddy on GitHub](https://github.com/Forceu/barcodebuddy) - [Issues](https://github.com/Forceu/barcodebuddy/issues) - [License: AGPL-3.0](https://github.com/Forceu/barcodebuddy/blob/master/LICENSE) - [README](https://github.com/Forceu/barcodebuddy/blob/master/README.md) - [Releases](https://github.com/Forceu/barcodebuddy/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/forceu-barcodebuddy