TeX Live package contributions
This page gives some information about contributing packages to TeX Live (TL), and how to make integrating your
package easier for the TL maintainers.
On this page: requirements
- normal TeX packages
- complex TeX packages
- a) First, the package must be free (as in freedom) software,
available under, for example, the LaTeX Project Public
License or GNU
General Public License. Please state the license explicitly in your
package's source code, README, and/or other documentation. Those
licenses (and others) contain instructions for how to apply them to your
- a) The package must be useful in itself, or useful in conjunction
with free software. In other words, we won't install a package that
exists only to support something nonfree, even when it is free itself
(e.g., LPPL'd macro support for a proprietary font). That doesn't help
the free software world, and would rightly be rejected by free distros in
b) We very strongly recommend using an existing license;
devising your own will certainly delay any inclusion in TeX Live. We
also strongly recommend using a clause “or any later
version” with any license. The licensing
conditions for TeX Live go into more detail about what is and isn't
- The source for any generated documentation files (e.g., pdf) must
also be available for the generated documentation to be included in TeX
Live. We won't refuse to install the package itself, but we must
refrain from installing generated documentation when there is no source.
is as important as free software.
- If you haven't uploaded your package to CTAN, please
do that. Virtually all TL packages come from CTAN and that is by far the easiest place for us
to update from. It's beneficial for the TeX world as a whole for CTAN
to be as comprehensive as possible.
- The @ character cannot be used in any filenames. Our
tools are not prepared to handle this, and since it's trivial to avoid
we'd rather not spend time on it.
- The package should not create (the likelihood of) any new runtime
filename conflicts; in other words, all names should be reasonably
expected to remain unique; using the package name as a prefix is usually
the best approach. In addition to conflicts in the TeX tree, new
executables should have names that are reasonably distinctive, and not
just within the TeX world—most executables will end up being
installed in system-wide directories as part of operating system
We don't include packages in the experimental or obsolete trees on
CTAN unless the author explicitly requests it. All other packages that
meet the above criteria are fair game by default, and we try to install
any new ones (that don't require compilation; see below) within a few
days of their appearance on CTAN. If you find qualifying packages
missing in TL, feel free to email email@example.com. Ones that
have been looked at and excluded are (tersely) listed in the ctan2tds
TeX-world packages - normal
Standard (La)TeX packages with a .ins file, .dtx, README, etc., don't
need any special treatment; they can just have all the files at the top
level. The TL scripts more or less
automatically translate the CTAN package into the TDS arrangement used in TL.
It is best for the documentation for a package foo to be in the file
foo.pdf. If this is not possible for whatever reason, please use
foo-doc.pdf. In any event, please do not name it literally
manual.pdf; that generic name does not help users. As
mentioned above, please include all sources to the documentation.
If you use .dtx files, please provide a way to generate the derived
.sty (or any other) runtime files without regenerating the
documentation, typically by using different engines for the different
purposes. For TL, we generally don't want to regenerate documentation,
but do need to generate derived files.
Special case: if you are making a LaTeX package containing
.tex files which should be installed in the runtime tex/ subtree (that
is, are not documentation), please be sure and state this in your README
and ideally in the package announcement as well.
TeX-world packages - complex
Some packages are complex.
If your package has many files in many different places, and especially
if it does not follow normal naming conventions, distributing it as
subdirectories of a texmf tree, with your files in the TDS places, can
be useful. This can be done by uploading to CTAN a
.tds.zip file along with the main tree (see the “In
However, if your package is not very large, or you are not extremely
well-acquainted with the TDS, please don't worry about this. A
.tds.zip file is never a requirement, nor even a
recommendation; it causes more trouble than it solves when the TDS
organization is not correct, which can happen all too easily.
Nevertheless, if you do this: as a rule of thumb for LaTeX packages,
only .dtx and .ins files go in source/; general auxiliary files can go
in doc/. For packages that include Type1 fonts, please include .tfm
files and .map files.
Packages with executables
If your package includes source files that actually have to be
compiled into binary executables, such as C (recommended) or C++ (extra
pain), it is necessary to use the GNU configuration
standards, implemented with Automake. The entire
TeX Live source tree is based on Automake,
and its option names, variables, and other conventions and features must
be supported. Much more info about this is in the TeX Live build manual.
Packages containing executables written in a scripting language are
easier to deal with. Some comments on languages:
- We recommend using either Perl or (especially) TeXLua, for the simple reason that we
provide those interpreters in TeX Live itself, including on Windows.
(A couple of the
Perl packages in TL: bundledoc, texfot; and TeXLua packages:
- For other languages (Python, Ruby, shell scripts), it is up to the
end-users to install everything necessary. Unix shell scripts will
generally not be usable on Windows. (A couple of the Python
packages in TL: lilyglyphs, dviasm. A Ruby package: match_parens.)
- Java: ironically, given its design goals, Java turns out to be less
portable in practice than other languages, and has additional
complications; we don't recommend it. (Some Java packages are
in TL, though, such as arara
Whatever the scripting language, to be installable in TL in the first
place, a couple of requirements must be met:
- The upload to CTAN must contain the runnable script itself, or
something from which the script can be easily derived (e.g., a .dtx
file). For example, it should not be required to run a setup.py
for Python packages, either by the TL maintainers or (completely out of
the question) by TL users.
- To repeat what's stated above, the script must be named reasonably
uniquely. Scripts, unlike TeX files, will typically end up getting
installed in OS-wide binary directories, and thus must be unique across
the entire operating system world, not just the TeX world. Three
character names are not going to work; four character names are
borderline but may be acceptable if they are sufficiently obscure; more
descriptive names are preferred to abbreviations of random phrases.
- Also to reiterate the above, any auxiliary files
should contain the package name as a prefix in the filename; e.g.,
myscript-subs.pl. Ambiguous names are the bane of our TeX world
and must be avoided.
In addition, again independent of the scripting language, certain
conventions should be followed for the new script to be usable. We do
not rigorously check these requirements and won't refuse to install a
script that does not follow them, but failing to do will cause trouble
- The first line should use
#!/usr/bin/env name, rather than hardwiring any
path to the interpreter.
- In general, whether the executable is compiled or a script, it must
be self-locating at runtime. That is, it must be able to find all its
support files elsewhere in the install tree, relative to its own
location. Otherwise, it cannot work in TeX Live, because TL can be
installed anywhere on a user's system. Usually, the user-level script
will be installed in texmf-dist/scripts/PKGNAME/, with any
auxiliary files needed at runtime also in that directory, with a symlink
in the bin/PLATFORM/* dirs for the users to execute. (Our
wrapper for Windows supports most languages other than shell scripts.)
- If your program needs to search for files, please use Kpathsea to find them, one way or another. If your
package is written in a scripting language and needs to search for
files, using the kpsewhich executable may be convenient.
Looking directly for files is one option; if (especially) the files are
not uniquely named, you can also get the location of the
texmf-dist tree with
kpsewhich -var-value TEXMFMAIN and find what you need
in your own code.
- Please make any executables do something reasonable with the
--version. (No need to
support other variants or other long options.) Again, see the GNU standards.
- Please write a Unix man page, however brief. The afm2tfm.1 man page may serve as a starting point, as it is short
but includes all the usual sections. Alternatively, GNU help2man can
convert your --help message to a man page, For Perl scripts, pod2man may be
Dependencies on other packages
In general, TL does not try to track package dependencies, since
there is no reliable way to detect dependencies automatically. (That
would mean installing packages during the TeX run, as MiKTeX does, and there are complications
with doing this in TL.)
However, if you as the package author wish to tell us about
dependencies, we will install them. We do not request this, and do not
particularly recommend it, but since people have asked us, we've defined
the following mechanism. Packages doing this must be uploaded to CTAN.
Provide a file named DEPENDS.txt (with that capitalization
and extension) at the top level of your CTAN upload (sibling to your
README file). A four-line example:
hard dep3 dep4
soft xedep # XeTeX only
The intent is for the file to be automatically processed. So its syntax
must adhere to the following:
- Whitespace is ASCII space (0x20) and tab (0x09).
- Lines are terminated with ASCII linefeed (0x0a) possibly preceded by
ASCII return (0x0d).
- Blank lines are ignored.
- Leading and trailing whitespace on a line are ignored.
- Multiple whitespace characters are the same as one.
- Comments begin with # and continue to the end of line.
- Each non-blank line therefore consists of one or more
- If the first word on a line is hard, soft, or
package, all subsequent words are the arguments.
- If a line has only one word, hard is assumed (first line of
- The arguments must be valid package names, as defined by CTAN. For
example, that means they consist of all lowercase ASCII letters a-z,
ASCII numbers 0-9, dash, underscore (very occasionally), and nothing
else. If this is different from the TL package name, use the CTAN
name anyway; we will convert, one way or another. If the package
does not exist in TL at all, the depends file will be ignored.
- The hard directive means the following package(s) are
always required. These will be converted into dependencies for
- The soft directive means the following package(s) may be
needed, but are not required. As in the example above, perhaps they
are only needed when running XeTeX (or some other specific engine).
These must be listed as soft because not every installation
wants or needs (for example) XeTeX. Similarly with packages that are
only conditionally required, e.g., if some option to your package is
specified. As far as tlmgr goes, soft dependencies are
currently ignored, but they may serve as useful documentation. Your
- The package directive must be followed by exactly one more
word, and that word is the package name for which any following
dependencies are applied. This is only useful in the extremely
unusual case of two or more packages being distributed from a single
CTAN directory; it's best to leave it out in the normal case.
- A DEPENDS.txt file is not required to have any directives.
An empty or comment-only file is valid, though meaningless :).
If experience shows that changes are necessary, we may extend the
syntax in the future, but don't expect to ever need to make an
If you have questions or suggestions about any of this, please email
$Date: 2020/07/22 22:52:04 $;