You change one line in your Dockerfile — swap FROM python:3.11-slim for FROM dhi.io/python:3.11-debian12 — kick off the build, and watch it fall over. apt-get: command not found. Fix that, rebuild, and now it's Permission denied writing to a log directory. Fix that too, and your container won't bind to port 80 anymore. None of this is broken tooling. It's Docker Hardened Images (DHI) doing exactly what they're designed to do, and the official migration guide assumes you already know why before you start.
I ran this migration for a Flask claims-validation service recently, and most of the pain came from treating it like a base image bump instead of an architecture change. Here's what actually happens under the hood, why your existing Dockerfile breaks, and how to fix it without rewriting your whole build pipeline.
What is a Docker Hardened Image, and why does it break your existing Dockerfile?
DHI ships as Alpine-based and Debian-based variants, pulled from a separate registry (dhi.io) rather than Docker Hub directly. You authenticate with the same Docker ID you already use, run docker login dhi.io, and pull images the same way you always have.
The part that actually changes your build: DHI's runtime images are minimal, or "distroless". They ship the application binary, its runtime dependencies, and nothing else — no shell, no package manager, no curl, ps, or cat. Docker's own published comparison for the Python image shows the hardened variant dropping from roughly 412 MB down to about 35 MB, cutting installed packages from around 610 to 80, and removing a high-severity CVE along with most of the medium and low-severity ones present in the standard image. Your numbers will differ depending on the image and date you pull, but the direction is consistent: drastically less surface area for an attacker to work with.
That's also exactly why a naive FROM swap doesn't work. Every apt-get install, every RUN sh -c, every assumption that the container runs as root — all of it depends on tooling that simply isn't in the runtime image anymore.
What problem is this migration actually solving?
If you're doing this voluntarily, it's usually one of two things: a customer security questionnaire that now asks for SBOMs and signed provenance on every image you ship, or an internal mandate to cut CVE noise out of vulnerability scans before it eats another sprint. DHI addresses both directly — every image ships with SBOMs and attestations baked in, and for regulated environments there are FIPS and STIG-compliant variants available through a DHI subscription.
The tradeoff is operational, not philosophical. You're not losing functionality, you're losing the assumption that a shell is always one docker exec away. For teams in healthcare or BFSI where that compliance pressure is already non-negotiable, the migration cost is worth paying once instead of explaining the same CVE list to an auditor every quarter.