Live demo

Install

One command. That's your part.

Docker is the recommended route on Linux and macOS; Windows has a self-contained installer that needs no runtime on the host. How long it takes is mostly your connection pulling the image — the part you do is one line.

Not sure yet? Try Bambuddy in your browser first — about ten seconds to spin up your own private demo, no install needed.
Try the demo

Full video walkthrough

Prefer to watch instead of read? @Help3d walks through the entire setup from a fresh Raspberry Pi to printing through virtual printers — Tailscale HTTPS, SSH, install, virtual printers and certificate import all in one go.

Video by @Help3d · covers Pi setup, SSH, install, Tailscale HTTPS, virtual printers and certificate import

Quick install

Paste one command into a terminal.

Docker

The easiest way to get started on Linux or macOS with Docker installed. On Windows, use the Windows installer below.

bash
curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/docker-install.sh -o docker-install.sh && chmod +x docker-install.sh && ./docker-install.sh

Native (Linux / macOS)

Installs with a Python virtual environment and a systemd/launchd service.

macOS: run the script as your normal user — not with sudo. Homebrew refuses to run as root, and a venv created by root cannot be managed by the launchd agent. The installer elevates on its own only where it is genuinely needed, and installs to ~/bambuddy by default.

bash
curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/install.sh -o install.sh && chmod +x install.sh && ./install.sh

Windows installer

Self-contained .exe for Windows 10 / 11 (x64). Bundles an embedded Python 3.13, the pre-built dashboard, ffmpeg, and the NSSM service supervisor — no Python, Node, Docker or Git required on the target machine. Installs Bambuddy as a Windows service that starts automatically at boot. Full reference in the Windows Installer Guide.

Direct download
bambuddy-windows-x64-setup.exe  ·  all releases
When it's done: Bambuddy runs as a Windows service and the installer opens http://localhost:8000 in your default browser automatically. To reach the dashboard from other devices on your LAN, open http://<windows-host-ip>:8000.
SmartScreen warning on first run: until our SignPath OSS code-signing approval lands, the installer is unsigned. Windows will show "Windows protected your PC" — click More info → Run anyway to proceed. The installer is built in public on GitHub Actions so the build provenance is verifiable.
Supported systems: Linux + macOS via the install scripts above (Debian/Ubuntu, RHEL/Fedora/CentOS, Arch Linux, openSUSE, macOS Homebrew). Windows 10 / 11 x64 via the native installer. ARM64 Windows (Surface Pro X, Snapdragon) is not currently supported — most Bambuddy deps don't ship ARM64 Windows wheels.

System requirements

What you need before or after running the install command above.

Python

  • Only needed for native install — Docker doesn't need Python on the host
  • Python 3.10 or higher (3.11/3.12 recommended)
  • pip package manager

Bambu Printer

  • Developer Mode enabled (step-by-step below)
  • Access code, IP address & serial number
  • Slicer: "Store sent files on external storage" enabled

Network

  • Printer and Bambuddy on the same local network
  • No firewall changes needed on typical home networks
  • Advanced: virtual printer feature uses ports 8883 + 990

Manual installation (Linux / macOS)

Prefer to do it yourself? Follow these steps.

Clone the Repository

Download the latest version from GitHub.

bash
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy

Create Virtual Environment

Set up an isolated Python environment for dependencies.

bash
python3 -m venv venv
source venv/bin/activate

Install Dependencies

Install all required Python packages.

bash
pip install -r requirements.txt

Start the Server

Launch Bambuddy with uvicorn.

bash
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000

Access the Interface

Open your browser and navigate to Bambuddy.

url
http://localhost:8000
Success! You should now see the Bambuddy dashboard.

Enable Developer Mode on your printer

Bambuddy talks to the printer over the LAN, which Developer Mode unlocks.

Access Printer Settings

On your printer's touchscreen, navigate to Settings (gear icon).

Find Network Settings

Look for Network or WLAN settings section.

Enable LAN Only Mode

Toggle LAN Only Mode to ON.

Enable Developer Mode

After enabling LAN Only Mode, a Developer Mode option will appear. Enable it.

Note: Developer Mode disables cloud features but enables full local control. Without it, you can only monitor (read-only).

Record the Access Code

An access code will be displayed. Write this down - you'll need it for Bambuddy.

Note IP Address & Serial Number

Find these in the printer's network settings or device info. You'll need both to connect.

Enable "Store sent files on external storage"

In Bambu Studio or OrcaSlicer, go to the Device tab and enable "Store sent files on external storage". This saves print files to the SD card so Bambuddy can extract thumbnails and 3D previews.

