docker-php-ext-install mbstring fails: oniguruma not found
configure: error: Package requirements (oniguruma) were not metShort 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.
Fix it fast
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 mbstring2Match what you see, then jump to its fix
- 1
The 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
The 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
The error appears in ./configure --enable-mbstring on a server, not in Docker.You compile PHP yourself and pkg-config cannot see OnigurumaFix
- 1
What does the error look like?
configure: error: Package requirements (oniguruma) were not metThe 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" Dockerfile2Fix
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 mbstring3Verify
Rebuild and list the modules.
docker build -t my-php .
docker run --rm my-php php -m | grep -i mbstringConfirmed by hub.docker.com
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 Dockerfile2Fix
Use apk instead of apt-get.
FROM php:8.3-fpm-alpine
RUN apk add --no-cache oniguruma-dev \
&& docker-php-ext-install mbstring3Verify
Rebuild and list the modules.
docker build -t my-php .
docker run --rm my-php php -m | grep -i mbstringConfirmed by pkgs.alpinelinux.org
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 missing2Fix
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-mbstring3Verify
configure passes the Oniguruma check and make completes.
php -m | grep -i mbstringConfirmed by php.net
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- Spotless LaundryAn on-demand laundry app: Flutter on a Laravel back end, with Firebase for live updates.
Related fixes
Servers
Apache returns 504 Gateway Timeout when PHP takes too long
Quick requests work, slow ones end in a 504 after a fixed wait
A 504 from Apache means the backend did not answer within the proxy timeout.
2 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
Composer reports a different PHP version than php -v on Ubuntu
You are running 8.1.2.
Composer takes its PHP version from the interpreter that runs it, unless config.platform fakes one.
3 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fix