Installing with Docker

Herbie is available through Docker, which is a sort of like a virtual machine. This page describes how to install the official Docker image for Herbie.

Herbie can also be installed from package or source. Herbie via Docker is only recommended if you already have Docker experience.

Installing Herbie via Docker

First, install Docker. Docker supports Windows, macOS, and Linux. Depending on how you install Docker, you may need to prefix the docker command with sudo or run them as the administrative user.

With Docker installed, download the Herbie image:

docker pull uwplse/herbie

You can now run Herbie:

docker run -it uwplse/herbie shell

This will run the Herbie shell, reading input from the standard input.

Note that Herbie in Docker is more limited; for example, it will not recognize plugins installed outside the Docker container.

Running the web shell

Running the web shell in Docker requires exposing the ports inside the container. The Herbie Docker image binds to port 80 by default; use the -p <hostport>:80 option to Docker to expose Herbie on whatever port you choose.

docker run -it --rm -p 8000:80 uwplse/herbie

If you are using the --log or --save-session flags for the web shell, you will also need to mount the relevant directories into the Docker container using the -v Docker option, as in the examples below.

Generating files and reports

To use Herbie in batch mode, you will need to mount the input in the Docker container. Do that with:

docker run -it --rm \
    -v in-dir:/in \
    -v out-dir:/out \
    -u $USER \
    uwplse/herbie improve /in/in-file /out/out-file

In this command, you are asking Herbie to read input from in-file in in-dir, and write output to out-file in out-dir. The command looks the same if you want Herbie to read input from a directory; just leave in-file blank.

To generate reports from Herbie, you can run:

docker run -it --rm \
    -v in-dir:/in \
    -v out-dir:/out \
    -u $USER \
    uwplse/herbie report /in/in-file /out/

As before, the input and output directories must be mounted inside the Docker container. Note that both here and above, the user is set to the current user. This is to ensure that the files Herbie creates have the correct permissions set.