How to Install a Downloaded Package with tlmgr

A file downloaded from CTAN is not necessarily an archive that tlmgr can install. TeX Live package archives, ordinary source bundles, and TDS ZIP files have different formats, so first identify what you downloaded. This guide shows how to choose the right method and check that the package is available to TeX afterward.

First choice: install from a TeX Live repository

If the package is included in TeX Live, install it by its TeX Live package name rather than downloading a file yourself:

tlmgr install package-name

For example, if the package is called examplepkg in TeX Live, run tlmgr install examplepkg. This lets tlmgr retrieve the correct archive and manage updates and removal. The tlmgr package name may differ from the name of a .sty file.

To search for a package that provides a particular file, try:

tlmgr search --global --file examplepkg.sty

The search result includes a TeX Live package name; pass that name to tlmgr install. If the search option is unavailable in your version, check tlmgr help search or browse the TeX Live package catalogue.

Installing a downloaded TeX Live archive

Some downloads are actual TeX Live package archives, usually files ending in .tar.xz. If your installed version of tlmgr supports local-file installation, use:

tlmgr install --file ./package-name.tar.xz

Use the path to the file you downloaded. Check tlmgr help install if the command rejects --file; older versions may not support the option. A local archive must use TeX Live’s package format. Renaming a ZIP or .tar.gz file to .tar.xz does not convert it into that format.

The archive should also be compatible with your TeX Live installation. A package archive from a different TeX Live release, or one prepared for a different packaging system, may fail to install or behave unexpectedly. When possible, installing from the repository configured for your TeX Live release avoids this mismatch.

Installing an ordinary CTAN download manually

A CTAN download may instead be a source archive containing files such as .sty, .dtx, .ins, and a README. tlmgr install generally does not install such a source archive directly. Read the README first: it may explain how to generate the .sty file or whether the download includes a TDS ZIP with files already arranged for TeX.

For a simple package that provides examplepkg.sty, you can put the file in a directory under your personal TeX tree. Find the tree path with:

kpsewhich -var-value=TEXMFHOME

On many Linux and macOS installations, the result is ~/texmf. Create a package directory and copy the .sty file there, for example:

~/texmf/tex/latex/examplepkg/examplepkg.sty

If the download is a TDS ZIP, extract its contents into the TEXMF tree while preserving its directory structure. If it contains a .dtx and .ins instead, follow the README; often you must run LaTeX on the .ins file to generate the installable package files, then place those files in the appropriate tree.

After adding files, refresh the filename database if your setup requires it:

mktexlsr "$(kpsewhich -var-value=TEXMFHOME)"

TeX Live can often find files in a personal tree without a system-wide installation. Do not copy personal files into the system-wide TeX Live directories unless you intend to manage them as an administrator. A personal installation is easier to update or remove and avoids changing files maintained by TeX Live.

Worked example: choosing the right command

Suppose you downloaded examplepkg.zip from CTAN, and it contains examplepkg.sty plus a README. First inspect the README. If it says the ZIP is a TDS archive, extract it under your TEXMFHOME tree, keeping the folders inside the ZIP. If it is a source bundle with a .dtx and .ins, follow its extraction instructions and copy the generated .sty file to tex/latex/examplepkg/ in your personal tree.

Do not run tlmgr install --file examplepkg.zip for this ordinary CTAN ZIP. If instead you have a genuine TeX Live package archive named examplepkg.tar.xz, and your tlmgr supports --file, run tlmgr install --file ./examplepkg.tar.xz. If the package exists in your configured repository, tlmgr install examplepkg is generally preferable to either manual route.

To test the manual installation, check whether TeX can locate the file:

kpsewhich examplepkg.sty

If this prints the path where you placed the file, create a minimal document and compile it:

\documentclass{article}
\usepackage{examplepkg}
\begin{document}
Test.
\end{document}

Common mistakes

• Treating every CTAN download as a tlmgr archive. A ZIP, source tarball, or collection of .sty files is not automatically a TeX Live package archive.
• Using the wrong package name. The name for tlmgr install is the TeX Live package name, which need not match the file name.
• Installing into a different TeX installation. If tlmgr manages one TeX Live release but your editor compiles with another, the package may not be found. Check which pdflatex or latex your editor runs, and compare its installation with the tlmgr you used.
• Putting files at the wrong directory level. Preserve the TDS folder layout in TDS archives; for a single .sty file, put it in a suitable tex/latex/... directory under a TEXMF tree.
• Expecting a database refresh to fix every problem. mktexlsr updates file lookup information; it cannot extract a source archive, generate missing files, or correct an incorrect directory structure.