Don't see the option in the slicer? Newer firmware/slicer combos (e.g. P2S firmware 01.02.00.00 with Bambu Studio 2.6+) moved the toggle to the printer itself. On the printer, open Settings → Print Settings (or Print Options) and enable the equivalent option there.

Docker installation

Compose files, multi-architecture images and the update script.

Option A: Interactive Install Script (Recommended for Linux / macOS)

Prompts for configuration options and sets everything up for you. Requires a bash-compatible shell (Linux, macOS, or WSL on Windows). For native Windows, use Option B below.

bash
curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/docker-install.sh -o docker-install.sh && chmod +x docker-install.sh && ./docker-install.sh

Option B: Pre-built Image (Manual — works on Windows / PowerShell too)

No building required — just download the compose file and run. Works on any OS with Docker installed.

Linux / macOS / WSL (bash)
mkdir bambuddy && cd bambuddy
curl -O https://raw.githubusercontent.com/maziggy/bambuddy/main/docker-compose.yml
docker compose up -d
Windows (PowerShell)
mkdir bambuddy
cd bambuddy
Invoke-WebRequest -Uri https://raw.githubusercontent.com/maziggy/bambuddy/main/docker-compose.yml -OutFile docker-compose.yml
docker compose up -d

Option C: Build from Source

If you want to modify the code or build locally:

bash
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
docker compose up -d --build
bash
# Pre-built image
docker compose pull && docker compose up -d

# Built from source
git pull && docker compose up -d --build
Multi-Architecture Support: Pre-built images work on linux/amd64 (Intel/AMD) and linux/arm64 (Raspberry Pi 4/5, Apple Silicon). Docker automatically pulls the right image for your system.
Printer Discovery: For automatic printer discovery and camera streaming, use network_mode: host in docker-compose.yml. Bambuddy will then let you scan your network subnet to find printers.
macOS/Windows Users: Docker Desktop doesn't support network_mode: host. Edit docker-compose.yml: comment out network_mode: host and uncomment the ports: section. Printer discovery won't work — add printers manually by IP address.
Custom Port: To run on a different port, use PORT=8080 docker compose up -d. If you get "permission denied" errors on Linux, prefix with sudo or add your user to the docker group.
External library folders (v0.2.5b1+): The "Add external folder" feature is opt-in for operators. Set BAMBUDDY_EXTERNAL_ROOTS to a colon-separated list of host paths users are permitted to mount (e.g. BAMBUDDY_EXTERNAL_ROOTS=/external/nas:/external/projects), and bind-mount the matching host directories. Empty default disables the feature. See the wiki for the full configuration recipe and the security rationale.

Updating

The in-app Update button does not reliably perform the one-time migration from 0.2.2.x to 0.2.3. Do this one upgrade from the command line using the paths below — once you're on 0.2.3, the in-app Update button works normally again for all future releases. Full guide: UPDATING.md.

Docker

Check your image: line first — if it pins an old tag (e.g. :0.2.2.2), docker compose pull will just re-fetch that same tag. Change it to :latest or the target version.

Native install (install.sh or manual git clone)

update.sh stops the service, snapshots the database, fast-forwards to the latest release, installs dependencies, rebuilds the frontend, and restarts — with automatic rollback on failure.

bash
sudo /opt/bambuddy/install/update.sh

Troubleshooting

The three things that go wrong most often.

Can't connect to printer?

  • Verify the printer and computer are on the same network
  • Double-check the IP address, serial number, and access code
  • Ensure Developer Mode is enabled on the printer (LAN Only Mode + Developer Mode)
  • Check that ports 8883 and 990 aren't blocked by a firewall

Python version issues?

  • Run python3 --version to check your version
  • Ensure you have Python 3.10+ installed
  • On some systems, you may need to use python instead of python3

Need more help?

Check the GitHub Issues for known problems, or open a new issue if you've found a bug.

Running this in a business?

Print farms, makerspaces and teams: there is priority support, commercial licensing, and deployment help when you need someone accountable. The software stays free — these are services, not a licence fee.

See the business track

What's next?

Now that Bambuddy is running, explore the documentation to configure notifications, integrations, and more.

Read documentation Explore features

Find Bambuddy useful?

Bambuddy is free and will stay free. It's developed in the open and funded by people who choose to support it directly — no VC, no acquisition target. If it's earning a place on your home network, consider keeping it independent.

Sponsor Bambuddy Star on GitHub Open the live demo