Pin your Docker image tags: `latest` is not a version
TL;DR:
image: something:latestmeans “whatever the maintainer pushed most recently,” and it changes under you without asking. Pin a specific version tag, upgrade deliberately one stack at a time, and use an update bot to tell you when new versions exist instead of letting them install themselves.
Open a random homelab compose.yml on the internet and you’ll see it:
image: somethingcool:latest. It feels like the responsible choice. You want the
latest fixes, right?
It’s the single most common reason a homelab that “was fine yesterday” is broken today. I’ve been bitten by it enough times that I now treat an unpinned image as a bug.
What latest actually is
latest isn’t magic. It’s just a tag, and by convention it’s the default tag Docker
uses when you don’t specify one. It points to whatever image the maintainer last
decided to call latest. That can change any time they push.
So latest doesn’t mean “the newest stable release.” It means “whatever this tag
pointed to the last time this machine pulled it.” Two machines running the same
compose file can be running different versions. The same machine can jump several
major versions the next time something triggers a pull, like a fresh deploy or a
cleanup that removed the old image.
The failure it causes
Here’s how it plays out. You haven’t touched a service in months. You rebuild the
host, or run a routine docker compose pull, and it comes up broken. The config
format changed, a database needs a migration, an environment variable was renamed.
And because you didn’t choose to upgrade, you don’t know what version you were on,
what you’re on now, or what changed in between.
That’s the core problem: with latest, upgrades happen to you instead of being
something you do. And they happen at the worst time, when you’re doing something
else entirely.
Databases are where this really hurts. Many database images can’t simply start on a data directory created by an older major version; they need a deliberate upgrade step. A surprise major-version jump there isn’t a quick fix, it’s an afternoon.
Pin a real version
The fix is boring: name the version.
services:
app:
image: example/app:2.4.1 # not :latest
db:
image: postgres:16 # a major version, on purpose
How specific to be is a judgment call:
- Exact version (
2.4.1) is fully reproducible. Nothing changes until you change it. Best for anything stateful or fragile. - Major version (
16) lets you pick up patch and minor releases while never jumping a major version by surprise. A reasonable middle ground for well-behaved projects that respect semantic versioning. - Digest (
@sha256:...) pins the exact image bytes. Maximum reproducibility, worst readability. Useful if you’ve been burned by a maintainer re-pushing a tag.
Whatever you choose, the key property is that the version is written in the file, so it’s in git, so it’s in your history. (You are keeping your stacks in git, right?)
“But then I’ll never update”
This is the real objection, and it’s fair. Pinning trades surprise breakage for the
risk of falling behind on security fixes. The answer isn’t to go back to latest;
it’s to make updating a visible, low-effort habit.
- Let a bot tell you, not do it for you. Dependency-update tools can scan your repo, notice a newer image tag exists and open a pull request bumping it. You read the release notes, merge, and your normal deploy picks it up. You get awareness without the surprise.
- Avoid silent auto-updaters for anything important. Tools that watch running
containers and swap in new images automatically are convenient for throwaway
services. For a database, a password manager, or anything you’d miss, they’re
latestwith extra steps. - Upgrade one thing at a time. One stack, one version bump, one commit. If it
breaks, you know exactly what did it and
git revertputs it back. - Read the release notes for major versions. Minor bumps are usually safe. Major bumps are where the migrations and breaking changes live.
A reasonable policy
Here’s what I actually do:
- Every image in every compose file has an explicit tag. No exceptions.
- Stateful services (databases, anything holding data I care about) are pinned to an exact version, and I back up before bumping them.
- Stateless services get a major-version tag.
- An update bot opens pull requests; I merge them in small batches when I have time to watch the result.
It’s slightly more work than latest. It’s much less work than restoring a
database at 11pm because a restart pulled a new major version you never asked for.