The PCRE4J project's goal is to bring the power of the PCRE library to Java.

PCRE4J provides 100% coverage of the PCRE2 API, giving you access to every feature of the PCRE2 library from Java.

Why PCRE4J?

Java's built-in java.util.regex covers many use cases, but PCRE2 offers capabilities that go beyond what the standard library provides:

• Richer regex syntax — PCRE2 supports features absent from java.util.regex, including \K (match reset), recursive patterns, callouts, and the DFA matching algorithm.
• JIT compilation — PCRE2's JIT compiler translates patterns into native machine code, delivering significant speedups for pattern-heavy workloads.
• Built-in ReDoS protection — configurable match, depth, and heap limits let you cap resource usage per match, guarding against catastrophic backtracking on untrusted input.
• Cross-system consistency — when your regex behavior must match other PCRE-based systems (Nginx, PHP, R, grep -P, and many more), using the same engine eliminates subtle dialect differences.
• Drop-in java.util.regex API — the regex module mirrors Pattern and Matcher, so you can switch engines without rewriting application code.
• Full PCRE2 API access — 100% of the PCRE2 C API is exposed, so advanced users are never limited by the binding layer.

Feature Comparison

Quick Start

Add the dependency and start matching — the API mirrors java.util.regex:

import org.pcre4j.regex.Pattern;

var matcher = Pattern.compile("(?<year>\\d{4})-(?<month>\\d{2})").matcher("2026-02");
if (matcher.find()) {
    System.out.println(matcher.group("year"));  // "2026"
}

Maven (pom.xml):

<properties>
    <pcre4j.version>1.0.0</pcre4j.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.pcre4j</groupId>
        <artifactId>regex</artifactId>
        <version>${pcre4j.version}</version>
    </dependency>
    <dependency>
        <groupId>org.pcre4j</groupId>
        <!-- TODO: Select one of the following artifacts corresponding to the backend you want to use -->
        <artifactId>jna</artifactId>
        <!-- <artifactId>ffm</artifactId> -->
        <version>${pcre4j.version}</version>
    </dependency>
</dependencies>

Gradle (build.gradle.kts):

val pcre4jVersion = "1.0.0"

dependencies {
    implementation("org.pcre4j:regex:$pcre4jVersion")
    // TODO: Select one of the following artifacts corresponding to the backend you want to use
    implementation("org.pcre4j:jna:$pcre4jVersion")
    // implementation("org.pcre4j:ffm:$pcre4jVersion")
}

By default, the JIT compilation is used in cases the platform and the library support it. To override this behavior, you can set the pcre2.regex.jit system property with the value false to the JVM.

Prerequisites

• Java 21 or later
• PCRE2 native library — choose one of these approaches:

Option A: Native Library Bundles (no system install)

Add a platform-specific bundle to your dependencies and PCRE4J loads the library automatically:

Example (Gradle): implementation("org.pcre4j:pcre4j-native-linux-x86_64:1.0.0")

Option B: System-Installed PCRE2

Install the PCRE2 library on your system:

• Ubuntu/Debian: sudo apt install libpcre2-8-0
• macOS (Homebrew): brew install pcre2
• Windows: Download the PCRE2 DLL and add its location to PATH

The library is located automatically via pcre2-config, pkg-config, or well-known platform paths. You can also set the path explicitly with -Dpcre2.library.path=/path/to/lib.

Automatic library discovery can be disabled with -Dpcre2.library.discovery=false.

Module Architecture

PCRE4J is organized into layered modules published as separate Maven artifacts under org.pcre4j:

regex  ──→  lib  ──→  api  ←──  jna
                       ↑
                       └──────  ffm

Dependency Chain for Consumers

Each API tier requires a different set of artifacts. The regex and lib artifacts declare their upstream dependencies as transitive, so your dependency manager pulls them automatically:

A backend (jna or ffm) is always required at runtime but is intentionally not a transitive dependency of regex or lib, letting consumers choose which native access mechanism to use.

Library Initialization

The regex and lib convenience APIs use a global backend held by Pcre4j. The backend is initialized automatically — just add a backend artifact (jna or ffm) to your classpath and start using PCRE4J. No explicit setup call is required.

