Pin your Docker image tags: `latest` is not a version

TL;DR: image: something:latest means “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 latest with 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 revert puts 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:

  1. Every image in every compose file has an explicit tag. No exceptions.
  2. Stateful services (databases, anything holding data I care about) are pinned to an exact version, and I back up before bumping them.
  3. Stateless services get a major-version tag.
  4. 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.