GemPy builds 3D geological models from interface and orientation data, implicitly

The core idea is that geology is interpolated, not drawn

GemPy is a Python-based open-source geomodeling library capable of constructing complex 3D geological models of folded structures, fault networks and unconformities, based on the underlying implicit representation approach.

An implicit representation is the reason the library is called a gemodelling tool rather than a mesh generator. The geological surfaces are not defined as explicit triangulated boundaries that you sculpt. They are defined as scalar fields, where each point in space has a value, and a contact surface is the locus where that value crosses a threshold. Interpolation happens on the fields, and the geometry emerges.

The consequence is the one the project description highlights, the implicit or automatic creation of complex geological models from interface and orientation data. A geologist typically has a handful of measurements: the depth of a contact at a borehole, the dip and azimuth of a bedding surface from a field station, the position of a fault from a map. Filling in everything between those sparse constraints is the actual work of geological modelling, and the implicit approach is what turns those constraints into a continuous 3D model without the modeller manually drawing a surface.

This also explains why the gallery is organised around geometries rather than workflows. The example set runs through horizontal stratigraphic, fold, recumbent fold, pinchout, fault, unconformity and combination, and each links to a runnable example in the documentation. Those seven cases are the vocabulary of structural geology, and seeing the model produced for each of them is a faster way to judge the library than reading about implicit methods.

Uncertainty is a first-class feature, not an afterthought

Alongside the implicit modelling, GemPy offers support for stochastic modelling to address parameter and model uncertainties. The repository topics list it in both forms, bayesian and uq, and there is a dedicated advanced tutorial on kriging in the documentation, which points to a probabilistic treatment of the spatial variability rather than a simple interpolation.

This is the feature that distinguishes a research library from a demonstration script, and it is worth thinking about what it changes about how you use the tool. A deterministic model gives you one answer, and the risk is that its authority is mistaken for its accuracy. A stochastic workflow lets you run the same input data many times under different parameter draws, using Monte Carlo simulation as the topic list indicates, and look at the spread of results. Where the spread is narrow, the data constrains the model. Where it is wide, you know which parts of your interpretation are guesses.

That difference changes the conversation between a modeller and the people who use the model, whether they are looking for a prospect location or a risk assessment. It also changes the computational cost, and the repository's topic list including torch is a hint about the machinery involved, since PyTorch support is listed among the changes in the 2026.0.3 release.

Installation is one pip command, and the extras matter

The project publishes to PyPI and the README recommends using it, with the install command given as:

pip install gempy[base]

The base extra is not decorative. The setup.py reads three separate requirement files: requirements.txt for the main install_requires, base-requirements.txt for the base extra, and optional-requirements.txt for an extra called opt. The requirement reader handles the -r directive and follows referenced files recursively, so the dependency set is composed from a few files rather than one long list.

The PyPI badge lists Python 3.10, 3.11 and 3.12, so the supported interpreter range is narrow and recent.

After installation, the README points to two starting points: the notebook tutorials in the documentation, and a video introduction on YouTube. The documentation site at docs.gempy.org holds the tutorials and examples, and the documentation status badge is a passing-flat badge, which means the docs build is part of the project's checks.

For questions and support there are GitHub discussions, and bugs and feature requests go to the issue tracker, with a separate CONTRIBUTING file for the contribution process and a DevelopersGuide.md at the root.

Version 3 is a rewrite, and v2 has been moved aside

The version structure is the thing to understand before you pick a starting point, because the project is mid-transition and the two lines behave differently.

GemPy 2026.0.3, dated June 2026, is the latest stable release of GemPy v3, and it brings together matching releases of gempy, gempy_engine and gempy_viewer. The changes listed are across model setup, serialization, octree handling, PyTorch support, visualization and example models. The splitting into three packages is worth noting: an engine package separate from the main one suggests the computation core can be used on its own, and the viewer package holds the visualisation side.

