Nimble lockfile ignored when global package satisfies version range

Question

Nimble records exact resolved dependency versions in a nimble.lock file, but by default it installs packages into a shared user-global directory rather than a project-local environment. When a globally installed package already satisfies a project's version range yet differs from the locked version, it is unclear whether Nimble reuses the global copy or enforces the lockfile, which can silently alter build inputs across machines.

Lockfile semantics and dependency path resolution have shifted across Nimble releases, so behavior observed in older tutorials may not apply to current versions and should be checked against the installed Nimble release. Nimble also lacks native support for pinning the Nim compiler version or sandboxing builds, making repeatable toolchains dependent on external wrappers or manual path management.

What is the documented resolution order when a global package conflicts with a nimble.lock entry, and does Nimble offer a supported flag or configuration to force per-project isolation from the global cache?

Tasadduq Burney · Answer

Resolution order
When a nimble.lock is present, Nimble follows this documented sequence for each dependency:

Attempt to satisfy the dependency with the exact version recorded in the lockfile.
  Check the global package cache (~/.nimble/pkgs by default) for that exact version.
  If the exact version is found in the cache, use it; otherwise install the locked version into the cache.

If a globally installed package satisfies the version range expressed in nimble.cfg but differs from the locked version, Nimble will reinstall the locked version (replacing the global copy) to enforce lockfile consistency.
Per‑project isolation
Nimble does not provide a flag to ignore the global cache entirely, but you can redirect where packages are installed:

nimblePath setting in nimble.cfg (e.g., nimblePath = "./nimble_pkgs").
  The --local flag introduced in Nimble 0.12.0, which installs packages into a .nimble subdirectory of the project for that invocation.
  The environment variable NIMBLE_PATH, which overrides the default cache location.

Using any of these mechanisms bypasses the shared global cache for the duration of the command, giving per‑project isolation.
Verification steps

Check your Nimble version: run nimble -v.
  Create a fresh Nim project, add a dependency (e.g., json) with a version range like >=0.1.0 in nimble.cfg.
  Run nimble install to generate a lockfile after installing a specific version globally.
  Install a different but compatible version of the same package globally (nimble install json --global).
  Run nimble install in the project and observe whether the locked version is reinstalled (check the directory indicated by nimblePath or ~/.nimble/pkgs).
  Repeat the test after setting export NIMBLE_PATH=./nimble_pkgs or adding nimblePath = "./nimble_pkgs" to nimble.cfg and verify that packages are placed under that directory instead of the global cache.

To confirm the exact behavior for your Nimble version, please run nimble -v and share the output.

Nimble lockfile ignored when global package satisfies version range

1 answer

Resolution order

Per‑project isolation

Verification steps

Your perspective belongs here.

0 question comments