Installation

Note

While not required, the pycoevolity Python package can be useful for summarizing the output of ecoevolity, and is used in some of the tutorials. See below for how to install pycoevolity.

There are three options for installing ecoevolity: Downloading precompiled ecoevolity programs, compiling from the source code, or using the Docker image. Use the outline below to help navigate the instructions for your preferred installation option.

Downloading precompiled programs

Download and extract precompiled programs

Linux

Use the following link that matches your CPU architecture to download ecoevolity’s precompiled programs:

To determine your CPU architecture, you can run the uname -m or dpkg --print-architecture command.

The download is a gzipped archive. To extract it, use one of these two commands, depending on which architecture you downloaded:

# For AMD arch download
tar xzf ecovolity-v1.1.1-amd64.tar.gz
# For ARM arch download
tar xzf ecovolity-v1.1.1-arm64.tar.gz

This should result in a directory (folder) named ecoevolity-v1.1.1

Try running the ecoevolity program in this directory to get the help menu:

./ecoevolity-v1.1.1/bin/ecoevolity -h

If it works, the beginning of help menu output should look something like:

======================================================================
                              Ecoevolity
                  Estimating evolutionary coevality
       Version 1.1.0 (HEAD d64cc24: 2026-01-01T14:52:21-06:00)
======================================================================

Usage: ecoevolity [OPTIONS] YAML-CONFIG-FILE

Ecoevolity: Estimating evolutionary coevality

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit

Didn’t work? Try the troubleshooting tips below.

Troubleshooting missing linked libraries

If you get an error when trying to run ecoevolity about a missing library, you might need to install the build-essential package. For example:

sudo apt-get install build-essential

This should install the missing libraries.

Mac OS X

Use the following link that matches your Mac’s hardware to download ecoevolity’s precompiled programs:

The download is a gzipped archive. To extract it, use one of these two commands depending on which architecture you downloaded:

# For Intel download
tar xzf ecovolity-v1.1.1-mac-intel64.tar.gz
# For Apple silicon download
tar xzf ecovolity-v1.1.1-mac-arm64.tar.gz

This should result in a directory (folder) named ecoevolity-v1.1.1

Try running the ecoevolity program in this directory to get the help menu:

./ecoevolity-v1.1.1/bin/ecoevolity -h

If it works, the beginning of the help menu output should look something like:

======================================================================
                              Ecoevolity
                  Estimating evolutionary coevality
       Version 1.1.0 (HEAD d64cc24: 2026-01-01T14:52:21-06:00)
======================================================================

Usage: ecoevolity [OPTIONS] YAML-CONFIG-FILE

Ecoevolity: Estimating evolutionary coevality

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit

Didn’t work? Try the troubleshooting tips below.

Troubleshooting Mac OS security

When you try running the ecoeovlity program, there’s a good chance that Mac OS will state that it can’t be opened because it cannot check it for malicious software (or can’t identify the developer). Click “OK” and then go into the “Security & Privacy” section of Sytem Preferences and click “Allow Anyway” where it states that “ecoevolity” was blocked. The next time you try to run ./ecoevolity-v1.1.1/bin/ecoevolity -h, the OS will complain again, but now there should be an “Open” button to click. After clicking “Open” ecoevolity should run and you should see the help menu. When you run ecoevolity in the future, the OS shouldn’t complain anymore.

You will have to repeat the above for all the programs in ./ecoevolity-v1.1.1/bin you would like to use.

Troubleshooting missing linked libraries

When trying to run the binary, if you get an error about a library not being found, you might need to install Xcode command line tools. For example:

xcode-select --install

The Xcode installation should include the missing libraries.

Install the precompiled programs

If running ecoevolity to view the help menu above worked, the programs in ./ecoevolity-v1.1.1/bin are ready to use, but you’ll probably want to put them in your PATH (a list of directories that your shell searches to find the commands you type on the command line).

Installing locally (no admin privileges required)

To install the programs locally within your home folder, you can use:

mkdir -p ~/.local/bin
cp ./ecoevolity-v1.1.1/bin/* ~/.local/bin

The ~/.local/bin directory is likely not in your PATH variable, but you can check using echo $PATH, which will show a “:”-separated list of directories in your PATH. To add the ~/.local/bin directory to your PATH, you can use:

export PATH="${PATH}:${HOME}/.local/bin"

Now, running ecoevolity -h on the command line should work.

Note

This update to PATH is only for your current terminal window. If you want this to be permanent (work for all future terminal windows), add the line:

export PATH="${PATH}:${HOME}/.local/bin"

to your shell’s startup file. E.g.,:

  • ~/.bashrc file in your home directory if you are using the bash shell

  • ~/.zshrc file in your home directory if you are using the zsh shell

Installing globally (admin privileges required)

If you have admin privileges and want to install the programs to a location that is almost certainly in your PATH, you can use:

sudo cp ./ecoevolity-v1.1.1/bin/* /usr/local/bin

You can check things are working by running ecoevolity -h, which should show a help menu.

Compiling ecoevolity from source code

Installing prerequisites

Compiling ecoevolity requires CMake and a new-ish C++ compiler (one that supports the C++11 standard).

Linux

If you are on a Linux machine, use your package manager to install the required software for compiling ecoevolity. On Ubuntu (or other Debian-based Linux distribution) you can use:

sudo apt-get install build-essential cmake git

Mac

If you are on a Mac, you can install Xcode command line tools using the following command:

xcode-select --install

This will get you a C++ compiler and Git. You also need to install CMake. If you have Homebrew installed you can install CMake via:

brew install cmake

If you don’t have Homebrew, you can download and install CMake from https://cmake.org/download/. Download the .dmg file for the latest version for Mac. Once installed, open CMake, and from the “Tools” menu click “How to Install For Command Line Use.” This should pop up a window that has a line like:

sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install

The line might be slightly different on your Mac. Copy that line from the CMake pop up window (not the line above), and paste it into the command line (Terminal).

Windows

We have not compiled ecoevolity in Windows. It’s possible to do, but I suspect it will take a fair bit of tweaking of the CMake configuration. If you have a Windows machine, and you are not experienced with compiling C/C++ code in Windows, you have some options:

  1. You can use Windows Subsystem for Linux to install Ubuntu. Once installed, then you can follow the instructions above for Linux.

  2. Try running our Docker image (see below).

Getting the ecoevolity source code

You can use the following link to download the latest release (v1.1.1) of the ecoevolity source code:

Once downloaded, you’ll need to unzip the archive.

Alternatively, if you have Git installed, you can download the ecoevolity repository with the following command:

git clone https://github.com/phyletica/ecoevolity.git

Build programs from source code

Next, move into the downloaded directory. If you downloaded the release archive, use:

cd ecoevolity-1.1.1

If you cloned the git repository, use:

cd ecoevolity

Then, run the build script:

./build.sh --threads

Note

The --threads option builds a version of ecoevolity that can perform likelihood calculations across multiple threads. If you don’t plan to use multithreading, you can remove this option (i.e., just run ./build.sh). In my opinion, you’re usually better off running multiple independent MCMC chains rather than multithreading, but if you have plenty of CPUs to spare, you can do both.

If the build was successful, the ecoevolity programs should now be in the ./build/bin directory, and you should be able to run:

./build/bin/ecoevolity -h

and see the ecoevolity help menu. The beginning of the help menu should look something like:

======================================================================
                              Ecoevolity
                  Estimating evolutionary coevality
       Version 1.1.0 (HEAD d64cc24: 2026-01-01T14:52:21-06:00)
======================================================================

Usage: ecoevolity [OPTIONS] YAML-CONFIG-FILE

Ecoevolity: Estimating evolutionary coevality

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit

Install the programs

If running ecoevolity to get the help menu above worked, the programs in ./build/bin are ready to use, but you’ll probably want to install them in your PATH (a list of directories that your shell looks in to find the commands you type on the command line) for easier use.

Installing locally (no admin privileges required)

To install the programs locally within your home folder, use:

mkdir -p ~/.local/bin
cp ./build/bin/* ~/.local/bin"

Then, try opening a new terminal terminal window and run ecoevolity -h. If this doesn’t work, the ~/.local/bin directory is likely not in your PATH variable. You can check what directories are in your PATH using echo $PATH. To add the ~/.local/bin directory to your PATH, you can use:

export PATH="${PATH}:${HOME}/.local/bin"

Now, ecoevolity -h should work.

Note

This update to PATH is only for your current terminal window. If you want this to be permanent (work for all future terminal windows), add the line:

export PATH="${PATH}:${HOME}/.local/bin"

to your shell’s startup file. E.g.,:

  • ~/.bashrc file in your home directory if you are using the bash shell

  • ~/.zshrc file in your home directory if you are using the zsh shell

Installing globally (admin privileges required)

If you have admin privileges and want to install the programs to a location that is almost certainly in your PATH, you can use:

sudo cp ./build/bin/* /usr/local/bin

You can check things are working by running ecoevolity -h, which should show the help menu for ecoevolity.

Build and install with one command

If you want to build and install in one go, you just need to specify where you want the installation to go using the --prefix argument. If you want to install the programs locally in your home directory (this does not require admin privileges), use:

./build.sh --threads --prefix ~/.local

If you want to install the programs “globally” for all users of the computer system (this requires admin privileges), use:

sudo ./build.sh --threads --prefix /usr/local

Using ecoevolity via Docker image

Docker provides a nice way of sharing lightweight containers that act like a virtual machine. We have created a Docker container with ecoevolity built in. To get started, you first need to install Docker. To do so, go to https://docs.docker.com/install and scroll down and click on the download button for your platform. Once Docker is installed and running, pull down our Docker image:

docker pull phyletica/ecoevolity-docker

Note

Depending on your system and how Docker is configured, you may need to use sudo to run Docker commands. If you received a “permission denied” message when you ran the command above, try:

sudo docker pull phyletica/ecoevolity-docker

This download could take several minutes depending on your internet connection. After it completes, run and enter the docker container:

docker run -it phyletica/ecoevolity-docker bash

Note

Again, you might need to prefix this command with sudo.

That’s it, you are now in a virtual container with a fully functioning ecoevolity ecosystem (ecoevolity and pycoevolity are installed, along with example data). Try typing:

ecoevolity -h

This should display the ecoevolity help menu.

To exit the container, simply type:

exit

Docker will keep the ecoevolity image around, so you can always jump back in anytime via:

docker run -it phyletica/ecoevolity-docker bash

However, any files you created on your last visit will be gone. So, if you want to analyze your data and keep the results around, cd to the directory where you want to run ecoevolity, then jump into the Docker container using:

docker run -v "$(pwd)":/portal -it phyletica/ecoevolity-docker bash

Then, once inside, type:

cd portal
ls

You should see the files that were in the directory on your computer. Now you can run ecoevolity on data in this directory, and all output files will be on your computer when you exit the container (magic!).

Using ecoevolity via Singularity image

We’ve also created a Singularity image you can download here:

Once downloaded, you can jump on the command line within the container via:

singularity shell ecoevolity-v1.1.1-linux64-intel-singularity.sif

Ecoevolity is preinstalled in the container, so you have access to all of it’s programs; e.g., try ecoevolity -h. Singularity mounts your home folder and current working directory into the container by default, so you have access to the files on your computer from inside the container.

Getting some example data

We have created Git repositories containing example data and configuration files. You can download example files for ecoevolity using:

git clone https://github.com/phyletica/ecoevolity-example-data.git

You can download example files for phycoeval using:

git clone https://github.com/joaks1/phycoeval-example-data.git

If you prefer not to use Git, you can download an archive of:

Note

If you are using the Docker image, these example data are included in the container. But, for the tutorials, it will be helpful to follow the instructions above to get a copy on your computer, outside of the container.

Installing pycoevolity

Pycoevolity is a Python package for summarizing the output of ecoevolity. It should work with Python 2 or 3. If you have Python and pip installed, you can install Pycoevolity via:

pip install git+https://github.com/phyletica/pycoevolity.git@master

If this isn’t working, try the manual installation instructions here.

Also, pycoevolity the option of using the R packages ggplot2 and ggridges for creating some plots. So, if you want this optional plotting functionality, and you don’t already have R installed, you’ll need to install it. Once R is in place, you can install the packages from the R prompt using:

install.packages(c("ggplot2", "ggridges"))