Herbie is available through Docker, which is 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.
Docker. Docker supports Windows, macOS, and Linux. Depending
on how you install Docker, you may need to prefix
docker commands with
sudo or run them
as the administrative user.
With Docker installed, you can run the Herbie shell with:
docker run -it uwplse/herbie shell
This will read 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.
You can run the Herbie web server locally with
docker run -it --rm -p 8000:80 uwplse/herbieand access the server at http://localhost:8000.
(Herbie's Docker image binds to port 80 by
default; this command uses the
option to expose Herbie on port 8000.)
If you are using the
--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.
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.
For building and testing, first clone the repo and confirm that Herbie
builds correctly with
Next, examine the Dockerfile and Makefile together. The Dockerfile
syntax is described
The Dockerfile should follow a process exactly like the Makefile,
except a clean initial environment is assumed. The build may be split
into 2 or more stages to limit the size of the resulting image. Each
stage consists of a
FROM command and a series of further
commands to build up the desired environment, and later stages can
refer to earlier stages by name--for example,
COPY --from=earlier-stage ... can copy files compiled in
earlier images. You may need to do things like bumping the version of
Rust used for binary compilation or the version of Racket used in
production, or adjusting paths to match the newest version of the repo.
Once you are ready to build:
docker build -t herbie-testbuild .from the repo's main directory will build a new test image with the tag
herbie-testbuild. You can run this image with
docker run -p 8000:80 -it herbie-testbuildand see the web demo in the host machine's browser at http://localhost:8000.
To open a shell in a running container for testing, first get the container ID with
docker psand then open a shell in the container as root with
docker exec -it <CONTAINER ID> shThe code and egg-herbie binaries should be under
First, make sure you have access to the docker repo you would
like to push the image to (e.g.
Then, give the image a name and a tag like this:
docker tag herbie-testbuild uwplse/herbie:tagnameOnce this is done, the tagged image can be pushed to the repo with
docker push uwplse/herbie:tagname
If you are pushing a new version, make sure to also update the
docker push uwplse/herbie:latest