On first use, Pcre4j.api() discovers available backends via ServiceLoader. When both the FFM and JNA backends are present, the FFM backend is preferred for its better performance.

For explicit control, you can still call Pcre4j.setup() to install a specific backend:

import org.pcre4j.Pcre4j;
import org.pcre4j.jna.Pcre2;   // or org.pcre4j.ffm.Pcre2

static {
    Pcre4j.setup(new Pcre2());
}

setup() takes priority over auto-discovery and may be called again to replace the backend; existing compiled patterns are unaffected because each Pcre2Code instance captures the backend it was created with.

Every convenience constructor and factory method (e.g. Pcre2Code(String), Pattern.compile(String)) has an explicit-API overload that accepts an IPcre2 parameter directly, bypassing the global singleton entirely.

Multi-classloader note: Pcre4j stores the backend in a static field, so each classloader that loads PCRE4J gets its own independent singleton. In application servers or plugin frameworks, either place the PCRE4J JARs in a shared classloader, or use the explicit-API overloads to avoid relying on the global state.

Advanced Usage via PCRE4J API

Add lib and a backend to your dependencies:

Maven (pom.xml):

<dependencies>
    <dependency>
        <groupId>org.pcre4j</groupId>
        <artifactId>lib</artifactId>
        <version>1.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.pcre4j</groupId>
        <!-- TODO: Select one of the following artifacts corresponding to the backend you want to use -->
        <artifactId>jna</artifactId>
        <!-- <artifactId>ffm</artifactId> -->
        <version>1.0.0</version>
    </dependency>
</dependencies>

Gradle (build.gradle.kts):

dependencies {
    implementation("org.pcre4j:lib:1.0.0")
    // TODO: Select one of the following artifacts corresponding to the backend you want to use
    implementation("org.pcre4j:jna:1.0.0")
    // implementation("org.pcre4j:ffm:1.0.0")
}

import org.pcre4j.*;
import org.pcre4j.option.*;

import java.util.EnumSet;

public class Usage {
    public static String[] example(String pattern, String subject) {
        final Pcre2Code code;
        if (Pcre4jUtils.isJitSupported(Pcre4j.api())) {
            code = new Pcre2JitCode(
                    pattern,
                    EnumSet.noneOf(Pcre2CompileOption.class),
                    null,
                    null
            );
        } else {
            code = new Pcre2Code(
                    pattern,
                    EnumSet.noneOf(Pcre2CompileOption.class),
                    null
            );
        }
        final var matchData = new Pcre2MatchData(code);
        code.match(
                subject,
                0,
                EnumSet.noneOf(Pcre2MatchOption.class),
                matchData,
                null
        );
        return Pcre4jUtils.getMatchGroups(code, subject, matchData);
    }
}

Low-Level Usage

Add a backend artifact directly:

Maven (pom.xml):

<dependencies>
    <dependency>
        <groupId>org.pcre4j</groupId>
        <!-- TODO: Select one of the following artifacts corresponding to the backend you want to use -->
        <artifactId>jna</artifactId>
        <!-- <artifactId>ffm</artifactId> -->
        <version>1.0.0</version>
    </dependency>
</dependencies>

Gradle (build.gradle.kts):

dependencies {
    // TODO: Select one of the following artifacts corresponding to the backend you want to use
    implementation("org.pcre4j:jna:1.0.0")
    // implementation("org.pcre4j:ffm:1.0.0")
}

// TODO: Select one of the following imports for the backend you want to use:
import org.pcre4j.jna.Pcre2;
// import org.pcre4j.ffm.Pcre2;

public class Usage {
    public static void example() {
        final var pcre2 = new Pcre2();

        final var errorcode = new int[1];
        final var erroroffset = new long[1];
        final var code = pcre2.compile("pattern", 0, errorcode, erroroffset, 0);
        if (code == 0) {
            throw new RuntimeException(
                    "PCRE2 compilation failed with error code " + errorcode[0] + " at offset " + erroroffset[0]
            );
        }

        pcre2.codeFree(code);
    }
}

See the complete list of exposed PCRE2 API functions here.

java.util.regex API Compatibility

The regex module provides a complete implementation of the java.util.regex API backed by PCRE2. All Pattern and Matcher methods are supported.

