Switch branches/tags
0.0.x 0.2.x 0.3.x add-travis-windows andreypopp/debug-macos-failure andreypopp/esy-release-improvements andreypopp/fix-647 andreypopp/gen-bat-shell andreypopp/include-workflow andreypopp/lockfile-syntax andreypopp/test-win-padding andreypopp/try-ocurl appveyor/debug bootstrap bryphe/appveyor/cache-npm bryphe/appveyor/improve-caching bryphe/bugfix/eaccess-on-install bryphe/build/remove-bootstrapping bryphe/ci/azure-windows-caching bryphe/ci/platform-package-report bryphe/ci/test-slowtest bryphe/dependency/appveyor-esy-0.3.4 bryphe/dependency/ocaml-4.6.8 bryphe/dependency/upgrade-esy-bash-0.2.1 bryphe/docs/xplat-draft bryphe/esy-rewrite-prefix-1 bryphe/inline-fastreplacestring bryphe/investigation/debug-logging-windows-hacks bryphe/investigation/debug-logging bryphe/lockfile-fixes+slowtests bryphe/proto/esyi-unblocked-windows bryphe/proto/use-forked-submodule bryphe/prototype/unc-paths bryphe/test/slow-test-compilation bryphe/travis/windows-build bryphe/windows/bugfix-arch bryphe/windows/build-esyi bryphe/windows/build-validate-ocamlbuild-project bryphe/windows/e2e-tests bryphe/windows/esy-build-package-permission-denied bryphe/windows/esyi-bash-windows-commands bryphe/windows/forked-override-repo bryphe/windows/hack-resolve-command bryphe/windows/hook-up-slowtests bryphe/windows/lockfile-logging bryphe/windows/long-paths-part-2-check-reg bryphe/windows/release-artifact-part-1 bryphe/windows/skip-flaky-test bryphe/windows/slow-tests bryphe/windows/solver bryphe/664/windows-out-of-space bryphe/667/repro docs/cleanup feat/pnp fix/linked-changes fix/memoize fix/no-package-name fix/opam-test-doc fix/slow-test intern-fastreplacestring master rauanmayemir/feature/findlib-config some-random-pr test/fast-slow windows-recovery
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
266 lines (169 sloc) 4.84 KB
id title

Reference of all available esy commands. The most common commands are esy install and esy build.

Main commands


The default command combines esy install and esy build and runs them in consecutively.

This makes it possible for the default esy project workflow be just:

% git clone && cd PROJECT
% esy

The commands above will clone project sources and make all dependencies including compiler toolchain and dev dependencies like IDE plugins be installed & built.

esy install

Install dependencies declared in package.json:

% esy install

If the solution lock esy.lock (an analogue of yarn.lock lockfile) exists then it will be used to resolve dependencies' version constraints to concrete versions, otherwise constraints resolution will be performed and saved to a fresh esy.lock.

esy build

Ensure all dependencies are built and then execute the project's build commands. Note that esy tries to reuse built artifacts as much as possible, even across different sandboxes. That means that usually esy build executes only root project's build process.


% esy build

You can also use esy b shortcurt instead of esy build:

% esy b

Run commands in the specified environment

These commands allow to execute arbitrary commands in esy's managed environments. For more info about environment types see [corresponding docs][].


Run command COMMAND in the command environment.


% esy vim ./bin/

As command environment contains development time dependencies (like @opam/merlin) vim program will have access to those.

esy build COMMAND

Run command COMMAND in the build environment.

For example, we can see which ocamlfind libraries are available:

% esy build ocamlfind

Another example usage would be to execute a build process for some specific build target:

% esy build dune build bin/hello.exe

This is useful when you want to perform a build just for a subset of build outputs.

You can also use esy b shortcurt instead of esy build:

% esy b dune build bin/hello.exe


Execute command COMMAND in the test environment.


% esy x hello

This invocation puts root project's executables in $PATH thus it's useful to test the project as it was installed.

esy shell

Initialize shell with the project's command environment.


% esy shell
% vim

The commands above are the equivalent of running esy vim.

esy build-shell

Initialize shell with the project's build environment.


% esy build-shell
% dune build bin/hello.exe

The commands above are the equivalent of running esy build dune build bin/hello.exe.

The command accept a position argument which allows to shell into a specific package's build environment, referring to the package by its name:

% esy build-shell @opam/lwt

This command is useful for debugging failing builds.

Sandbox introspection

esy ls-builds

Prints a dependency tree with status of each package.


% esy ls-builds

esy ls-libs

Prints a dependency tree with all available libraries.


% esy ls-libs

esy ls-modules

Prints a dependency tree with all available libraries and modules.


% esy ls-modules

esy build-env

Prints build environment on stdout.


% esy build-env

esy command-env

Prints command environment on stdout.


% esy command-env

Other commands

esy add

Adds a new dependency for a project.


% esy add @opam/lwt

esy release

Produce an npm package with pre built binaries for the current platform inside the _release directory.

See Building Releases for more info.

esy export-dependencies

Export dependencies of the root project from a build store.


% esy export-dependencies

The invocation above produces a set of tarballs inside _export directory. Those tarballs can be shipped to another host and imported into build store with esy import-build command.

esy export-build

Export a single build out of a build store.


% esy export-build ~/.esy/3/i/ocaml-4.6.0-abcdef90

This commands produces _export/ocaml-4.6.0-abcdef90.tar.gz tarball which can be imported into another build store with esy import-build command.

esy import-build

Import a single build into a build store.

Import from a previously exported build:

% esy import-build ./_export/ocaml-4.6.0-abcdef90.tar.gz

Import from a build store:

% esy import-build /path/to/build/store/3/i/ocaml-4.6.0-abcdef90