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

Network

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

Quick Start

Follow these steps to get Bambuddy running on your system.

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
Windows users: Use venv\Scripts\activate instead.
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.

Docker Installation (Recommended)

The easiest way to run Bambuddy. 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: Pre-built Image (Fastest)

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 B: 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