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
py 3.10
✕ build_error
✓ 9.15s
py 3.11
✕ build_error
✓ 8.78s
py 3.12
✕ build_error
✓ 7.85s
py 3.13
✕ build_error
✓ 8.05s
py 3.9
✕ build_error
1/4 runs
403MB installed
● package 403MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
coal
✓ import coal
✗ import hppfcl
The library was renamed from HPP-FCL to Coal in 2024; the old import path is deprecated.
Transform3s
✓ import coal
trans = coal.Transform3s()
Core types and functions are typically accessed directly from the `coal` module.
This quickstart demonstrates how to define geometric primitives (e.g., capsules), set their poses using `Transform3s`, create `CollisionObject` instances, and perform collision detection and distance computation using `coal.collide` and `coal.distance`.
import numpy as np
import coal
# Define geometries
radius = 0.1
length = 0.5
capsule1_geom = coal.Capsule(radius, length)
capsule2_geom = coal.Capsule(radius, length)
# Define poses (transformations)
# Capsule 1 at origin, identity orientation
capsule1_tf = coal.Transform3s.Identity()
# Capsule 2 shifted along X-axis
capsule2_tf = coal.Transform3s.Identity()
capsule2_tf.translation[:] = np.array([0.2, 0.0, 0.0])
# Create collision objects
obj1 = coal.CollisionObject(capsule1_geom, capsule1_tf)
obj2 = coal.CollisionObject(capsule2_geom, capsule2_tf)
# Perform collision check
req = coal.CollisionRequest()
res = coal.CollisionResult()
# Note: coal.collide returns a boolean indicating collision state
collision_occurred = coal.collide(obj1, obj2, req, res)
if collision_occurred:
print(f"Collision detected! Number of contacts: {len(res.contacts)}")
for contact in res.contacts:
print(f" Contact point: {contact.pos.transpose()}, Normal: {contact.normal.transpose()}")
else:
print("No collision detected.")
# Example for distance computation
req_dist = coal.DistanceRequest()
res_dist = coal.DistanceResult()
distance_found = coal.distance(obj1, obj2, req_dist, res_dist)
if distance_found:
print(f"Minimum distance: {res_dist.min_distance}")
print(f"Closest point on obj1: {res_dist.nearest_points[0].transpose()}")
print(f"Closest point on obj2: {res_dist.nearest_points[1].transpose()}")
Debug
Known issues
breakingThe project was renamed from HPP-FCL to Coal in 2024. Code using the old 'hppfcl' import or package name will break.fixUpdate imports from `import hppfcl` to `import coal`. Ensure you are installing the `coal` package.
affects: All versions prior to 3.0.0 (as HPP-FCL) when migrating to Coal.
gotchaDirect `pip install coal` might fail if pre-built wheels are not available for your specific Python version and operating system, often requiring manual compilation.fixEnsure you have a C++ compiler (e.g., MSVC on Windows, GCC/Clang on Linux/macOS) and CMake installed. Consider using `conda install -c conda-forge coal` for better dependency management if `pip` fails.
affects: All versions, particularly on less common platforms or with new Python releases.
gotchaCoal explicitly implements its own GJK and EPA algorithms and does not rely on `libccd`, a common component in other Flexible Collision Library (FCL) wrappers.fixBe aware that behavioral differences might exist compared to other FCL implementations or wrappers like `python-fcl`. Review Coal's documentation for specific algorithm details and expected performance characteristics.
affects: All versions.
Errors
Common errors & fixes
ERROR: Could not build wheels for coal which use PEP 517 and cannot be installed directly
This error occurs when `pip` cannot find a pre-built binary wheel for your system and attempts to build from source, but the necessary C++ compilers, CMake, or other build dependencies are missing or misconfigured. This is common for Python packages with underlying C++ code.
fixInstall a C++ compiler (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, Visual Studio with C++ development tools on Windows) and CMake. Alternatively, use `conda install -c conda-forge coal` if available, as conda often provides pre-compiled binaries with all dependencies.
ModuleNotFoundError: No module named 'coal'
The `coal` package was not successfully installed, or you are attempting to import it using an incorrect name. This can also happen if you previously installed the old `hpp-fcl` package.
fixEnsure the installation was successful (`pip install coal` or `conda install -c conda-forge coal`). If migrating from `hpp-fcl`, verify that the old package is uninstalled and `coal` is correctly installed, and update your import statements from `import hppfcl` to `import coal`.
Upgrade
Version history
3.0.3latest on PyPI · released May 21, 2026
Audit
Dependencies
numpyrequiredCommonly used for numerical operations and array handling with geometric data.
pinocchiooptionalA rigid body dynamics library that often uses and can install Coal as a dependency.
assimprequiredRequired for 3D model import; typically handled by binary wheels or conda.
boostrequiredC++ utility libraries; typically handled by binary wheels or conda.
eigenrequiredC++ template library for linear algebra; typically handled by binary wheels or conda.
octomaprequiredUsed for Octree-based collision objects; typically handled by binary wheels or conda.