Skip to main content

Package plain G-code into Bambu Lab .gcode.3mf files

Project description

bambox

CI codecov PyPI version Python versions

Experimental software — use at your own risk. bambox talks directly to Bambu Lab printer firmware. Incorrect packaging, settings, or G-code can cause failed prints, nozzle clogs, or physical damage to your printer. Always review output before sending to hardware.

Package plain G-code into Bambu Lab .gcode.3mf files — no OrcaSlicer required.

Known limitations

Read these before pointing bambox at a real printer. None of them are going away in the very near term.

  • Only the Bambu P1S with AMS is tested. The architecture is general and other Bambu models (X1C, A1, A1 Mini) can be added by dropping in machine profiles, but we don't have the hardware in the loop to validate them. If you have one of those printers and want to help test, please open an issue — see also the roadmap.
  • bambox cancel (CLI) is disabled. libbambu_networking rejects print-class MQTT commands (stop, pause, resume, skip_objects) when the hosting process is not an officially signed BambuStudio binary. The CLI returns a structured error pointing at docs/signed-app-gate.md, which has the full investigation. The daemon /cancel endpoint is unaffected because it also handles in-flight upload cancellation, which still works.
  • macOS always uses the Docker bridge. The native bambox-bridge binary hits the same code-signing gate on macOS and cannot send start_print — bambox detects macOS and forces the Docker path, so Docker Desktop (or a compatible runtime) must be installed and running for print, status, login, and daemon.
  • No LAN mode. Cloud connectivity to Bambu's servers is required for every bridged operation. LAN-direct support is tracked in #91.
  • No Windows native bridge. Windows users need Docker Desktop for any bridged command; Linux ARM64 users need Docker + QEMU.

bambox is a standalone Python library and CLI for creating printer-ready Bambu Lab archives from any G-code source. It handles the BBL-specific packaging format (metadata, checksums, settings) so that any slicer — CuraEngine, PrusaSlicer, KiriMoto, or a custom toolpath generator — can target Bambu printers.

What You Can Do

Pack G-code (no extra dependencies) — build .gcode.3mf archives from any G-code source with full 544-key settings generation. Works on Linux, macOS, and Windows.

Validate archives — check .gcode.3mf files for errors before printing.

Print and monitor (requires bridge) — send archives to Bambu printers via cloud and query printer status. Requires either the native bambox-bridge binary or Docker (see Bridge Setup below).

Where This Fits

bambox is part of the estampo project that decouples slicer pipelines from OrcaSlicer:

estampo (pipeline + slicer backends)
    ↓ G-code
bambox (packaging + settings + printing)
    ↓ .gcode.3mf → printer
Bambu printer

estampo orchestrates the build pipeline — plate arrangement, profile management, CI integration. It can invoke any slicer backend and delegates Bambu-specific concerns to bambox.

bambox (this project) owns: (1) the .gcode.3mf archive format that Bambu firmware requires, (2) the slicer settings blob (project_settings.config) that would normally come from OrcaSlicer, and (3) printer communication via the cloud bridge. It can generate the full 544-key settings from just a machine name and filament types.

You don't need estampo to use bambox — it works standalone.

Installation

pip install bambox

Or with uv:

uv pip install bambox

This is all you need for pack, repack, and validate. For print, status, login, and daemon you also need the bridge — see below.

Bridge Setup

The print, status, and login commands communicate with Bambu printers via a cloud bridge. You have two options:

Option A — Native binary (Linux x86_64 only):

curl -fsSL https://github.com/estampo/bambox/releases/latest/download/install.sh | sh

This installs bambox-bridge to ~/.local/bin. macOS, Windows, and Linux ARM64 users should use Option B.

Option B — Docker (all other platforms):

If you have Docker installed and running, bambox uses the estampo/bambox-bridge image automatically — no extra setup needed. This is the only supported option on macOS, Windows, and Linux ARM64. See Known limitations for why macOS cannot use the native binary.

Platform Support

Feature Linux x86_64 Linux ARM64 macOS Windows
pack, repack, validate Yes Yes Yes Yes
print, status, login (native bridge) Yes No¹ No² No
print, status, login (Docker bridge) Yes Yes³ Yes Yes