GemPy v2 remains available as gempy_legacy in its own repository for users who still depend on previous workflows. The README states that the core team is not developing new features for that version, but that maintenance can continue based on community needs. That is a clear signal about where to start and where not to.

The current release train is the 2026 line, and it is in alpha. The recent releases are v2026.2.0a1 on 2026-10-14, v2026.2.0a0 on 2026-10-13, and v2026.1.0a3 from July 2026. The last push was on 2026-10-14. The versioning scheme also changes how releases are named, since they are dated versions rather than semver, which is a reasonable choice for a research library that pins a specific environment for a paper or a project.

The WhatsNewGemPy3.md file at the repository root holds the background on the v3 transition, and there is a CITATION.cff and a Zenodo DOI badge, which tells you the project is set up for archiving and citation.

The repository is a library with a large example corpus

The top level of the repository reads like a scientific Python project with a substantial documentation effort attached. It holds the gempy/ package, docs/, examples/, requirements/, scripts/, test/, a setup.py and setup.cfg, a MANIFEST.in, an AUTHORS.rst, a CITATION.cff, a CODE_OF_CONDUCT.md, a CONTRIBUTING.md and a DevelopersGuide.md. There is a .teamcity/ directory, a .travis.yml and a .env.example.

The examples directory is organised into four parts: data, examples, integrations and tutorials, and each of the documentation's example pages is a runnable script. The integrations folder is the interesting one for an engineer, because it shows how GemPy is meant to sit next to other tools in a subsurface workflow rather than as an island.

The documentation itself is the primary interface for this library, and the structure reflects how a modeller thinks. The tutorials are grouped into fundamentals, where 2D visualisation, 3D visualisation and cross-section extraction are covered, and advanced, where kriging and topology appear. The examples are grouped into geometries, real and otherwise, and the real examples are the case studies, which include a named model, Alesmodel.

Two files at the root describe the project for contributors specifically: DevelopersGuide.md for the development side and WhatsNewGemPy3.md for users migrating from v2. The .env.example is worth a glance if you plan to use the integrations, since it holds a LIQUID_EARTH_API_TOKEN and a BOREHOLES_SOUTH_FOLDER path.

Where GemPy is the wrong tool

The first case is a team that wants a graphical interpretation environment. GemPy is a library, and the documentation is built around notebooks and scripts. A modeller who works by drawing cross sections, snapping horizons to wells and iterating visually will be faster in a desktop interpreter, and the interactive part of GemPy is the notebook and the viewer package rather than a full interpretation desktop.

The second is the maturity question. The current line is in alpha, with two alpha releases of the same 2026.2 version in consecutive days, and the stable release is 2026.0.3 from June 2026. A library with a stable release and an alpha line is fine to build on, but you should pick deliberately: the alpha line has the newest API and the least settled one, and the stable line is behind. The v2 to v3 transition already cost some users a migration, with a separate legacy repository kept alive for them.

The third is the licence, and it is genuinely unusual. GemPy is licensed under EUPL-1.2, the European Union Public Licence, which is a copyleft licence aligned with the GPL family in intent but not identical in text, and it applies to network use in a way that surprises people who expect a permissive research licence. The setup.py records license='EUPL-1.2' and the LICENSE file is in the repository. Anyone integrating GemPy into a commercial or closed product needs to read that text rather than assume MIT-like terms, and the project is a good example of a research library that is free to use but not free of obligations.

Editorial conclusion

GemPy fits a structural geologist or subsurface modeller who wants to build and iterate on a 3D geological model in Python, especially one who needs stochastic runs to understand model uncertainty, and it does not fit a team that needs a desktop interpretation workflow or a vendor-supported product. Before adopting it, check which version you are on, because the v3 line is the actively developed one and v2 lives in a separate gempy_legacy repository where the core team is not developing new features, and expect the alpha cadence of the current 2026.2 line to mean the API is still moving.

Frequently asked questions

Official sources

1. gempy-project/gempy on GitHub
2. License: EUPL-1.2
3. Project website
4. README
5. Releases