Why Your Nim Builds Drift — and How Nimble Lock Files Pin Them Down

Your Nim project builds fine on your laptop. A week later, CI fails, and the only thing that changed is that a dependency published a new patch release. Nothing in your .nimble file moved, but the build did. The cause is almost always the same: a requires clause like requires "jester >= 0.5.0" is a promise about the minimum, not a record of what you actually built against. Nimble's lock file is the fix — it records the exact resolved versions so every install gets the same code.

What a requires clause actually promises

Every Nimble project declares dependencies in its .nimble file, a small Nim-like DSL. A typical snippet:

version     = "0.2.0"
author      = "Example Team"
requires    = "nim >= 1.6.0"
requires    = "jester >= 0.5.0"
requires    = "https://github.com/example/helper#head"

Version constraints like >= 0.5.0 are resolved against the package index at install time. That means two installs a week apart can resolve to different releases. Git URL dependencies are worse: a reference to a branch like #head silently follows whatever the branch points to today. Both are fine for exploration and terrible for reproducibility.

The lock file: recording what resolution decided

Newer Nimble releases can write a nimble.lock file that captures the exact resolved versions (and, for Git dependencies, the specific commits) from a successful resolution. Once that file exists, subsequent installs follow it instead of re-resolving from scratch.

Lock-file support and its exact flags have evolved across Nimble releases, so before relying on it, check what your installed version supports:

nimble --version
nimble --help

Run these in your project directory as your normal user — no elevated permissions needed. Look for lock-related flags or subcommands in the help output. If your release predates lock-file support, the practical fallback is pinning every dependency to an exact version or commit hash in the requires clause itself.

A worked example: from drift to reproducible install

Here's the workflow I'd use to verify reproducibility on a scratch project:

1. Create a project with a versioned requires clause, then run nimble install (or the build/install command your release documents) in the project root.
2. Inspect the generated nimble.lock. Confirm it lists concrete versions or commit hashes for every dependency, including transitive ones.
3. Commit nimble.lock to version control alongside the .nimble file.
4. To prove it works, clear Nimble's local package cache (its location is platform-dependent; check nimble --help or your config) and reinstall in a clean checkout. The resolved set should match the lock file exactly.

If step 4 pulls anything different from what the lock file records, treat that as a bug to investigate — the whole point is that it shouldn't.

Libraries vs. applications: the real engineering decision

The interesting trade-off isn't whether lock files work — it's whether your repo should ship one.

Applications (anything you deploy or ship as a binary): commit the lock file. Reproducible builds across developer machines and CI are worth more than the occasional chore of deliberately updating it.

Libraries (things other people require): be cautious. If your library pins exact versions, downstream users inherit those constraints, and Nimble has to reconcile your pins with everyone else's. Over-constrained libraries cause version conflicts that consumers can't fix without forking. For libraries, keep requires ranges as permissive as you can honestly support, and either omit the lock file or treat it as an internal CI tool rather than a published contract.

One more trap: a lock file only pins what resolution produced. If a Git dependency was declared by branch, the lock records today's commit — good — but if you bypass the lock and reinstall from the .nimble file alone, you're back to drift. Prefer exact commit references in requires for anything critical.

Limitations worth knowing

• Lock-file behavior is version-sensitive. Flags, file format, and even whether the feature exists differ across Nimble releases — verify against your installed version before writing CI around it.
• A lock file doesn't protect you from upstream deletions. If a dependency's repository or tag disappears, a pinned commit may still be unfetchable. For critical builds, vendoring or an internal mirror is the stronger guarantee.
• Updating dependencies becomes an explicit act (re-resolve, review the lock diff, commit). That's a feature, but teams used to automatic freshness should expect the workflow change.

Actionable takeaway

Pick one application project this week: run nimble --version and nimble --help to confirm lock-file support, generate the lock file, commit it, and do one clean-cache reinstall to prove the build reproduces. For libraries you maintain, audit your requires clauses instead — loosen anything pinned tighter than your actual compatibility. That split, lock files for apps and honest ranges for libraries, is the decision that makes Nimble dependency management boring in the best way.