Install & Compatibility
Where this runs
tested against v0.7.0.11 · 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
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.8s · import 0.268s · 126MB
129MB installed
● package 129MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fcl
✓ import fcl
The main module is 'fcl', not 'python_fcl' or 'pyfcl'.
Basic collision check between two identical boxes.
import fcl
import numpy as np
# Create box geometry
box = fcl.Box(1, 1, 1)
obj = fcl.CollisionObject(box, fcl.Transform())
# Create collision request/result
req = fcl.CollisionRequest()
res = fcl.CollisionResult()
# Self-collision check (not useful, but simple)
ret = fcl.collide(obj, obj, req, res)
print(f"Collision? {res.is_collision}")
Debug
Known issues
breakingVersion 0.7.0.x changed the return type of fcl.collide and fcl.distance from bool to int (return code). Old code checking if ret == True will break.fixCheck ret == 1 for collision detected, or use res.is_collision / res.is_distance_valid.
affects: >=0.7.0.0 <0.7.0.11
gotchaPython-fcl uses row-major order for matrices (numpy default), while FCL C++ uses column-major internally. Incorrect transposition can lead to wrong transforms.fixAlways use numpy arrays in row-major format; do not transpose unless explicitly documented.
affects: all
gotchaCollisionObject instances must outlive the collision query; they are not copied. Deleting or reusing the same object in parallel can cause segfaults.fixKeep a reference to all CollisionObjects until after all queries are done.
affects: all
Errors
Common errors & fixes
ImportError: No module named fcl
Package not installed or installed under different name.
fixRun 'pip install python-fcl' (note: import name is 'fcl').
AttributeError: module 'fcl' has no attribute 'CollisionObject'
Very old version (pre-0.6) or copy with renaming.
fixUpgrade: pip install --upgrade python-fcl. Or check if API changed: use 'import fcl; print(dir(fcl))'.
Upgrade
Version history
0.7.0.11latest on PyPI · released Apr 8, 2026
Audit
Dependencies
numpyrequiredRequired for geometry data structures (vectors, transforms).
fclrequiredC++ FCL library; python-fcl is a binding, but often pre-built wheels bundle it.