Install & Compatibility
Where this runs
tested against v2.4.4 · 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.8s
py 3.11
✕ build_error
✓ 7.6s
py 3.12
✕ build_error
✓ 8.75s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 10.35s
388MB installed
● package 388MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
hppfcl
✓ import hppfcl
✗ import hpp-fcl
The Python package is `hpp-fcl` but the importable module name is `hppfcl` (without the hyphen).
Transform3f
✓ from hppfcl import Transform3f
✗ from hppfcl import Transform
The primary transformation class is `Transform3f`, not `Transform`, which existed in older FCL versions.
This quickstart demonstrates how to create two simple sphere objects, position them using `Transform3f`, and then perform both collision and distance checks using the `hppfcl.collide` and `hppfcl.distance` functions.
import hppfcl
from hppfcl import CollisionRequest, CollisionResult, DistanceRequest, DistanceResult
# Create two spheres
s1 = hppfcl.Sphere(1.0)
s2 = hppfcl.Sphere(1.0)
# Create an identity transform for s1
tf1 = hppfcl.Transform3f()
# Create a transform for s2 (translated by 2.0 along X-axis)
tf2 = hppfcl.Transform3f()
tf2.setTranslation(hppfcl.Vector3(2.0, 0.0, 0.0))
# Perform collision check
req = CollisionRequest()
res = CollisionResult()
ret = hppfcl.collide(s1, tf1, s2, tf2, req, res)
print(f"Collision result: {res.isCollision()}")
# Perform distance check
dreq = DistanceRequest()
dres = DistanceResult()
ret = hppfcl.distance(s1, tf1, s2, tf2, dreq, dres)
print(f"Minimum distance: {dres.min_distance}")
Debug
Known issues
breakingMajor API changes occurred between hpp-fcl 2.x and 3.x, corresponding to underlying FCL library updates from v0.6 to v0.7/v0.8. This affects geometry constructors, transformation classes (e.g., `Transform3f` methods), and collision/distance function signatures.fixReview the official FCL v0.7/v0.8 documentation for API changes. Update code to use `Transform3f.setTranslation()`, `hppfcl.Vector3` for vectors, and verify `collide`/`distance` function arguments.
affects: hpp-fcl < 3.0.0
gotchaThe Python package name is `hpp-fcl` (with a hyphen), but the module you import into Python code is `hppfcl` (without a hyphen).fixAlways use `import hppfcl` in your Python code, not `import hpp-fcl`.
affects: All versions
gotchaWhile `pip install hpp-fcl` typically installs pre-compiled wheels, certain environments or source builds might encounter issues due to missing C++ compiler tools (e.g., g++, cmake) or underlying FCL library dependencies.fixEnsure that development tools like `cmake`, `g++`, and potentially `boost` development libraries are installed on your system before attempting a source build.
affects: All versions (when building from source or on unsupported platforms)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'hpp-fcl'
Attempting to import the module using the package name with a hyphen.
fixChange your import statement from `import hpp-fcl` to `import hppfcl`.
AttributeError: module 'hppfcl' has no attribute 'Transform'
Trying to use an older FCL API transformation class, or a misremembered name.
fixThe correct class for transformations is `hppfcl.Transform3f` in current versions. Update your code to use `Transform3f`.
ImportError: libfcl.so.0.7: cannot open shared object file: No such file or directory
The Python binding was likely built from source or in an environment where the underlying C++ FCL library is not correctly found by the linker at runtime.
fixEnsure the directory containing `libfcl.so` (or `fcl.dll` on Windows) is in your system's `LD_LIBRARY_PATH` (Linux/macOS) or `PATH` (Windows), or reinstall `hpp-fcl` using a pre-compiled wheel if available for your platform and Python version.
Upgrade
Version history
2.4.4latest on PyPI · released Mar 6, 2024
Audit
Dependencies
No dependency data recorded yet.