nimble develop shadowing installed packages: limiting nimble.paths entries to one project

Short answer

There is no built-in project-scoped mode for nimble develop. The command appends entries to the global nimble.paths file (typically ~/.config/nimble/nimble.paths), and every nimble invocation on that machine consults it. While a package is listed there, the develop checkout wins over both installed copies and nimble.lock pins. The supported escape hatch is to redirect the paths file itself per session, so the global file stays untouched.

Likely explanation vs. confirmed behavior

Confirmed by the documented mechanism: nimble develop is a global mutation by design — it exists so that any build picks up your local checkouts. What is less certain, and what you should verify against your installed version (nimble -v and the shipped README), is the exact precedence wording, because path/lock interaction has shifted across Nimble releases. Treat the details below as version-sensitive.

Scoping the develop setup to one project

Since the file location is the only lever, point nimble at a project-local paths file for the shell where you work:

cd ~/src/my-project
export NIMBLE_PATHS="$PWD/.nimble.paths"
touch "$NIMBLE_PATHS"
nimble develop ../lib-a ../lib-b   # entries land in ./.nimble.paths
nimble build

Key points:

• Export the variable only in that shell (or use a direnv .envrc so it activates on cd and clears on exit). Exporting it globally recreates the same leak you are trying to avoid.
• Alternatively pass the path per command (nimble --paths=... build) if your version supports the flag — check nimble --help.
• Add .nimble.paths to .gitignore; it is machine-local state.
• Because the global file is never modified, unrelated projects keep resolving from their lock files and installed packages.

Reversing it cleanly

Use the built-in undo rather than hand-editing:

nimble develop --undo lib-a     # remove one entry
nimble develop --undo all       # remove every develop entry

With NIMBLE_PATHS still set, undo edits your project-local file. If you used the global file, undo removes the lines there. Either way, afterwards the dependency resolves from nimble.lock or the installed package again.

Lock-file precedence

Expect the develop path to win unconditionally while the entry exists — that is the entire point of the feature. So a nimble.lock pin for lib-a is ignored until you undo the entry. This also means CI and other developers (who never ran develop) still build against the lock file, which is the behavior you want.

Verification checklist

1. cat "$NIMBLE_PATHS" after develop — entries present; after --undo — gone.
2. nimble show lib-a (or inspect build output paths) before and after undo to confirm which source tree is compiled.
3. Build an unrelated project in a shell without the variable set to prove it resolves from its lock file.

One caveat: if you undo an entry while another project was (intentionally or not) building against that checkout, it silently reverts to the locked version. The one missing detail that would change this advice is your exact Nimble version — if --paths/NIMBLE_PATHS behaves differently there, fall back to a dedicated shell with the env var, which is the most portable approach.