Are there best practices w.r.t. `opam install --locked`?

Dear all,

I’m wondering whether there are best practices regarding the opam install --locked option, especially from a CI and packaging perspective?

The doc says it allows one “to share a set of dependencies that you know (locally) the project is working with”.

But to be more precise:

  1. is it advised to commit a project.opam.locked in all projects?

if yes, this yields two standard ways to build the project (with opam install --locked or simply with opam install), so:

  1. should the CI configuration build the project using the project.opam.locked or project.opam spec, or both (with two separated jobs in a fresh environment)?

  2. and for end users (assuming they build the project in a fresh switch), should we recommend using the project.opam.locked or project.opam spec?

  3. As an aside, are there standard ways (maybe semi-automatic?) to facilitate the update of a project.opam.locked spec?

Thanks for any references/suggestions,


Disclaimer: it seems the feature is little used for now, so we might make some changes for 2.1 (and in any case, document/advertise it better). In any case, your feedback is welcome!

It makes much less sense for libraries, but it is advised for applications (which is also how other package managers generally advise to use them)

Both may be of interest:

  • if your CI is producing artefacts, deployments, etc., you most likely want to remain on the most stable setup (so the .opam.locked file)
  • if you are running tests, you may want them to also ensure compatibility with e.g. new releases of the dependencies, in which case you want the plain opam file.
    For tests on contributions, PRs, etc., you probably want the stable setup too.

Assuming they just want a working version, advising the locked file is safer, esp. on a fresh switch. On an existing switch, that might needlessly force them to downgrade installed packages, so they can try but it shouldn’t be the recommendation.

Re-running the opam lock command (plugin for opam 2.0, built-in 2.1 alpha) is the only way at the moment; if you made manual changes, the best I can suggest at the moment would be cp opam.locked opam.locked.old; opam lock; meld opam.locked.old opam.locked.
We are how discussing ways to improve generation for lock-files that end up specific to a given arch/os setting, because the dependencies may depend on that.