¹ Bambu Lab does not ship a Linux ARM64 build of libbambu_networking.so. ² macOS requires Docker — the native bridge is not supported on macOS. ³ Runs via QEMU emulation (amd64 image on ARM64 host).

CLI

bambox [-V] [-v] {pack,repack,login,print,validate,status,daemon}

bambox pack — Package G-code

Create a .gcode.3mf archive from a G-code file.

# Basic packaging
bambox pack plate_1.gcode -o output.gcode.3mf

# With machine profile and filament settings
bambox pack plate_1.gcode -o output.gcode.3mf -m p1s -f PLA

# Multi-filament with AMS slot and color
bambox pack plate_1.gcode -o output.gcode.3mf -m p1s \
  -f 1:PLA:#FF0000 -f 3:PETG-CF:#2850E0

Options:

Flag Description
-o, --output Output .gcode.3mf path
-m, --machine Machine profile (e.g. p1s)
-f, --filament Filament spec: [SLOT:]TYPE[:COLOR] (repeatable)
--nozzle-diameter Nozzle diameter (default: 0.4)
--printer-model-id Override printer model ID

bambox repack — Fix up existing archives

Regenerate settings in an existing .gcode.3mf for Bambu Connect compatibility. Modifies the file in-place.

# Patch existing settings
bambox repack my_print.gcode.3mf

# Regenerate settings with a specific machine and filament
bambox repack my_print.gcode.3mf -m p1s -f PLA

bambox validate — Validate archives

Check a .gcode.3mf for errors and warnings.

# Basic validation
bambox validate my_print.gcode.3mf

# JSON output for CI pipelines
bambox validate my_print.gcode.3mf --json --strict

# Compare against a reference archive
bambox validate my_print.gcode.3mf --reference known_good.gcode.3mf

Options:

Flag Description
--json Output results as JSON
--strict Treat warnings as errors (non-zero exit)
--reference Reference .gcode.3mf to compare against

bambox login — Configure credentials

Authenticate with Bambu Cloud and save printer credentials.

bambox login

Credentials are stored in ~/.config/estampo/credentials.toml.

bambox print — Send to printer

Send a .gcode.3mf to a Bambu printer via cloud.

# Print by device serial
bambox print output.gcode.3mf -d DEVICE_SERIAL

# Print by named printer from credentials
bambox print output.gcode.3mf -p my_printer

# Dry run — show AMS mapping without sending
bambox print output.gcode.3mf -d DEVICE_SERIAL -n

# Manual AMS tray assignment
bambox print output.gcode.3mf -d DEVICE_SERIAL \
  --ams-tray 2:PETG-CF:2850E0

Options:

Flag Description
-d, --device Printer serial number
-p, --printer Named printer from credentials.toml
-c, --credentials Path to credentials.toml
--project Project name shown in Bambu Cloud
--timeout Upload timeout in seconds
--no-ams-mapping Skip AMS filament mapping
--ams-tray Manual tray spec: SLOT:TYPE:COLOR (repeatable)
-n, --dry-run Show print info without sending
-y, --yes Skip confirmation prompt

bambox status — Query printer

Query printer status and AMS tray info.

# One-shot status
bambox status DEVICE_SERIAL

# By named printer
bambox status -p my_printer

# Live watch mode with custom interval
bambox status DEVICE_SERIAL -w -i 5

Options:

Flag Description
-p, --printer Named printer from credentials.toml
-c, --credentials Path to credentials.toml
-w, --watch Continuously refresh status display
-i, --interval Seconds between refreshes (default: 10)

bambox daemon — Manage bridge daemon

Start, stop, and check the background bridge daemon used for fast printer status polling.

# Check if daemon is running
bambox daemon status

# Start daemon in background
bambox daemon start

# Start in foreground (blocking)
bambox daemon start -f

# Stop daemon
bambox daemon stop

# Restart daemon
bambox daemon restart

Options (for start):

Flag Description
-c, --credentials Path to credentials.toml
-f, --foreground Run in foreground (blocking)

Global options

Flag Description
-V, --version Show installed version
-v, --verbose Enable debug logging

Python API

Packaging G-code

