Fixing the libz.so.1 Docker-Compose Error on RHEL 9: A Deep Dive

“docker-compose: error while loading shared libraries: libz.so.1: failed to map segment from shared object”

If you’ve hit this error trying to run Docker Compose on RHEL 9 — welcome to one of the lesser-known yet frustrating runtime issues that can halt container orchestration in its tracks.

In this guide, we’ll walk through what this error means, why it occurs on modern systems like RHEL 9, and how to fix it using Docker’s supported Compose plugin. We’ll also include real-world CLI outputs, insights for other Linux distributions, and a clean migration path.

Context: When It All Broke

While deploying a microservices stack on RHEL 9.6, running this simple command:

docker-compose ps

We were hit with:

docker-compose: error while loading shared libraries: libz.so.1: failed to map segment from shared object

Understanding the Error

This is a dynamic linking error — not related to your containers, volumes, or Docker itself. The error occurs before containers are evaluated, and originates from the Linux dynamic linker trying to map libz.so.1 (from the zlib library) into memory.

Root Cause: Broken Legacy Compose + Host Mismatch

1. Legacy docker-compose is Dynamically Linked

Older Docker Compose binaries (v1.x) are Python applications bundled with PyInstaller, and dynamically link to libraries such as:

• libz.so.1
• libc
• other shared libraries on the host OS

This becomes a problem when:

• The binary is old
• The OS is newer (e.g., RHEL 9+, Debian 12, Fedora 39+)
• Or the binary was copied from another architecture

…because the linked libraries may no longer be compatible.

2. libz.so.1 Exists — But Cannot Be Mapped

Check this:

[root@host ~]# ls -l /usr/lib64/libz.so.1
lrwxrwxrwx. 1 root root 13 Jul 2 12:35 /usr/lib64/libz.so.1 -> libz.so.1.2.11

But then:

[root@host ~]# ls -Z /usr/lib64/libz.so.1
? /usr/lib64/libz.so.1

The ? symbol indicates the SELinux context is unreadable. Potential causes include:

• Corrupt inode
• Read-only or noexec mount
• Missing extended attributes support
• SELinux disabled (as in our case):

[root@host ~]# sestatus
SELinux status: disabled

So even though the library exists, the binary cannot map it into memory due to low-level permission/context issues.

What Didn’t Work (and Why)

Reinstalling zlib

dnf reinstall zlib

This reinstalled cleanly, but didn’t fix the issue. Why? Because it’s not a problem with the zlib files — it’s with how the old docker-compose binary is built.

Restoring SELinux Labels

restorecon -v /usr/lib64/libz.so.1

Also had no effect, because SELinux was disabled. So label restoration was moot.

The Real Fix: Use Docker Compose Plugin (v2)

Starting with Docker 20.10+, Docker includes a plugin-based Compose v2, invoked as:

docker compose

Benefits:

• Statically compiled
• Integrated with Docker CLI
• Free of shared library dependency issues

To keep your habits intact, you can alias it:

alias docker-compose='docker compose'

And voilà:

docker-compose ps

No more crash! (You might see harmless env var warnings, which are unrelated.)

Verifying the Plugin

docker-compose version

Sample output:

Docker Compose version v2.32.4

This confirms that you are using the modern, stable plugin version.

Optional Cleanup

You can remove the old legacy binary:

rm -f /usr/local/bin/docker-compose

And persist the alias:

echo "alias docker-compose='docker compose'" >> ~/.bashrc
source ~/.bashrc

What If You See This on Ubuntu, Debian, Arch, or Alpine?

This issue isn’t specific to RHEL.

You might also encounter it on:

• Ubuntu/Debian — if libz.so.1 is missing or incompatible
• Alpine Linux — if you run a glibc-linked binary in a musl-only environment
• Arch/Fedora — due to rolling library versions mismatching
• Containers — where libz.so.1 doesn’t exist in minimal base images

Universal Troubleshooting Checklist

Check if the library exists:

ls -l /usr/lib*/libz.so.1

Reinstall zlib:

• Ubuntu/Debian:

sudo apt install --reinstall zlib1g

• Fedora/RHEL:

sudo dnf reinstall zlib

Check SELinux or AppArmor:

dmesg | grep denied
ls -Z /usr/lib64/libz.so.1

Check mount options:

mount | grep /usr

Check binary architecture:

file $(which docker-compose)
ldd $(which docker-compose)

TL;DR

| Problem                           | Fix                                      |
| --------------------------------- | ---------------------------------------- |
| `libz.so.1 failed to map segment` | Use `docker compose` plugin              |
| `ls -Z` shows `?` on libz file    | Harmless if SELinux is disabled          |
| Reinstalling zlib didn’t help     | Binary mismatch, not a library issue     |
| Other distros show similar errors | Use statically linked or native binaries |

Conclusion

This wasn’t just a case of a missing file. It was a clash between legacy tools and modern OS behavior.

While it may seem tempting to deep-dive into SELinux labels or library rebuilds — in 2025, the right approach is simple:

Use tools that are built for modern systems.

Bonus: Why Docker Compose v2 Just Works

Docker Compose v2 is:

• Lightweight
• Self-contained
• Reliable across distros and kernel versions

If you’re already on Docker 20.10+, you already have it.

Just switch your CLI habits from docker-compose ➝ docker compose and move forward confidently.