Install & Compatibility
Where this runs
tested against v3.0.3 · 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.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 8.7s · import 0.000s · 367MB
368MB installed
● package 368MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
libcoal_core
✓ import libcoal_core
✗ import libcoal
The core functionality and classes are exposed via the 'libcoal_core' module, not 'libcoal' directly, despite the package name.
CollisionGeometry
✓ from libcoal_core import CollisionGeometry
✗ from libcoal import CollisionGeometry
Common classes like CollisionGeometry are members of the libcoal_core module. Direct import from libcoal will fail.
Transform3d
✓ from libcoal_core import Transform3d
✗ from libcoal import Transform3d
Geometric types like Transform3d are available directly from libcoal_core.
This quickstart demonstrates how to create two simple collision geometries (spheres), define their poses using transforms, and perform a collision check using `libcoal_core.collide`. It shows both colliding and non-colliding scenarios.
import libcoal_core
# Create two spheres
sphere_radius = 1.0
s1 = libcoal_core.CollisionGeometry(libcoal_core.CollisionShape_Sphere(sphere_radius))
s2 = libcoal_core.CollisionGeometry(libcoal_core.CollisionShape_Sphere(sphere_radius))
# Define transforms (position and orientation) for the spheres
tf1 = libcoal_core.Transform3d()
# Move the second sphere to partially overlap with the first
tf2 = libcoal_core.Transform3d()
tf2.translation = libcoal_core.Vector3d([sphere_radius * 0.5, 0.0, 0.0]) # Overlap by 0.5 units
# Perform collision checking
req = libcoal_core.CollisionRequest()
res = libcoal_core.CollisionResult()
libcoal_core.collide(s1, tf1, s2, tf2, req, res)
print(f"Are spheres colliding? {res.is_collision}")
print(f"Number of contacts: {res.num_contacts}")
# Adjust position to not collide
tf2.translation = libcoal_core.Vector3d([sphere_radius * 2.5, 0.0, 0.0]) # Separated by 0.5 units
libcoal_core.collide(s1, tf1, s2, tf2, req, res)
print(f"Are spheres colliding (separated)? {res.is_collision}")
Debug
Known issues
gotchaThe PyPI package is named `libcoal`, but the primary module containing all collision detection functionalities and classes is `libcoal_core`. Attempting to `import libcoal` directly will likely result in an `AttributeError` or missing functionalities.fixAlways use `import libcoal_core` to access the library's features and refer to classes (e.g., `libcoal_core.CollisionGeometry`).
affects: All versions
gotchaLibcoal provides pre-built binary wheels for common platforms and Python versions. If a suitable wheel is not available for your specific OS/architecture (e.g., ARM, less common Linux distributions), `pip install libcoal` may fail or attempt to build from source, which requires CMake, a C++ compiler, and the FCL development libraries installed on your system.fixEnsure a compatible wheel exists for your environment. If not, refer to the GitHub repository for source build instructions and dependency requirements (e.g., FCL, Eigen, Boost).
affects: All versions
breakingMajor version upgrades (e.g., from 2.x to 3.x) of `libcoal` often correspond to significant updates to the underlying Flexible Collision Library (FCL). These FCL updates can introduce API changes or behavioral differences that might break existing code that directly interacts with FCL concepts exposed through `libcoal`.fixConsult the `libcoal` GitHub repository's release notes for specific changes, and if issues arise, review the FCL documentation for details on API changes relevant to the integrated FCL version.
affects: Major version upgrades (e.g., 2.x to 3.x)
Errors
Common errors & fixes
ImportError: No module named 'libcoal_core'
The `libcoal` package was not installed correctly, or the Python environment is not configured to find it. This can also happen if `pip` attempted a source build that failed silently due to missing C++ dependencies.
fixVerify installation by running `pip list | grep libcoal`. If missing, try `pip install libcoal`. For build failures, check `pip`'s verbose output (`pip install libcoal --verbose`) and ensure required C++ development libraries (FCL, CMake, a C++ compiler) are installed.
AttributeError: module 'libcoal' has no attribute 'CollisionGeometry'
Attempting to access library features through `import libcoal` instead of `import libcoal_core`.
fixChange `import libcoal` to `import libcoal_core` and update all subsequent references (e.g., `libcoal.CollisionGeometry` to `libcoal_core.CollisionGeometry`).
RuntimeError: FCL initialization failed: Could not load FCL library.
The underlying C++ FCL library could not be found or loaded by the Python bindings. This often indicates issues with dynamic linking, missing shared libraries on the system, or a corrupted `libcoal` installation.
fixEnsure that all required C++ shared libraries (FCL, Eigen, Boost, etc., if applicable and not bundled) are correctly installed and discoverable by your system's dynamic linker (e.g., in `LD_LIBRARY_PATH` on Linux). Reinstall `libcoal` to ensure bindings are correct: `pip uninstall libcoal && pip install libcoal`.
Upgrade
Version history
3.0.3latest on PyPI · released May 21, 2026
Audit
Dependencies
No dependency data recorded yet.
Resources
No resource links recorded.