Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker-php-ext-install mbstring fails: oniguruma not found

Errorconfigure: error: Package requirements (oniguruma) were not met

Short answer

mbstring needs the Oniguruma library to build its regex functions, and the PHP build finds it through pkg-config. The official php image does not ship the headers. Install libonig-dev on Debian images, or oniguruma-dev on Alpine, in the same RUN step before docker-php-ext-install mbstring.

  • Applies to php 8.3 Docker image, Debian 12 (bookworm), Alpine Linux
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the extension is already in the image before you build anything. If mbstring shows up, remove the install line.

    docker run --rm php:8.3-fpm php -m | grep -i mbstring
  2. 2Match what you see, then jump to its fix

    1. 1The build log ends with the oniguruma error in a Debian-based image (php:8.3-fpm or -cli).The Debian image has no libonig development packageFix
    2. 2The same error in an image whose tag ends in -alpine, and apt-get fails with command not found.An Alpine image needs the Alpine package nameFix
    3. 3The error appears in ./configure --enable-mbstring on a server, not in Docker.You compile PHP yourself and pkg-config cannot see OnigurumaFix

What does the error look like?

  • configure: error: Package requirements (oniguruma) were not met
  • The docker-php-ext-install step exits with a non-zero code

Cause 1 of 3

The Debian image has no libonig development package

1Check

PHP finds Oniguruma with pkg-config, and the extension needs the development files. The php image docs say you must install an extension's dependencies yourself.

grep -n "docker-php-ext-install" Dockerfile

2Fix

Install libonig-dev in the same RUN step as docker-php-ext-install.

FROM php:8.3-fpm
RUN apt-get update && apt-get install -y libonig-dev \
    && docker-php-ext-install mbstring

3Verify

Rebuild and list the modules.

docker build -t my-php .
docker run --rm my-php php -m | grep -i mbstring

Confirmed by hub.docker.com

Did this fix it?

Cause 2 of 3

An Alpine image needs the Alpine package name

1Check

Alpine uses apk, and the development package is named oniguruma-dev.

head -n 3 Dockerfile

2Fix

Use apk instead of apt-get.

FROM php:8.3-fpm-alpine
RUN apk add --no-cache oniguruma-dev \
    && docker-php-ext-install mbstring

3Verify

Rebuild and list the modules.

docker build -t my-php .
docker run --rm my-php php -m | grep -i mbstring

Confirmed by pkgs.alpinelinux.org

Did this fix it?

Cause 3 of 3

You compile PHP yourself and pkg-config cannot see Oniguruma

1Check

From PHP 7.4 the build uses pkg-config to detect libonig. Before 7.4 the library was bundled, which is why old tutorials do not mention it.

pkg-config --exists oniguruma && echo found || echo missing

2Fix

Install pkg-config and your system's Oniguruma development package, then run configure again. On Debian that package is libonig-dev.

sudo apt-get install -y pkg-config libonig-dev
./configure --enable-mbstring

3Verify

configure passes the Oniguruma check and make completes.

php -m | grep -i mbstring

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • Run php -m in the base image before adding extensions, so you only build what is missing.
  • Install the dev package and build the extension in one RUN step, then keep image layers small.
  • Pin the base image tag so a new Debian release does not change your build under you.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.