Running CollateX on your Macintosh OSX (Mavericks)


This post was prepared originally when CollateX in version 1.5. Under CollateX, version 1.6, it is no longer distributed as Windows or Mac Zip file. Instead, it is distributed as a compressed Java archive, a .jar file. You can still run it from command line. But see new instructions at CollateX downloads.

You can also run it as a Python 3 module. For instructions on installing, see David J. Birnbaum’s Computer-supported collation with CollateX. The installation instructions include Python 3 Anaconda, CollateX, the Levenshtein Library, GraphViz, GraphViz bindings for Python, all part of a suite of resources to support a one-day seminar. It’s a bit intimidating, but I was able to install the entire suite of tools in a little over an hour, though I already had MacPorts and XCode. You need to be reasonably comfortable with command line and have Admin control over your OS.

Some troubleshooting that I had to do with setup (because I had Python 2.7 previously installed)  included re-setting Python to version 3.4 (rather than 2.7) after 3.4 installed, re-installing CollateX inside Anaconda 3.4, and re-installing GraphViz bindings in Anaconda. After each of those, restart Anaconda. Anaconda a new thing to me, and I may refer wrongly to it. But go ahead and go to Birnbaum’s installation guide and course (I’m working my way through that now). It’s much more useful than the newby instructions below.

Oh, Python scares the ever-loving bejeesus out of you? Me too. You can start at Python the Hard Way. Also, John Gutag, Eric Grimson and Ana Bell’s MITX course on Computation and Programming using Python. It’s really good, but that’s why I had 2.7 installed. Go learn it.

I believe scholarly editing is now unapologetically Tech Geekery. Sorry to be bearer of bad news: that’s just the way it is. I hope you’re younger than I am, more tech-savvy that I am, so you’ll adjust more easily. I’m having a really hard time with this.

Here begins the old post:

I had CollateX running on my Macintosh OSX (Lion, probably), but after installing Mavericks CollateX no longer ran. So I had to work through the steps for getting CollateX to run from the command line on this new OS. I had for a while satisfied myself with running it from Windows 7 PC, which still worked, but I need now to share these instructions for a graduate class anyway. These instructions are for newbies, and I welcome corrections if I use the wrong terms to describe what needs to be done from an OS or Java perspective, realms in which I have only achieved minimal literacy.

The basic steps are the following:

  • Download the application (a zip file with a directory structure) from and place it anywhere on your computer.
  • Designate the downloaded CollateX program (named collatex on Macintosh) as an executable file so that the operating system will permit it to run.
    1. You must install the Java Software Development Kit (not same as end-user Java or JRE for your browser, though the CollateX page says should work with JRE, but it did not for me).
    2. You must add the path to JAVA_HOME to your .bash_profile and re-start the terminal, so CollateX can find the Java SDK.
  • With CollateX designated as an executable and able to find Java SDK, you must issue the proper command to launch CollateX on the command line from within the “bin” directory of the unzipped CollateX directory. The command “./collatex” (do not omit period or forward slash) will indicate the version and provide a list of commands for CollateX.

Download CollateX

  • Go to and download ““. Open it with the Archive utility (or your other favorite unzip tool) and place it someplace where you can find it, such as “/Users/[your user name]/Documents/collatex-tools-1.5“.
  • When you unzip it, CollateX will create a folder with the version name “collatex-tools-1.5”, and inside that directory one will find a “bin” and a “lib“. To run CollateX, you will need to enter your Terminal (shell) and navigate to the “bin” directory. If you’re experienced and feeling lucky, open Terminal, navigate to CollateX bin, and try to run it with the command “./collatex“. If that didn’t work, continue with steps below.

Designate CollateX an executable

  • In the Terminal (shell), use Unix commands to traverse the directories (ls to display current directory, and cd with "folder name"/"folder name" (single or double quotes needed in paths if spaces in directory names, or escape spaces with backslash followed by spaces). You will not need quotation marks or escaped spaces if you used recommended path above, so go to following destination: /Users/[your user name]/Documents/collatex-tools-1.5/bin.
  • Within bin directory, type the following command: “chmod +x collatex“. The command chmod has now designated collatex file as an executable. By the way, if in Windows, you will use “collatex.bat” rather than collatex file.
  • If Java previously set up, the following command may work: “./collatex“. Tip: Don’t omit the period or slash before the command.
  • If CollateX fails to run and error message explains that your OS can’t find Java, continue with steps below.

Install the Java SDK

If you attempt to run CollateX and it fails with a Java message like below, you probably need to install the JDK (technically, you may have it installed but not mapped to JAVA_HOME, but you are a newbie with this, so probably not).

JAVA_HOME is not defined correctly.
We cannot execute /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/bin/java

  1. Go to the download site for the Java Development Kit
  2. Click the button for the JDK Download.
  3. Accept the License Agreement.
  4. Download the appropriate one for your operating system: Macintosh OS X x64. If on Windows, select Windows x64 (Windows 7, 64 bit or Windows 8), or Windows x86 (earlier or Windows 7, 32 bit).
  5. Install the JDK.

Tell Macintosh OSX where to find Java

These steps are some kind of with-Java-you-must-work-with-the-force-not-against-it that I don’t actually understand, but they were necessary.

  1. Open your terminal.
  2. Enter the following command and press Enter, exactly as below:
    echo export "JAVA_HOME=\$(/usr/libexec/java_home)" >> ~/.bash_profile
  3. Why? I don’t know. But see this link and this link if you are interested in sussing out why.
  4. Then exit and close the terminal. If you don’t exit and close the terminal entirely, CollateX will continue to NOT WORK.

Run CollateX

  1. Re-open terminal (you closed it after mapping JAVA_HOME in previous step).
  2. Using the finder, place two files that you want to collate (wit1.txt and wit2.txt in the bin directory. I recommend plain one-sentence text files. wit1.txt would have one line: “This is witness 1 of the work.” wit2.txt would have one line: “This is witness 2 of the same work.”
  3. Using the cd and ls command, make your way to “/Users/[your user name]/Documents/collatex-tools-1.5/bin“. To make life easier for yourself, you can open the Finder and have a visual reminder of your location.
  4. To confirm that CollateX is functioning, enter the following command: :./collatex” (do not omit period or forward slash). Because you did not tell CollateX to do anything, it will do nothing more than to display the documentation.
  5. If wit1.txt and wit2.txt are in the bin directory, collatex is an executable file, collatex can find Java on your OS because you instructed it where JAVA_HOME is located, and the Terminal is running the command from within the bin directory, enter the following command: ./collatex wit1.txt wit2.txt > witness1and2compared.txt
  6. If that works and outputs a file witness1and2compared.txt, have at it. The full documentation is at

If anyone asks what kind of work you do, you may now say with a straight face that you are a philologist.

This entry was posted in Uncategorized and tagged , . Bookmark the permalink.

1 Response to Running CollateX on your Macintosh OSX (Mavericks)

  1. Pingback: Collation in Scholarly Editing: An Introduction | Fill His Head First with a Thousand Questions

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s