Install Bambuddy

One command. Sixty seconds.

Quick Install

Paste one command into a terminal. Docker is recommended — native works too.

Docker Installation

The easiest way to get started. Works on any system with Docker installed.

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 Installation

Installs with Python virtual environment and systemd/launchd service.

bash 
curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/install.sh -o install.sh && chmod +x install.sh && ./install.sh
When it's done: Open http://localhost:8000 in your browser. That's it — you're running Bambuddy.
What the scripts do: Prompts for install path, port, bind address, timezone, and more. Automatically installs dependencies, sets up the service, and starts Bambuddy. Use --yes for unattended mode.
Supported systems: Debian/Ubuntu, RHEL/Fedora/CentOS, Arch Linux, openSUSE, and macOS (Homebrew).

System Requirements

Here's 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.

1

Clone the Repository

Download the latest version from GitHub.

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

Create Virtual Environment

Set up an isolated Python environment for dependencies.

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

Install Dependencies

Install all required Python packages.

bash 
pip install -r requirements.txt
4

Start the Server

Launch Bambuddy with uvicorn.

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

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

Developer Mode allows Bambuddy to control your printer directly over your local network.

1

Access Printer Settings

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

2

Find Network Settings

Look for Network or WLAN settings section.

3

Enable LAN Only Mode

Toggle LAN Only Mode to ON.

4

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).
5

Record the Access Code

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

6

Note IP Address & Serial Number

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

7

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.

Docker Installation

Pre-built images available for Intel/AMD and ARM (Raspberry Pi).

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.

Option A: Interactive Install Script (Recommended)

Prompts for configuration options and sets everything up for you:

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)

No building required - just download the compose file and run:

bash 
mkdir bambuddy && cd bambuddy
curl -O https://raw.githubusercontent.com/maziggy/bambuddy/main/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
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.

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.

bash 
# Pre-built image
docker compose pull && docker compose up -d

# Built from source
git pull && docker compose up -d --build

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

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.

What's Next?

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

Read Documentation Explore Features