---
id: python-fcl
version: "0.7.0.11"
license: BSD
license_treatment: permissive
maintenance: active
---

# python-fcl — Python bindings for the Flexible Collision Library

License: permissive · Maintenance: active · Downloads: 220.1K/mo

## What it is and what it does

Python-FCL is an unofficial Python interface to the Flexible Collision Library, a C++ library for geometric proximity queries. It wraps FCL's core algorithms to let you detect collisions between 3D shapes, compute minimum distances between objects, and check for collisions during motion. The package supports geometric primitives (boxes, spheres, cylinders, cones, capsules, ellipsoids, half-spaces, planes) and arbitrary triangle meshes via BVHModel or Convex wrappers, plus OcTree structures for spatial hierarchies.

You work with CollisionObject instances (a geometry plus a pose), set up request/response structures, and call query functions like collide(), distance(), or continuousCollide(). The library is commonly used in robotics, physics simulation, and motion planning where you need fast, accurate proximity checks. Installation requires pre-built system libraries (libfcl-dev and liboctomap-dev on Linux) or manual FCL compilation; wheels are provided for recent Python versions on major platforms.

Use it for:

- Robotics motion planning: check for collisions between robot links and obstacles during path planning
- Physics simulation: compute contact points and distances for rigid body dynamics engines
- Continuous collision detection: detect whether moving objects collide during a time interval
- Mesh-based proximity queries: compute minimum distance between complex triangle meshes
- Spatial reasoning in autonomous systems: query geometric relationships for navigation and manipulation

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Python bindings for the Flexible Collision Library (FCL) that perform collision detection, distance computation, and continuous collision detection queries on pairs of geometric models.

Yes, if you need collision detection and distance queries in Python and can satisfy the system library prerequisites. The library is actively maintained, supports current Python versions (3.9+), carries no known vulnerabilities, and has a permissive BSD license. The main friction is the upfront system dependency installation; once that is done, the wheels install cleanly. Suitable for robotics, simulation, and computational geometry projects.

## Install

pip install python-fcl
uv add python-fcl
poetry add python-fcl

## Installing python-fcl

Before you install: Medium install friction due to compiled C++ bindings; requires pre-installed system libraries (libfcl-dev and liboctomap-dev on Ubuntu, or manual FCL compilation). Wheels are available for Python 3.10–3.13 on macOS, Linux, and Windows. Active maintenance with recent release (128 days ago).

License in practice: BSD permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart:

pip install python-fcl

import fcl
import numpy as np

g1 = fcl.Box(1, 2, 3)
t1 = fcl.Transform()
o1 = fcl.CollisionObject(g1, t1)

g2 = fcl.Sphere(1.0)
t2 = fcl.Transform(np.array([2.0, 0.0, 0.0]))
o2 = fcl.CollisionObject(g2, t2)

request = fcl.CollisionRequest()
result = fcl.CollisionResult()
ret = fcl.collide(o1, o2, request, result)

Requires libfcl-dev and liboctomap-dev system libraries installed before pip install; on Ubuntu use `sudo apt-get install libfcl-dev liboctomap-dev`, or compile FCL from source on other systems.

Verify before relying:

- Whether OcTree support requires additional runtime configuration beyond liboctomap-dev installation
- Performance characteristics for large-scale mesh collision queries or high-frequency distance checks
- Stability of the Alpha status (Development Status :: 3) and whether breaking changes are expected

## Package facts

- License: BSD (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 220.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

collision detection library, distance computation geometry, continuous collision detection, fcl python bindings, proximity queries 3d, geometric collision checking, rigid body collision, collision-detection, computational-geometry, robotics

[View on SkillFed](https://skillfed.io/packages/python-fcl) · [View on PyPI](https://pypi.org/project/python-fcl/)