setup-texlive-action

A GitHub Action to set up TeX Live

This action provides the following functionality:

• Installing and setting up a specific version of TeX Live;
• Caching and restoring TEXDIR by default to improve workflow execution time;
• Optionally configuring an additional package repository and installing TeX packages.

Linux, Windows, and macOS are supported.

Breaking Changes in V3

In most cases, you can upgrade from v2 to v3 without changing your workflow.

Use Node.js v20 as runtime.

	With Node.js v16 having reached its end-of-life and GitHub Actions beginning the transition to Node.js v20, the action has upgraded its default runtime to Node.js v20. If you are using a self-hosted runner, please update it to v2.308.0 or later to ensure node20 runtime functionality.

Change the condition under which cache-hit is set to true.

	To be more consistent with official actions such as actions/cache, the cache-hit output is now set to true only if a cache is found that exactly matches the specified version and package set. To simply check if a cache was found, use cache-restored instead: - uses: teatimeguest/setup-texlive-action@v3 id: setup - if: fromJSON(steps.setup.outputs.cache-restored) run: echo 'A cache has been found'

Change default installation prefix, environment variable name, and cache key prefix.

	Actions published on GitHub Marketplace have unique names defined in the metadata file action.yml. To minimize conflicts with other actions, the action name (setup-texlive-action) is now used for the following things: Directory name of the default installation prefix: - $RUNNER_TEMP/setup-texlive + $RUNNER_TEMP/setup-texlive-action Environment variable name: - SETUP_TEXLIVE_FORCE_UPDATE_CACHE + SETUP_TEXLIVE_ACTION_FORCE_UPDATE_CACHE Cache keys.

Change default texmf user directories.

	As with install-tl's portable installation, user directories are now set by default to be the same as the corresponding system directories. To emulate the previous behavior, specify the user directories explicitly using environment variables: - uses: teatimeguest/setup-texlive-action@v3 env: TEXLIVE_INSTALL_TEXMFHOME: ~/texmf TEXLIVE_INSTALL_TEXMFCONFIG: ~/.local/texlive/<version>/texmf-config TEXLIVE_INSTALL_TEXMFVAR: ~/.local/texlive/<version>/texmf-var

Change syntax for the package-file input.

	The package-file input now accepts glob patterns to specify multiple files: - uses: actions/checkout@v4 - uses: teatimeguest/setup-texlive-action@v3 with: package-file: | .github/tl_packages **/DEPENDS.txt This change might break existing workflow behavior since special characters such as * and ? will need to be escaped.

Table of Contents

• Usage
  • Basic Usage
  • Caching
  • Historic Versions
• Inputs
• Outputs
• Environment Variables
• Permissions
• Troubleshooting
• Changelog
• License

Usage

Basic Usage

- name: Setup TeX Live
  uses: teatimeguest/setup-texlive-action@v3
  with:
    packages: scheme-basic

To make it suitable for CI use, by default, the action will only set up tlmgr (TeX Live package manager) and will not install any TeX packages, even basic commands such as pdflatex. If you want to install some TeX packages, you can use the packages input:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    packages: |
      scheme-basic
      hyperref
      microtype

  # `pdflatex` is now available
  # along with hyperlink and microtypography support.

Note

Since tlmgr does not manage package dependencies, you will need to explicitly specify all the packages you depend on. If you are not sure exactly which packages are required, it is recommended to install at least scheme-basic, which contains the most basic packages such as latex and amsmath.

See also "Troubleshooting."

You can also specify packages by file using the package-file input:

- uses: actions/checkout@v4
- uses: teatimeguest/setup-texlive-action@v3
  with:
    package-file: |
      .github/tl_packages
      **/DEPENDS.txt

Caching

By default, the action will save TEXDIR to cache using @actions/cache. This is done in the post-process of a completed workflow job, so that, for example, LuaTeX font cache files generated in your job are also saved and restored as part of the cache entry.

If you have problems due to a corrupt cache entry, you can delete it from the web interface, GitHub CLI, or REST API. For an example of programmatically deleting cache entries created by this action using actions/github-script, see this script.

If you want to disable caching, set the cache input to false:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    cache: false

Historic Versions

You can use an older version of TeX Live by setting the version input:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    version: 2008

The action will install an older version using historic archive with small patches to fix minor problems.

Supported TeX Live versions

OS	Runner	TeX Live Versions
Linux	ubuntu-‍24.04*	2008–2024
	ubuntu-22.04
	ubuntu-20.04
Windows	windows-2022*
	windows-2019
macOS	macos-15	2013–2024 📝 Versions prior to 2013 are for 32-bit systems and will not work due to Bad CPU type in executable.
	macos-14*
	macos-13
The runners marked with "*" are the current -latest runners (i.e., ubuntu-latest, windows-latest, and macos-latest).

Inputs

All inputs are optional.

