Installing Gregorio

Before you install Gregorio

If you have never used TeX before, then we strongly recommend that you start to familiarize yourself with gabc by using the Illuminare Score Editor or the Gregorio Chant Engraver. These online tools will only require you to learn about gabc itself, while handling the considerable overhead that comes with using TeX for you. You won't have access to all of the features of GregorioTeX, but you won't have to learn two things at once, making it much easier to ease into the use of Gregorio.

Once you have mastered gabc itself, and find yourself wanting access to more of the capabilities of GregorioTeX, then you need to get yourself a TeX distribution. The most common distribution is TeX Live. This distribution supports many platforms, including all the major ones (Windows, Mac, and all varieties of Linux). For Mac users, there is also a Mac specific variant of TeX Live called MacTeX which does a much better job of integrating it into the Mac environment than the cross-platform installer. Another common distribution is MiKTeX which now supports all three major platforms (Windows, Mac, and Linux in its Ubuntu/Mint varieties).

One more thing...

If you have a full installation of TeX Live (including MacTeX), then Gregorio may already be installed on your system as part of that installation. The table below indicates which versions of Gregorio shipped with which versions of TeX Live:

TeX Live version Gregorio version
2016 4.1
2017 5.0
2018 5.1
2019 5.2
2020 5.2
2021 6.0

If you have MiKTeX, then Gregorio is also included there. Because of MikTeX's rolling update model, it is impossible for us to tell you exactly what version is there, but you should be able to find and install a fairly recent, if not the most recent, version using the MiKTeX Console.

And now, finally, the installation instructions

If your TeX distribution doesn't have Gregorio, or you want a newer version of Gregorio than is available in your distribution, then refer to the following pages:

Configuration

Executable Access

By default LuaTeX (and all other varieties of TeX is only permitted to access a limited list of third-party programs. This is a security measure which prevents documents from doing things to you system that you might not expect or desire. Of course, in order for Gregorio to work, it has to be able to access its own exectuable. If you've installed TeX Live or MiKTeX, then access to the included executable is already setup for you. However, if you install an updated version, then you will need to enable access to the new executable. This can be accomplished in a number of ways:

For more information about texmf.cnf files (and related issues) we suggest reading this page or asking a question at TeX Stack Exchange.

Editor Configuration

If you plan to use an editor, then you'll need to configure it once Gregorio is installed. For instructions on how to do this, refer to the following pages:

Uninstalling Gregorio

While we hope you'll be satisfied with Gregorio and never want to remove it from your computer, we've also tried to make it as straight forward as possible to do so should the need arise. Follow the instructions below that correspond to your OS and method of installation.

TeX Live or MiKTeX (All OSes)

Make use of the package installation tools for these distributions to remove a version of Gregorio which was installed by them.

Windows Installer

Use the Uninstall feature of Add/Remove Programs. See the Windows documentation for more information.

MacOS Installer

Use the Uninstall-Gregorio-*.*.*.pkg that corresponds to the version which you installed. Download it from the appropriate release page and run it just like you did the original installer.

Command-line installation (MacOS and Linux)

If you've installed a version of Gregorio from the command-line, there is a uninstall-gtex.sh script which is generated during the installation process which you can use. This file is placed at TEXMFLOCAL/scripts/gregoriotex/uninstall-gtex.sh (where TEXMFLOCAL is the place where you installed GregorioTeX, usually the output of kpsewhich --var-value TEXMFLOCAL. To use the script you first need to set its executable bit and then run it. Given the usual installation path, that looks something like this:

chmod +x $(kpsewhich --var-value TEXMFLOCAL)/scripts/gregoriotex/uninstall-gtex.sh
$(kpsewhich --var-value TEXMFLOCAL)/scripts/gregoriotex/uninstall-gtex.sh

This removes the GregorioTeX components. Once that's done, you simply need to delete the executable, which can be done using make uninstall in the source code directory. If you did not keep your source code download, then make use of which and rm to locate and delete the executable (it should be named gregorio-*_*_*, where the wild cards correspond to the version number that was installed).

Note: Depending on how and where you installed Gregorio, you may need to execute some of the above commands as root.