The Dune team has started planning the next major release and we would like to share and discuss the current plan with the community. We expect to release Dune 3 in August 2021. Here is the corresponding page.

As with previous major releases, we put a lot of effort in backward compatibility. The majority of Dune users should not notice any breaking changes unless they explicitly opt into the new behaviour by increasing the version of the Dune language to 3.0 in the dune-project file. However, some of the changes that we plan to make are not specific to the way Dune deals with individual projects, and so they cannot be versioned through dune-project files. This means that a small number of packages may be broken by upgrading from Dune 2 to Dune 3. We are happy to help the authors of the affected packages to fix the breakage.

What’s new

Here are the main features we plan to include in Dune 3:

  • Incremental file-watching mode. Dune already supports a basic file-watching mode, activated by the -w flag, where the build is restarted whenever any source file changes. The current implementation is non-incremental: restarting really means restarting the build from scratch, which, for example, involves reparsing all dune files. On small-size projects, this is fast enough, but this clearly doesn’t scale well to large monorepos. We are making the file-watching mode fully incremental, to avoid redoing the computations whose inputs didn’t change since the previous build.

  • Dune RPC. We are working on adding an RPC server to Dune that will make it possible to control Dune programmatically (instead of using the command line), which is often desirable for integration with various other tools, such as editors.

  • Better support for warnings. Currently, if Dune executes a build command that reports a warning but doesn’t fail, that warning will only be shown to the user on the first build. Indeed, since the command succeeded, there is no need to rerun it again in subsequent builds unless its inputs change, and so the warning may go unnoticed and unfixed. This is why Dune turns warnings into errors by default, which can be annoying. Dune users (and we too) often complain about this, so we are working on better support for warnings.

What we plan to change

We plan to make two changes that affect the semantics of dune files in a backward-incompatible way.

  • Better scoping semantics. Dune provides some project-level scoping functionality, for example, it is possible to mark a library as private to prevent leaking the implementation details outside of a project. The current implementation of scoping has wrong semantics for nested vendored projects: a public library in the inner vendored project escapes its scope and is globally visible. This loophole caused problems for users, and we are going to remove it. This will be a breaking change but nested vendored projects are not very common, so this change will only affect a small number of users and in a positive way.

  • Disallow conditional cycles. Dune language makes it possible to declare optional libraries that depend on each other, as well as libraries that enable each other via enabled_if. The semantics of such conditional cycles had never been formalised. Furthermore, their existence significantly complicates Dune’s library resolution logic. We would like to simplify this part of Dune and plan to disallow conditional cycles. This is a breaking change but we are not aware of any packages that would actually be broken by this, so please get in touch if you have any concerns.

What we plan to remove

We plan to remove the features listed below. Please let us know if you will be affected and will need some help with the transition to Dune 3.

  • Support for opam 1. We believe that it is not used any more (it was deprecated in 2017), so we’d like to remove the associated code.

  • The external-lib-deps subcommand. This subcommand prints out an approximate set of external libraries that are required for building given targets, without running the build. While this feature is useful, over time the quality of approximation has degraded and the cost of maintenance has increased.

  • Automatic creation/editing of dune-project files. If there is no dune-project file, Dune interprets the dune file using the latest version of the Dune language, which changes over time. It is therefore a good practice to create a dune-project file to freeze the semantics of the dune file to a specific version of the language. Dune used to provide some support for creating and updating dune-project files automatically but in practice this feature caused a fair amount of confusion for users, so we are removing it.

  • Calling ocamlfind at runtime. When running Dune outside of an opam environment, Dune invokes ocamlfind if it is present to figure out where to look for installed libraries. This is bad for reproducibility and doesn’t feel useful anymore, so we plan to stop doing that. Dune will however continue to use the OCAMLPATH variable, as well as the search paths hard-coded at build time by the optional ./configure script.


This plan is not set in stone. If you don’t like it, please let us know and we will see how we can improve it.

Note that the Dune team is currently working on a few other features. They are not going to be synchronised with the Dune 3 release, which is why we didn’t mention them above. If you are waiting for them, don’t worry: they are still coming but not necessarily in Dune 3. And don’t hesitate to remind us about your favourite feature requests — this helps us to set priorities.