Install & Compatibility
Where this runs
tested against v1.1.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.004s · 19.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.002s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Packer
✓ from py3dbp import Packer
Bin
✓ from py3dbp import Bin
Item
✓ from py3dbp import Item
Painter
✓ from py3dbp import Packer, Bin, Item, Painter
Optional: Painter is used for visualization, often found in examples from forks.
This quickstart demonstrates how to define bins and items, add them to a Packer instance, and then execute the packing algorithm. It also shows how to retrieve the fitted and unfitted items per bin. The `pack` method parameters `bigger_first` and `distribute_items` are highlighted due to their importance in packing strategy.
from py3dbp import Packer, Bin, Item
# Initialize packer
packer = Packer()
# Add bins
packer.add_bin(Bin('large-box', 12.0, 12.0, 5.5, 70.0))
packer.add_bin(Bin('medium-box', 11.0, 8.5, 5.5, 70.0))
# Add items
packer.add_item(Item('item-1', 5.0, 3.0, 2.0, 5.0))
packer.add_item(Item('item-2', 4.0, 4.0, 3.0, 3.0))
packer.add_item(Item('item-3', 6.0, 2.0, 1.0, 2.0))
# Pack items into bins
# Default parameters: bigger_first=False, distribute_items=False, number_of_decimals=3
packer.pack(bigger_first=True, distribute_items=True)
# Print results
for bin_obj in packer.bins:
print(f"\nBin: {bin_obj.name}, Volume: {bin_obj.get_total_volume()} cubic units, Weight: {bin_obj.get_total_weight()} kg")
print(" Fitted items:")
for item in bin_obj.items:
print(f" - {item.name} (WHL: {item.width}x{item.height}x{item.depth}, Weight: {item.weight}kg)")
print(f" Unfitted items: {len(bin_obj.unfitted_items)}")
for item in bin_obj.unfitted_items:
print(f" - {item.name} (WHL: {item.width}x{item.height}x{item.depth}, Weight: {item.weight}kg)")
Debug
Known issues
breakingThe `distribute_items` parameter behavior changed significantly between version 0.x and 1.x. In 0.x, it tried to put all items in the first bin that could fit at least one. In 1.x, when `distribute_items=True`, it distributes all items across all bins; when `distribute_items=False`, each bin attempts to pack all items independently.fixReview the desired packing logic and explicitly set `distribute_items=True` or `distribute_items=False` in `packer.pack()` to match the expected behavior for your use case. Also, be aware that the default for `bigger_first` has been observed to vary in some forks/examples (sometimes `True`, sometimes `False`). Always explicitly set `bigger_first`.
affects: 0.x to 1.x
gotchaThe `pack()` method's default parameters (`bigger_first=False`, `distribute_items=False`, `number_of_decimals=3`) may not always be optimal or align with intuitive expectations. Different forks or examples of the library might implicitly suggest different defaults for these parameters.fixAlways explicitly define the `bigger_first`, `distribute_items`, and `number_of_decimals` parameters when calling `packer.pack()` to ensure consistent and predictable results based on your requirements.
affects: All versions
gotchaThe library's last release was in July 2020. While functional, it indicates that active development might be minimal, and community support or bug fixes may be limited.fixConsider reviewing existing issues or pull requests on the GitHub repository for potential workarounds or community-contributed improvements. Be prepared for self-support or to adapt the library if specific new features or critical bug fixes are required.
affects: 1.1.2 and earlier
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'py3dbp'
The `py3dbp` library is not installed in the Python environment where the code is being executed.
fixRun `pip install py3dbp` in your terminal or command prompt to install the library.
AttributeError: module 'py3dbp' has no attribute 'Packer'
This error occurs when `py3dbp` is imported using `import py3dbp` and then attempts are made to access `Packer`, `Bin`, or `Item` directly as attributes of the `py3dbp` module (e.g., `py3dbp.Packer`), rather than importing them directly or referencing them through the module name.
fixChange your import statement from `import py3dbp` to `from py3dbp import Packer, Bin, Item` to directly import the classes. Alternatively, if you wish to keep `import py3dbp`, you would need to reference them as `py3dbp.Packer`, `py3dbp.Bin`, etc.
py3dbp incorrect packing results or distribute_items not working as expected
The `distribute_items` parameter's behavior changed significantly between `py3dbp` versions 0.x and 1.x. In version 0.x, it attempted to pack all items into the first bin that could fit at least one. In version 1.x (and 1.1.2), setting `distribute_items=True` distributes all items across multiple bins, while `distribute_items=False` makes each bin attempt to pack all items independently and return its best result. Using the wrong interpretation for your installed version leads to unexpected outcomes.
fixExplicitly set `distribute_items=True` or `distribute_items=False` when calling `packer.pack()` based on your desired packing logic, ensuring you understand the behavior for `py3dbp` version 1.x. If you want items distributed among available bins, use `distribute_items=True`; if you want each bin to be tested against all items independently, use `distribute_items=False`.
py3dbp visualization not showing (or UserWarning: Matplotlib is currently using agg)
The visualization function (e.g., `visualize_results`) typically relies on Matplotlib, and this error or warning arises when Matplotlib is configured to use a non-interactive backend (like 'agg') that cannot display figures in the current environment, or when the script is run in an environment without an active graphical user interface (GUI).
fixEnsure your environment supports GUI output (e.g., run in a Jupyter Notebook, Spyder, or a Python script with a desktop environment). If running a standalone script, you might need to set an interactive Matplotlib backend explicitly before importing `matplotlib.pyplot` (e.g., `import matplotlib; matplotlib.use('Qt5Agg'); import matplotlib.pyplot as plt`) and then call `plt.show()` after the `py3dbp` visualization. Upgrade
Version history
1.1.2latest on PyPI · released Jul 4, 2020
Audit
Dependencies
No dependency data recorded yet.