bambox

Experimental software — use at your own risk. bambox packages G-code into Bambu Lab firmware-validated archives. Incorrect 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.

What bambox is — and isn't

bambox is a Bambu Lab packaging layer. It takes G-code from any slicer and produces the .gcode.3mf archive Bambu Lab printers require — with the 544-key project_settings.config, metadata, MD5 checksums, and per-filament arrays the firmware validates.

bambox is not:

• A slicer. Slicing happens upstream (estampo + CuraEngine/OrcaSlicer). bambox packages the result — see Where This Fits.
• A profile editor. It loads and overlays bundled profiles. New printers are added by dropping in src/bambox/profiles/base_<printer>.json; there is no UI for editing profiles.
• A printer-control tool. Cloud printing lives in boo-cloud. bambox only produces the archive.

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 + validation)
    ↓ .gcode.3mf
boo-cloud (cloud printing, optional)
    ↓ → 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, and (2) the slicer settings blob (project_settings.config) that would normally come from OrcaSlicer. It generates the full 544-key settings from just a machine name and filament types.

boo-cloud handles cloud printing and printer credentials separately.

You don't need estampo or boo-cloud to use bambox — it works standalone.

Installation

pip install bambox

Or with uv:

uv pip install bambox
uv tool install bambox   # just the CLI

The core install covers packing, repacking and validation. Two optional extras pull in heavier dependencies only if you need them:

pip install "bambox[templates,thumbnail]"

Supported printers and filaments

bambox ships bundled profiles in src/bambox/profiles/. bambox pack fails loudly at entry if the requested printer or filament is not in these tables, rather than letting the archive fail at print time.

Other Bambu printers (P1P, X1C, X1, X1E, A1, A1 Mini) have firmware model IDs listed in bambox.cura.PRINTER_MODEL_IDS but no bundled profiles yet. Adding one is a matter of dropping in base_<printer>.json — contributions welcome.

Only the Bambu P1S with AMS is validated on hardware. Other models can be added by dropping in machine profiles, but require external contributor testing. If you have one of those printers and want to help, please open an issue.

CLI

bambox [-V] [-v] {pack,repack,validate}

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:

How packing works

.gcode.3mf is a ZIP archive. The packing step does three things:

1. Rewrites the G-code to meet Bambu firmware expectations (header injection, layer markers, AMS tool-change rewriting).
2. Generates a 544-key project_settings.config by layering the machine base profile (base_<printer>.json) with per-slot filament overlays (filament_<type>.json). The firmware validates this blob and rejects archives where keys are missing, arrays are the wrong length, or the embedded printer_model_id doesn't match.
3. Computes MD5 checksums and writes OPC/3MF metadata so the archive is a valid package.

Because the settings blob is printer-specific, a .gcode.3mf packed for the wrong printer is not portable. bambox validates the requested printer at pack entry and exits with a clear error if the profile is unknown or malformed.

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:

Global options

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

Archive validation

from bambox.validate import validate_3mf

Modules

BBL .gcode.3mf Format

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

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

All files include MD5 checksums validated by the printer firmware.

See docs/gcode-3mf-format.md for the full format specification.

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

Credits and attribution

The bundled machine and filament profiles under src/bambox/profiles/ are derived from OrcaSlicer and BambuStudio slicer profiles (AGPL-3.0-era sources). See THIRD-PARTY-NOTICES for full provenance, file lists, and license details. The file is also shipped inside the installed package so it remains discoverable after pip install.

License

bambox's own source code is MIT. The bundled printer/filament profiles under src/bambox/profiles/ are derived from BambuStudio 2.5.0.66 (AGPL-3.0); they remain under AGPL-3.0. The package as a whole is therefore MIT AND AGPL-3.0-only.

Full AGPL-3.0 text: LICENSES/AGPL-3.0.txt. Third-party file list and provenance: THIRD-PARTY-NOTICES.