from pathlib import Path
from bambox.pack import pack_gcode_3mf, SliceInfo, FilamentInfo

gcode = Path("plate_1.gcode").read_bytes()

info = SliceInfo(
    nozzle_diameter=0.4,
    filaments=[FilamentInfo(filament_type="PLA", color="00AE42")],
)

pack_gcode_3mf(gcode, Path("output.gcode.3mf"), slice_info=info)

With generated settings (no OrcaSlicer)

from bambox.settings import build_project_settings

settings = build_project_settings(
    filaments=["PETG-CF"],
    machine="p1s",
    filament_colors=["2850E0FF"],
    overrides={"layer_height": "0.2"},
)

pack_gcode_3mf(
    gcode,
    Path("output.gcode.3mf"),
    slice_info=info,
    project_settings=settings,
)

Cloud printing (requires bridge)

from bambox.bridge import cloud_print, query_status

Archive validation

from bambox.validate import validate_3mf

Modules

Module Purpose
pack Core .gcode.3mf archive construction, XML metadata, MD5 checksums
settings 544-key project_settings.config builder from machine + filament profiles
bridge Cloud printing via native or Docker bridge, AMS tray mapping
validate Archive validation checks, warnings, and reference comparison
cli Typer CLI commands — delegates to other modules
cura CuraEngine Docker invocation and profile conversion
templates OrcaSlicer-to-Jinja2 syntax conversion and template rendering
assemble G-code component assembly (start + toolpath + end)
thumbnail G-code-to-PNG rendering (top-down view)
toolpath Synthetic toolpath generation for testing
credentials Credential loading and storage (~/.config/estampo/credentials.toml)
auth Bambu Cloud authentication
gcode_compat G-code rewriting for multi-filament compatibility
ui Rich console formatting, color swatches, interactive prompts

BBL .gcode.3mf Format

A .gcode.3mf is a ZIP archive containing 13-17 files:

File Purpose
Metadata/plate_1.gcode The actual G-code
Metadata/slice_info.config Print metadata (time, weight, filaments)
Metadata/project_settings.config Full slicer settings (536-544 keys)
Metadata/model_settings.config Per-plate filament mapping
Metadata/plate_1.png Thumbnail (required by firmware)
3D/3dmodel.model OPC/3MF model XML
[Content_Types].xml OPC content types
_rels/.rels OPC relationships

BambuStudio adds: cut_information.xml, filament_sequence.json, top_N.png, pick_N.png.

All files include MD5 checksums validated by the printer firmware.

Development

uv sync --extra dev
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src/bambox
uv run pytest

License

MIT

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bambox-0.4.4.tar.gz (804.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

bambox-0.4.4-py3-none-any.whl (77.6 kB view details)

Uploaded Python 3

File details

Details for the file bambox-0.4.4.tar.gz.

File metadata

  • Download URL: bambox-0.4.4.tar.gz
  • Upload date:
  • Size: 804.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for bambox-0.4.4.tar.gz
Algorithm Hash digest
SHA256 ea24a6501b6cbfa47d88cbc6f4d39c170bd02953262fb844932f9e3e10460158
MD5 ee760a1c3c1474c2d41bbbeabf2dc934
BLAKE2b-256 9c9354f0d186786c38e3d61666265ceabaf6774fb0595579bd48f4f45c657826

See more details on using hashes here.

Provenance

The following attestation bundles were made for bambox-0.4.4.tar.gz:

Publisher: release.yml on estampo/bambox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bambox-0.4.4-py3-none-any.whl.

File metadata

  • Download URL: bambox-0.4.4-py3-none-any.whl
  • Upload date:
  • Size: 77.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for bambox-0.4.4-py3-none-any.whl
Algorithm Hash digest
SHA256 21d7f8d1755d1b4362c57544ddad6948d77660eed54c6e3814997440915b9b34
MD5 a88884d8cb0c7d22086b6f4fb6d0ed97
BLAKE2b-256 efd35db6d3d9dbd9d56014f71c4f87f69a5ec2895a9c0a06e4089375439a8676

See more details on using hashes here.

Provenance

The following attestation bundles were made for bambox-0.4.4-py3-none-any.whl:

Publisher: release.yml on estampo/bambox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page