How to Use Opam Alongside Dune Package Management

This guide will show you a workflow for gradually adopting Dune Package Management, while retaining the use of an Opam switch as the default way of resolving dependencies of a project. It assumes you have a project with dependencies, and are managing those dependencies with an Opam switch. By the end of this guide you’ll have enabled Dune Package Management for your project, however by default Dune will still use an Opam switch to resolve your project’s dependencies. By setting an environment variable or passing an extra argument to commands like dune build you’ll be able to toggle between an Opam-based workflow and a purely Dune-based workflow.

Create a file named dune-workspace at the root of your project, with the following contents:

(lang dune 3.21)

(pkg disabled)

Since dune-workspace is the default workspace file, this tells Dune that by default, don’t use its internal package management mechanism to resolve the project’s dependencies, even in the presence of a lockdir.

Now create a second file in the project root named dune-workspace.pkg. The name of this file isn’t important, but conventionally alternative workspace files begin with the dune-workspace. prefix. Add the following to this new file:

(lang dune 3.21)

(pkg enabled)

With these two files in place, by default Dune will use the specified Opam switch to resolve your project’s dependencies. However, setting the environment variable DUNE_WORKSPACE=dune-workspace.pkg will cause Dune to use its internal package management mechanism to resolve dependencies instead. Unset the DUNE_WORKSPACE environment variable to return to an Opam-based workflow.

Alternatively to setting the DUNE_WORKSPACE environment variable, invoking commands like dune build, dune exec, and dune pkg lock with the argument --workspace=dune-workspace.pkg also has the effect of changing which workspace file Dune will use to the one which enables package management.