Name	Type	Description
cache	Bool	Enable caching for TEXDIR. Default: true
package-file	String	A (multi-line) glob string to specify files that contain package names to be installed. The file format is the same as the syntax for the packages input. In addition, the DEPENDS.txt format is also supported.
packages	String	TeX package names to be installed, separated by whitespaces. Schemes and collections are also acceptable. Everything from "#" to the end of line will be treated as a comment.
prefix	String	TeX Live installation prefix. This has the same effect as TEXLIVE_INSTALL_PREFIX. Default: $RUNNER_TEMP/setup-texlive-action
repository	URL	Specify the package repository URL to be used as the main repository. Currently only http(s) repositories are supported.
texdir	String	TeX Live system installation directory. This has the same effect as the installer's -texdir option and takes precedence over the prefix input and related environment variables.
tlcontrib	Bool	Set up TLContrib as an additional TeX package repository. This input will be ignored for older versions. Default: false
update-all-packages	Bool	Update all TeX packages when cache restored. Defaults to false, and the action will update only tlmgr. Default: false
version	String	TeX Live version to install. Supported values are 2008 to 2024, and latest. Default: latest if the repository input is not set, otherwise the remote version will be assumed.

Outputs

Name	Type	Description
cache-hit	Bool	A boolean value to indicate if an exact cache match was found. Implies cache-restored.
cache-‍restored	Bool	A boolean value to indicate if a cache was found.
version	String	The installed TeX Live version.

Environment Variables

The action reads the following environment variable:

Name	Type	Description
SETUP_TEXLIVE_ACTION_​FORCE_UPDATE_CACHE	String	Setting this to anything other than 0, the action will use a unique cache key each time to keep the cache up-to-date. ⚠️ Enabling this will consume more cache space.
SETUP_TEXLIVE_ACTION_​NO_CACHE_ON_FAILURE	String	Setting this to anything other than 0, no cache will be saved when a job fails.
NO_COLOR	String	Disable color output.

In addition, the official environment variables for install-tl are supported, with the exception of TEXLIVE_INSTALL_TEXMFSYS(CONFIG|VAR) in order to ensure system directories are cached correctly.

To specify the installation prefix, either the input prefix or the environment variable TEXLIVE_INSTALL_PREFIX can be used, with prefix taking precedence if both are set. Precedence for all other texmf-related inputs and environment variables follows the behavior of the latest version of install-tl.

Default values in this action

Name	Default
TEXLIVE_DOWNLOADER
TL_DOWNLOAD_PROGRAM
TL_DOWNLOAD_ARGS
TEXLIVE_INSTALL_ENV_NOCHECK	1
TEXLIVE_INSTALL_NO_CONTEXT_CACHE
TEXLIVE_INSTALL_NO_DISKCHECK
TEXLIVE_INSTALL_NO_RESUME
TEXLIVE_INSTALL_NO_WELCOME	1
TEXLIVE_INSTALL_PAPER
TEXLIVE_INSTALL_PREFIX	$RUNNER_TEMP/setup-texlive-action
TEXLIVE_INSTALL_TEXMFLOCAL
TEXLIVE_INSTALL_TEXMFHOME	Same as TEXMFLOCAL
TEXLIVE_INSTALL_TEXMFCONFIG	Same as TEXMFSYSCONFIG
TEXLIVE_INSTALL_TEXMFVAR	Same as TEXMFSYSVAR
NOPERLDOC

Permissions

This action does not use GITHUB_TOKEN and does not require any permissions.

Troubleshooting

If a problem persists, feel free to open an issue.

• Dependency Issues
• Repository-Related Issues
• Local Testing
• Debug Logging

Dependency Issues

Unlike other package managers such as pip or npm, TeX Live (tlmgr) has very little dependency management, so generally it is difficult to determine exactly which packages you need. Lacking some indirect dependencies, you may often encounter compilation errors like:

! LaTeX Error: File `XXXXX.sty` not found.

While there is no perfect solution, there are some tools that can help address this problem:

Name	Version	Description
DEPP		Dependency Printer for TeX Live
TeXFindPkg		Query or install TeX packages and their dependencies
texliveonfly		On-the-fly download of missing TeX live packages

Repository-Related Issues

By default, the action automatically picks one of the CTAN mirrors and sets it as the main package repository for the installation. Infrequently, there may be some problem with the repository, causing setup to fail with log messages like:

• Error: unable to verify the first certificate

• TeXLive::TLUtils::check_file_and_remove:
    checksums differ for /tmp/path/to/some/package.tar.xz:

• gpg: BAD signature from "TeX Live Distribution <tex-live@tug.org>" [ultimate]

In most cases, these problems do not last so long and after a while the workflow should be stable again.

Alternatively, you can pin the main repository using the repository input to avoid using problematic repositories:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    repository: https://example.com/path/to/systems/texlive/tlnet/

For more information on the repository URL format, see "3.3.1 The -repository option" in the official TeX Live documentation.

Local Testing

If you are using a container engine such as docker, act allows you to run a workflow locally inside a container environment, without having to push changes to GitHub, saving a lot of time in setup for CI. This action can be run on a node:20 image, so the following configuration is a good starting point for testing or debugging with act:

.actrc

--platform ubuntu-latest=node:20 --pull=false --detect-event --env RUNNER_DEBUG=1 # Enable debug logging # --env NODE_DEBUG=<module> # Might be useful in few cases

Debug Logging

On GitHub, debug logging can be enabled without modifying a workflow file by setting repository configuration variables. See the GitHub Docs for more information.

Changelog

See the releases page.

License

MIT License

For third-party software licenses and copyright notices, please refer to dist/NOTICE.md.