Installation Guide

Get Bambuddy up and running in just a few minutes.

Requirements

Python

  • Python 3.10 or higher
  • Python 3.11/3.12 recommended
  • pip package manager

Bambu Printer

  • Developer Mode enabled
  • Access code noted
  • IP address & serial number
  • "Store sent files on external storage" enabled in slicer

Network

  • Same local network
  • Ports 8883 (MQTT) open
  • Port 990 (FTPS) open

One-Line Install (Recommended)

Interactive install scripts that handle everything for you. Just run one command.

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

Windows (Portable)

The easiest way to run Bambuddy on Windows - no installation required.

batch 
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
start_bambuddy.bat
What happens: On first run, the script automatically downloads Python 3.13 and Node.js 22 (portable, no system changes), verifies checksums, installs dependencies, builds the frontend, and opens your browser.
Commands:
start_bambuddy.bat — Launch
start_bambuddy.bat update — Update dependencies
start_bambuddy.bat reset — Clean start
set PORT=9000 & start_bambuddy.bat — Custom port

Everything is stored in the .portable\ folder. Requires Windows 10 version 1803+. Supports x64 and ARM64.

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

Docker installations are updated via command line. When an update is available, Bambuddy shows these instructions in Settings → Updates:

bash 
# Pre-built image: just pull and restart
docker compose pull && docker compose up -d

# From source: pull changes and rebuild
git pull && docker compose up -d --build

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