---
id: libcoal
version: "3.0.3"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# libcoal — An extension of the Flexible Collision Library

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

## What it is and what it does

libcoal is a Python interface to a modern collision detection and distance computation library that evolved from the Flexible Collision Library (FCL). It provides efficient implementations of the GJK and EPA algorithms for narrow-phase collision detection, along with support for safety margins, contact point computation, and a variety of geometric primitives (boxes, spheres, capsules, ellipsoids, convex meshes, height fields, octrees). The library is designed for robotics and physics simulation where fast, reliable collision checking is critical.

The package wraps a C++ core with compiled dependencies on cmeel-boost, cmeel-assimp, cmeel-octomap, and cmeel-qhull, making installation straightforward on supported platforms (macOS and Linux) but requiring binary wheels. It is actively maintained and used in production robotics frameworks for motion planning and dynamics simulation.

Use it for:

- Motion planning for robotic systems: check collisions between links and obstacles during trajectory generation.
- Physics simulation: detect contacts and compute distances between rigid bodies in a dynamics engine.
- Mesh collision queries: load convex hulls from OBJ/STL/DAE files and perform fast collision detection with other objects.
- Safety margin enforcement: maintain minimum distance constraints between objects in real-time control loops.
- Contact analysis: compute contact points and patches between colliding geometries for force feedback or constraint solving.

## Worth the install?

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

libcoal provides Python bindings for collision detection and distance computation between 3D geometric objects using optimized GJK and EPA algorithms.

Yes, if you need collision detection in a robotics or physics simulation context on macOS or Linux. The library is actively maintained, permissively licensed (BSD-3-Clause), and offers state-of-the-art performance via optimized GJK algorithms. Install friction is moderate due to compiled dependencies, but binary wheels are available for common platforms. No known vulnerabilities.

## Install

pip install libcoal
uv add libcoal
poetry add libcoal

## Installing libcoal

Before you install: Medium install friction due to compiled dependencies (cmeel-assimp, cmeel-boost, cmeel-octomap, cmeel-qhull). Actively maintained with recent releases; last commit 2026-08-01. Requires Python >=3.9.

License in practice: BSD-3-Clause (permissive) allows commercial use, modification, and distribution with minimal restrictions—suitable for most projects.

Quickstart:

pip install libcoal

import libcoal

# Create shapes and check collision
shape1 = libcoal.Ellipsoid(0.7, 1.0, 0.8)
shape2 = libcoal.Sphere(0.5)
request = libcoal.CollisionRequest()
result = libcoal.CollisionResult()
libcoal.collide(shape1, libcoal.Transform3s.Identity(), shape2, libcoal.Transform3s.Identity(), request, result)

Requires compiled C++ libraries; binary wheels available for macOS (x86_64, arm64) and Linux (x86_64, aarch64) only.

Verify before relying:

- Whether Python bindings expose the full feature set (contact patches, serialization, broad phase) described in the C++ documentation.
- Performance characteristics of the Python bindings relative to direct C++ usage.
- Availability of comprehensive Python API documentation beyond the excerpt provided.

## Package facts

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

## Tags

collision detection library, 3d geometry distance computation, gjk algorithm python, rigid body collision checking, convex hull collision detection, contact point computation, bounding volume hierarchy, collision-detection, robotics, geometry

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