# GEOS C++ Geometry Library: C, C++, and Python Integration

> GEOS is a C++ library for operations on two-dimensional vector geometries, with a stable C interface for dynamically linked applications. It suits geospatial software developers, but its unstable C++ ABI changes the adoption decision for C++ projects.

**libgeos/geos** — Geometry Engine, Open Source

- Repository: https://github.com/libgeos/geos
- Website: https://libgeos.org
- Stars: 1,519 · Forks: 438
- Language: C++
- License: LGPL-2.1
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/libgeos-geos

## GEOS Targets Two-Dimensional Vector Geometry Operations

GEOS solves the problem of implementing computational geometry operations in applications that work with points, lines, and polygons. It is intended primarily for C++ developers, but it also exposes a C interface and bindings in other languages. The library focuses on two-dimensional vector geometries rather than raster data, so it is relevant to spatial databases, desktop GIS software, analysis services, and language packages that need topology operations.

The README identifies GEOS as primarily a port of the JTS Topology Suite, a Java library. This relationship gives potential users a concrete model for the library's algorithmic domain, but the repository does not claim exact feature parity with every JTS release. GEOS provides algorithms used by PostGIS, Shapely, the R package sf, and other software. Those projects are relevant references because they demonstrate downstream use, not because the repository publishes compatibility guarantees for each of them.

GEOS is most useful when an application needs reusable geometry behavior without implementing its own computational geometry layer. It is the wrong kind of dependency for processing raster imagery, storing arbitrary application data, or presenting a complete GIS application. The repository describes a geometry library rather than a data management system or mapping package. Developers looking for those broader capabilities would need other components.

## GEOS Architecture Links C, C++, and Language Bindings

The repository presents two native interfaces with different compatibility contracts. The C library is the lower-level integration surface, and its implementation uses the C++ interface. The C++ interface exposes functionality that has not all been made available through C. In the repository structure, `include/` contains public headers, `src/` contains implementation code, `capi/` contains the C interface, and `examples/` contains usage examples for both interfaces.

Applications normally pass geometries into GEOS functions, request a geometry operation, and receive a result or an error status. The repository excerpts do not provide a complete function trace for a specific predicate or overlay operation, so a more detailed algorithm-level data flow cannot be confirmed here. The documented interface model is still clear: callers include the appropriate header, compile against the library, and invoke its API. Geometry objects and operation behavior are exposed through that API rather than through a command-line workflow.

Language bindings extend access beyond native clients. The README directs users to the project's bindings page, but it does not enumerate binding versions, supported language features, or compatibility rules in this repository excerpt. PostGIS, Shapely, and sf are identified as consumers of GEOS algorithms. That makes GEOS relevant to Python and R workflows, but a Python or R project should verify how its binding packages manage the native GEOS version rather than assuming that the C++ upgrade policy applies identically at every layer.

## Building GEOS and Linking the C API

The README sends native build users to `INSTALL.md`. It does not reproduce platform prerequisites or the complete build sequence there, so this tutorial should not substitute an invented package command for that file. Once GEOS is built and installed according to `INSTALL.md`, `geos-config` supplies the compiler and linker flags for the C library.

Add its compiler flags when configuring the build, then link the C library with `-lgeos_c`:

```bash
CFLAGS += `geos-config --cflags`
LDFLAGS += `geos-config --ldflags` -lgeos_c
```

These are Make-style shell variable assignments copied from the README. The backticks request command substitution, so the compiler and linker receive the flags reported by the installed `geos-config` program. A C application includes the public C API through `geos_c.h`. The repository also includes focused C examples such as `examples/capi_read.c`, `examples/capi_prepared.c`, `examples/capi_strtree.c`, and `examples/capi_indexed_predicate.c`.

The first practical step is therefore to build a matching example from the repository's `examples/` directory or use one of those files as the basis for an application. The README says that examples are available, but it does not print their compilation commands or source contents here. Readers should not invent a geometry operation merely to test installation. Confirm instead that compilation succeeds, `geos-config` resolves, and the executable starts with the C API.

## Choosing GEOS C++ Headers by Release Policy

The C++ interface offers a more natural API for C++ programs and includes additional functionality not exposed through C. Common functionality is available from `geos.h`:

```cpp
#include <geos.h>
```

Less common classes use individual headers. The README gives this exact example:

```cpp
#include <geos/algorithm/distance/DiscreteHausdorffDistance.h>
```

The build configuration is analogous to the C interface, except that the library name changes:

```bash
CFLAGS += `geos-config --cflags`
LDFLAGS += `geos-config --ldflags` -lgeos
```

This is the major GEOS adoption boundary. GEOS does not promise API or ABI stability for its C++ interface between releases, and breaking changes may not be announced in `NEWS`. The C++ library name also changes on every minor release. A project compiling and linking against a source or binary distribution can absorb some of this churn, but a C++ consumer that expects a stable deployment interface across minor versions is exposed to real upgrade work.

