Manual Installation Of Latex Packages Explained
What are LaTeX Packages and Why Install Manually?
LaTeX packages are collections of code, documentation, font files, and other resources that extend the capabilities of the LaTeX typesetting system. Packages allow you to add new functionality like specialized fonts, graphics, bibliographies, and scientific features. There are thousands of free packages available on the Comprehensive TeX Archive Network (CTAN).
Most LaTeX distributions come with a package manager that automatically downloads and installs packages from CTAN mirrors. However, there are some reasons why you may need to manually download and install LaTeX packages instead:
- Installing bleeding edge package versions before they are available in repositories
- Adding packages not available in distribution repositories
- Customizing package installation locations
- Developing and testing local packages
- Reducing distribution bloat by only installing needed packages
- Enhancing understanding of how LaTeX and packages work
Locating and Downloading Packages
The comprehensive TeX Archive Network (CTAN) hosts thousands of free LaTeX packages contributed by developers from around the world. Packages are categorized by topic area making it easy to locate relevant packages. The main CTAN site is located at https://ctan.org.
There are two main methods to download packages from CTAN:
- Navigate to the package directory on CTAN and download zipped package files manually.
- Use the search box to find packages and click links to go to the package site and download.
Make sure to take note of package names and versions for installation. Depending on connectivity, downloading from a geographically closer CTAN mirror can sometimes improve download speeds.
Package Installation Location
Unlike applications in operating systems, LaTeX packages do not have a single standard installation location. However, there are some typical conventions on where to install LaTeX packages:
- Local texmf tree - Create a custom local texmf tree to store user-installed packages separated from distribution files.
- System texmf tree - Install packages into the default system texmf tree, requires root/admin permissions.
- User texmf tree - Install packages in the user texmf tree located in home folders, good for test installs.
Creating a dedicated local texmf tree offers the most control and separation from other distribution files:
- Create a top-level folder like ~/texmf for the local tree root directory.
- Under this, make sub-folders like tex, doc, fonts, etc to match standard TDS structure.
- Edit tex config file to add local tree root to the TEXINPUTS path.
This custom local texmf tree will now be the installation location for manually installed packages.
Unpacking and Installing a Package
Once the package source files have been downloaded from CTAN, it is necessary to unpack and install the files into the designated texmf folder structure:
- Unzip the .zip archive containing the package source files.
- Browse the extracted files and subfolders to identify type (tex, cls,sty, fonts etc).
- Copy relevant files and folders to matching directories in target texmf tree.
- Delete downloaded zip archive and leftover extracted files.
Some key points when installing package files:
- Maintain folder structures within texmf tree.
- Install documentation PDFs and text files into doc folder.
- Place font files into texmf fonts folder.
- Copy license and readme files if available.
Repeat this sequence for any files from other required packages. Consistently organizing files helps avoid issues down the line.
Updating the File Database
The LaTeX system maintains a file index database to speed up locating resources. After installing new files manually, it is necessary to update the file index database.
From command line, run mktexlsr tool to update database:
mktexlsr /path/to/texmf/tree
This scans all files in the texmf tree to build a new evaporate database. An alternative is to directly delete the old ls-R file at root folder to force rebuild on next LaTeX compile.
It is also good practice to clear the file name cache after updating the system file database. Delete or move old fname.tex files inside texmf to refresh file lookups.
Verifying the Installation
After completing the package installation process, it is critical to test that you can correctly compile documents using the manually installed files.
- Create a sample LaTeX test file making use of your newly installed package.
- Compile LaTeX document multiple times to check for errors.
- Review compiler log for warnings about missing files or incorrect file paths.
- Confirm that expected package-related output is generated.
- Test functionality across different LaTeX engines like pdfTeX vs XeLaTeX.
During testing, pay attention to package version mismatches, path configuration issues, and file access permissions. Identify and address any such errors at this stage before proceeding for full usage.
Troubleshooting Issues
Some common issues faced when manually installing LaTeX packages include:
- File permission errors - Verify texmf folders have read and execute access.
- Missing package files - Check paths matched system root file locations.
- Version conflicts - Remove old copies of packages before install.
- Path configuration - Confirm environment variables refer to texmf folders.
- Database not updated - Run mktexlsr command on texmf tree.
Carrying out test compiles with different LaTeX engines can help identify and debug file access and path problems. Fix any directory permission issues identified during tests.
Summary
Manually downloading and installing LaTeX packages enables full customization and control compared to package managers. Key steps include:
- Identify needed packages on CTAN and download source files.
- Create local texmf folder structure for custom install location.
- Unpack and copy package files into relevant texmf folders.
- Update the file database using mktexlsr tool.
- Verify installations are working by test compiling documents.
Learning how packages integrate with the lower LaTeX system also builds useful troubleshooting knowledge. Overall, manual installation process helps optimize, trim down LaTeX distributions with only needed packages.