Purplelink
← All guides

How-to

TeX Live Utility "Listing Failed" on Mac: causes and fixes

By ·

TeX Live Utility shows "Listing Failed" when it cannot get the list of package updates. The status line never says why. The log does, and nearly every case is one of three causes: your TeX Live is from last year, the mirror you are using is down, or tlmgr itself is damaged. Each has a short fix.

Disclosure: Purplelink makes ModernTex, a Mac LaTeX editor. It does not install or update TeX Live, and nothing below depends on it. The menu names and messages come from the TeX Live Utility source code (version 1.58, released October 2, 2026), and the commands from the tlmgr manual and TUG's upgrade page. I read all three on November 5, 2026. I did not reproduce the errors on a test machine, so check the source if a detail does not match what you see.

First, read the log

TeX Live Utility is a front end for tlmgr, TeX Live's package manager. When you open it or press Refresh, it asks tlmgr which packages have updates. "Listing Failed" means that request ended in an error, and the error text goes to the log.

  1. Open Window > Log Window.
  2. Scroll to the newest lines and find the first message that says tlmgr: or mentions a URL.
  3. Match it to one of the causes below.

You can get the same text in Terminal, which is often quicker to read:

tlmgr update --list

This changes nothing. It only reports what an update would do, or the error that stops it.

Cause 1: your TeX Live is from an earlier year

TeX Live is released once a year, and the main repository then serves only the new year. An installation from a previous year cannot update from it. In Terminal the message looks like this (the years vary):

tlmgr: Local TeX Live (2025) is older than remote repository (2026).
Cross release updates are only supported with
  update-tlmgr-latest(.sh/.exe) --update

TeX Live Utility reports the same problem in its own words. It shows an alert titled "Repository has a different TeX Live version", saying the repository has one TeX Live year while you have another installed and that you need to switch repositories.

The fix. Install the new year. TUG's upgrade page says to get the new release by doing a new installation by default, and that any number of installations can sit side by side. On a Mac that means downloading the current MacTeX and running the installer. It puts the new year in /usr/local/texlive/ next to the old one and points /Library/TeX/texbin at it. The install guide for MacTeX, BasicTeX and TinyTeX covers the steps and the download sizes.

TUG does describe an in-place upgrade, but its own page calls the procedure not recommended and meant for people familiar with Unix and TeX Live. If you are reading this guide, the new installation is the better path.

Afterwards. When both years are installed, TeX Live Utility has a Configure > Change Default TeX Live Version item to choose which one it manages. To free the space, drag the old year's folder from /usr/local/texlive to the Trash. macOS asks for an administrator password because TeX Live is owned by root.

The opposite mistake gives a similar alert. If your repository address points at an archive of an older year, or at a mirror that is still on last year, TeX Live Utility says the repository has a different version. Switch back to the standard repository as in cause 2.

Cause 2: the mirror is down or out of date

By default, tlmgr uses mirror.ctan.org, which sends each request to a nearby CTAN mirror. If you or an installer set a specific mirror instead, and that mirror moves, goes offline or falls behind, every listing fails. The log usually shows a download error or a URL that does not respond. You may also see "Unable to find a valid update server". The app's text for it says the cause is either a network problem or a server on a different TeX Live version.

The fix. Point tlmgr back at the automatic mirror. The tlmgr manual gives two equivalent commands:

sudo tlmgr option repository ctan
sudo tlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet

In TeX Live Utility the same setting is under Configure > Manage Repositories, where Set as Home Repository makes a chosen entry the default. Then refresh. If one mirror keeps failing, CTAN publishes the status of every mirror at ctan.org/mirrors/mirmon.

Mirrors also lag for a day or so after TeX Live changes, which is why the manual suggests updating at most once a day. A failure that appeared today and that a different mirror fixes is usually this.

Cause 3: tlmgr itself is damaged or out of date

Sometimes tlmgr's own files, which TeX Live calls the infrastructure, are left half updated, often after an update was interrupted. Listings then fail with Perl errors, checksum errors or messages about the TeX Live database.

The fix. TeX Live Utility has two repair items in the Actions menu:

From Terminal, the equivalent first step is to update the infrastructure on its own:

sudo tlmgr update --self

Signature errors

If GnuPG (gpg) is installed, tlmgr checks a signature on the main repository's package list. The manual says a signature that is checked and fails to verify raises an error. Most such failures come from a mirror serving a stale or partial copy, so the cause 2 fix (the automatic mirror) is the first thing to try. Do not turn verification off to make the error go away.

Updating everything except a few packages

A related question: you want all updates except one or two, for example to keep a biber and biblatex pair you know works. In TeX Live Utility you can select packages and use Actions > Update Selected Packages. If that item is greyed out, Terminal does the same job:

sudo tlmgr update --all --exclude biber --exclude biblatex

The tlmgr manual says --exclude can be repeated, and that each one also skips the package's platform-specific parts (the biber.universal-darwin binary, in this example). Remember that the pair stays held back only until the next plain "update all".

Quick check from Terminal

Three commands answer most questions about which TeX Live you are dealing with:

tlmgr --version
which tlmgr
tlmgr option repository

The first shows the TeX Live year, the second shows which installation answers (it should be under /Library/TeX/texbin for MacTeX), and the third shows the repository in use. If the year is older than the current release, you have cause 1. If the repository is a specific mirror rather than mirror.ctan.org, try cause 2.

Sources

Frequently asked questions

What does Listing Failed mean in TeX Live Utility?
TeX Live Utility asks tlmgr, TeX Live's package manager, for the list of available updates. Listing Failed means that request returned an error. The reason is in Window > Log Window. It is usually a TeX Live year that no longer matches the repository, a mirror that is down, or a damaged tlmgr.
How do I fix Local TeX Live is older than remote repository?
Your TeX Live is from an earlier year, and the repository now serves the new release. tlmgr does not update across years. TUG recommends installing the new MacTeX rather than upgrading in place. The old year can stay on disk, or you can delete its folder in /usr/local/texlive.
How do I update every package except a few?
In Terminal, run sudo tlmgr update --all --exclude biber --exclude biblatex, with your own package names. The tlmgr manual says the --exclude option can be given more than once and that it also skips each package's platform-specific parts.