The README also says a compiler warning can be suppressed by defining `USE_UNSTABLE_GEOS_CPP_API`. That setting acknowledges the interface status; it does not make the interface stable. The repository examples include `examples/cpp_read.cpp` and `examples/cpp_strtree.cpp`, which are more appropriate starting points for a C++ integration than treating the C example as interchangeable.

## GEOS Release and C API Stability Boundaries

GEOS makes an unusually explicit distinction between its interfaces. Successive C API releases may add functions, but existing types and function signatures are not expected to be removed or changed. Programs linking only against the C library should therefore continue to work without relinking when GEOS is upgraded, subject to the normal ABI-sensitive versioning model described by the project.

That promise favors the C API for software dynamically linked to a system installation. It matters for packaging, plugins, command-line tools distributed through operating system repositories, and applications whose native dependency is managed outside the application's own build. Such software can isolate more of the GEOS upgrade surface than code compiled directly against C++ classes.

The repository is not archived, and its last push was on 2026-10-16. Release 3.15.0 was published on 2026-09-01 after `3.15.0rc1` and `3.15.0beta3`. These dates show recent repository activity, but they do not prove compatibility with any particular downstream package. The README also does not document a general rollback procedure. An adopter needing a rollback policy must determine it from `HOWTO_RELEASE`, packaging procedures, or the relevant release artifacts rather than assuming one exists.

## GEOS Versus JTS and Direct Algorithm Use

JTS is the closest architectural alternative identified by the project because GEOS is primarily a port of the JTS Topology Suite. The practical difference is deployment language: JTS is a Java library, while GEOS provides native C and C++ libraries that can be linked by native applications and reached through language bindings. A Java team already standardized on JTS would normally evaluate JTS directly, while a native application or a binding ecosystem centered on GEOS has a reason to use GEOS instead.

Another alternative is embedding a smaller geometry implementation directly in the application. That would avoid a native GEOS dependency, but the repository does not claim it is the wrong choice in every case. Direct implementation requires the application team to own algorithm correctness, error handling, memory behavior, headers, build integration, and future maintenance. GEOS centralizes those concerns in a library whose algorithms already serve projects including PostGIS, Shapely, and sf.

GEOS is the wrong choice when the application needs a stable C++ ABI across arbitrary minor releases, since the project explicitly withholds that stability promise. It is also unsuitable when the actual requirement is raster processing rather than two-dimensional vector geometry. For native binding work, the actual decision is between GEOS's C and C++ interfaces, and that decision has a direct operational consequence.

## GEOS Licensing, Build Cost, and Operational Surface

GEOS is distributed under `LGPL-2.1`, with license text stored in `COPYING`. Projects that redistribute GEOS or link it according to LGPL conditions must review those obligations for their own distribution model. This is a compliance consideration rather than a claim that every application has the same obligations, and the repository excerpt does not provide legal guidance.

The build has optional documentation work. Documentation is not included in the default build, but the README documents this CMake sequence:

```bash
cmake -DBUILD_DOCUMENTATION=YES
cmake --build . --target docs
```

The first command enables documentation generation, and the second invokes the `docs` target. Developer formatting uses the included Astyle wrapper, which accepts a source path:

```bash
tools/astyle.sh <yourfile.cpp>
```

Testing instructions are separated into `tests/README.md`, so build and test cost should be evaluated there rather than guessed from the top-level README. Upgrade cost depends heavily on the selected interface. C API users receive the stronger compatibility contract. C++ users face potentially unannounced source and ABI changes, a library name that changes every minor release, and individual class headers whose availability must be checked against the selected release.

## Conclusion

GEOS is a sound choice for C or C++ applications that need two-dimensional geometry operations, especially when future upgrades must preserve a dynamically linked binary interface. It is less suitable for a C++ codebase that cannot absorb breaking API and ABI changes between minor releases. Before adoption, inspect INSTALL.md for the supported build process, verify the required GEOS version against downstream bindings, and confirm whether the application can depend on the C API rather than the C++ interface.

## FAQ

### What is GEOS used for?

GEOS is a C++ library for operations on two-dimensional vector geometries. Its algorithms are also used by projects such as PostGIS, Shapely, and sf.

### Is the GEOS C++ API stable between releases?

No stability promise is made for the C++ API or ABI. Breaking changes may not be listed in `NEWS`, and the C++ library name changes on every minor release.

### Which GEOS API should a dynamically linked application use?

The README recommends the C API for software intended to link dynamically against a system installation. Existing C types and function signatures are expected to remain compatible, although ABI-sensitive versioning still applies.

## Sources

- [libgeos/geos on GitHub](https://github.com/libgeos/geos)
- [License: LGPL-2.1](https://github.com/libgeos/geos/blob/main/LICENSE)
- [Project website](https://libgeos.org)
- [README](https://github.com/libgeos/geos/blob/main/README.md)
- [Releases](https://github.com/libgeos/geos/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/libgeos-geos