Pattern Flags

Security: ReDoS Protection

Regular Expression Denial of Service (ReDoS) occurs when a crafted input causes catastrophic backtracking in a regex engine, leading to excessive CPU usage. PCRE4J provides several layers of protection against ReDoS attacks.

For reporting security vulnerabilities, please see the Security Policy.

JIT Compilation (Enabled by Default)

The regex module enables PCRE2 JIT compilation by default when the platform supports it. JIT-compiled patterns use a fixed-size machine stack, which can mitigate some forms of catastrophic backtracking and runaway recursion, but explicit match limits (see below) should still be used for stronger guarantees on CPU and memory usage.

To disable JIT: -Dpcre2.regex.jit=false

Match Limits

PCRE2 provides configurable limits that terminate match operations exceeding resource thresholds. The regex module exposes these via system properties:

When a limit is exceeded, a MatchLimitException is thrown (a RuntimeException subclass) with the specific PCRE2 error code indicating which limit was hit.

Example: Tightening limits for untrusted input:

java -Dpcre2.regex.match.limit=1000000 -Dpcre2.regex.depth.limit=100 -jar myapp.jar

Note: The PCRE2 library's compiled-in defaults already provide baseline protection. The system properties allow applications to tighten these limits further for security-sensitive use cases. When not set, the library defaults are used.

Low-Level API

For fine-grained control, the lib module provides Pcre2MatchContext with setMatchLimit(), setDepthLimit(), and setHeapLimit() methods that can be applied on a per-match basis.

Backends

The PCRE4J library supports several backends to invoke the pcre2 API.

jna

The jna backend uses the Java Native Access library to invoke the pcre2 shared library. For this backend to work, the pcre2 shared library must be installed on the system. The library is located via jna.library.path, or automatically discovered using pcre2-config, pkg-config, or well-known platform paths as a fallback.

ffm

The ffm backend uses the Foreign Functions and Memory API to invoke the pcre2 shared library. For this backend to work, the pcre2 shared library must be installed on the system. The library is located via java.library.path, or automatically discovered using pcre2-config, pkg-config, or well-known platform paths as a fallback.

The ffm module is packaged as a Multi-Release JAR supporting both:

• Java 21: Requires --enable-preview flag (FFM was a preview feature)
• Java 22+: No special flags required (FFM is finalized)

Note: The ffm backend is incompatible with OpenJ9-based JVMs (including IBM Semeru) on Java 21 due to a JVM bug in the preview FFM implementation that causes memory corruption assertions. OpenJ9 Java 22+, where FFM is finalized, works correctly. Use the jna backend on OpenJ9 Java 21.

GraalVM Native Image

PCRE4J supports GraalVM native-image compilation using the FFM backend. All modules ship with GraalVM reachability metadata, so no additional configuration is required.

Requirements:

• GraalVM JDK 25 or later (for finalized FFM and reachability-metadata.json foreign section support)
• FFM backend (ffm artifact) — the JNA backend is not supported for native-image
• PCRE2 native library must be available at runtime (via system install or library path)

What's New in 1.0.0

The 1.0.0 release marks PCRE4J's first stable API with a comprehensive set of new features:

• Platform-specific native library bundles — add a dependency, skip the system install
• GraalVM native-image support — compile PCRE4J applications to native executables
• ServiceLoader-based backend discovery — zero-configuration setup
• Callout support in the high-level API
• DFA matching through the high-level API
• Pattern serialization — serialize compiled patterns to bytes and back
• Glob and POSIX pattern conversion through the high-level API
• Scoped backend API for multi-backend support (Pcre4j.withBackend())
• Unified exception hierarchy with specific exception types
• JPMS module descriptors across all modules

See the Changelog for the full list of changes.

Roadmap

See the Roadmap for planned features and project direction.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

All commits must be signed off to certify the Developer Certificate of Origin (DCO). Use git commit -s to add the required Signed-off-by line.

This project is brought to you by Alexey Pelykh with a great gratitude to the PCRE library author Philip Hazel and its contributors.

The source code is hosted on GitHub.

Javadoc

Please see the Javadoc Index for the detailed API documentation.