Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jiaojiaodubai/tpmgr

A modern LaTeX package management
https://github.com/jiaojiaodubai/tpmgr

cli-tool latex package-manager tex

Last synced: about 1 month ago
JSON representation

A modern LaTeX package management

Awesome Lists containing this project

README 

          
# tpmgr - Modern LaTeX Package Manager 🚀



*[中文说明](README_zh.md)*



A modern LaTeX package manager written in Rust. It provides project-level package isolation, installs missing packages automatically, supports configurable multi-step compile chains, and keeps your workspace clean with optional cleanup.



## ✨ Key Features



- 📁 Project-level management: Isolate LaTeX packages per project to avoid global bloat

- 📦 Automatic package detection: Detect missing packages and install them automatically

- 🔗 Compile chain support: Run tools in a specified order and reuse the same config across machines

- 🧹 Clean cleanup: Remove download leftovers, intermediate build files, and temporary env vars



## 📥 Installation



### Windows



#### Method 1: Remote install (recommended)



> Note: The following commands are for PowerShell and only apply to Windows 8 and later with built-in PowerShell.



```powershell

# Temporarily relax script execution policy (current process only)

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force



# One-click install latest version

iwr -useb https://raw.githubusercontent.com/jiaojiaodubai/tpmgr/master/install-remote.ps1 | iex



# Or download and run with options

curl -o install-remote.ps1 https://raw.githubusercontent.com/jiaojiaodubai/tpmgr/master/install-remote.ps1



# Run local installer script (policy may block scripts; relax policy in current process first)

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force

./install-remote.ps1 -InstallerType "inno"     # Use Inno Setup installer

./install-remote.ps1 -InstallerType "portable" # Use portable version

./install-remote.ps1 -Help                      # Show all options

```



#### Method 2: Manual download



1. Visit the [Releases](https://github.com/jiaojiaodubai/tpmgr/releases) page

2. Download one of:

   - `tpmgr-x.x.x-setup.exe` — Inno Setup installer

   - `tpmgr-x.x.x-portable.zip` — Portable version

3. Run the installer or extract the portable package

4. Restart your terminal to use `tpmgr`



### macOS



```bash

curl -L https://github.com/jiaojiaodubai/tpmgr/releases/latest/download/tpmgr-macos.tar.gz | tar xz

cd tpmgr-*-macos

./install.sh

```



### Linux



```bash

curl -L https://github.com/jiaojiaodubai/tpmgr/releases/latest/download/tpmgr-linux.tar.gz | tar xz

cd tpmgr-*-linux

./install.sh

```



### Uninstallation



**Windows:**



- Via “Settings > Apps & features” or “Control Panel > Programs and Features”



**Windows (portable):**



```powershell

./uninstall.bat

```



**Other platforms:**



```bash

cargo uninstall tpmgr

sudo rm /usr/local/bin/tpmgr || true

rm -f ~/.local/bin/tpmgr || true

```



## 🚀 Quick Start



### First run auto-configuration



On first run, tpmgr will:



- Detect your TeX Live installation path and save it to global config

- Probe CTAN mirrors and select the fastest for your network

- Persist these settings globally for future projects



### Initialize a new LaTeX project



```bash

tpmgr init my-paper

cd my-paper

```



### Install packages



```bash

# Install specific packages (project-level)

tpmgr install amsmath geometry hyperref



# Install specific packages globally

tpmgr install --global tikz pgfplots



# Scan current project and auto-install missing packages

tpmgr install



# Attempt compilation and auto-install missing packages from errors

tpmgr install --compile



# Scan only a specific file

tpmgr install --path main.tex

```



### Search



```bash

tpmgr search "math"

tpmgr search "graphics"

```



### List installed packages



```bash

tpmgr list          # project

tpmgr list --global # global

```



### Update packages



```bash

tpmgr update                 # all

tpmgr update amsmath geometry # selected

```



### Remove packages



```bash

# Project-level

tpmgr remove old-package



# Global

tpmgr remove --global old-package

```



### Info



```bash

tpmgr info tikz

```



### Clean cache



```bash

tpmgr clean

```



### Mirror management



```bash

tpmgr mirror list

tpmgr mirror use --auto

tpmgr mirror use "Mirror Name"

```



### Dependency analysis



```bash

tpmgr analyze

tpmgr analyze --path main.tex

tpmgr analyze --compile

tpmgr analyze --verbose

```



### Compilation



```bash

tpmgr compile

tpmgr compile --path main.tex

tpmgr compile --clean

tpmgr compile --verbose

tpmgr compile --path src/paper.tex --clean --verbose

```



tpmgr installs packages into the project's `packages/` directory. To ensure the engine can find them, set `TEXINPUTS` before compiling.



#### Use `tpmgr compile` (recommended)



You can invoke `tpmgr compile` directly from third-party tools:



1. Configure the compile steps in `tpmgr.toml`:



   ```toml

   [[project.compile.steps]]



   tool = "xelatex"  # or your preferred engine

   args = ["-interaction=nonstopmode", "${PROJECT_ROOT}/main.tex"]

   ```



2. Run a build with automatic package detection:



   ```bash

   tpmgr compile

   ```



In the example above, we used the `${PROJECT_ROOT}` magic variable, which is replaced with your project root so you can share the same configuration across machines. Magic variables you can use in the compile chain include:



- `${PROJECT_ROOT}`: Project root directory

- `${CURRENT_DIR}`: Current working directory

- `${HOME}`: User home directory



#### Manual TEXINPUTS setup



Windows (PowerShell):



```powershell

$env:TEXINPUTS = ".\packages\;$env:TEXINPUTS"

pdflatex main.tex

```



Linux/macOS (Bash):



```bash

export TEXINPUTS="./packages/:$TEXINPUTS"

pdflatex main.tex

```



### Configuration



```bash

tpmgr config show

tpmgr config show --global

tpmgr config set compile "xelatex -interaction=nonstopmode ${PROJECT_ROOT}/main.tex"

tpmgr config set install_global true

tpmgr config set --global texlive_path "/usr/local/texlive/2024"

tpmgr config get compile

tpmgr config list

tpmgr config reset

```



## ⚙️ Configuration File



The `tpmgr.toml` file in your project might look like:



```toml

[project]

name = "my-paper"

version = "0.1.0"

package_dir = "packages"



[project.compile]

auto_clean = true



clean_patterns = [

    "*.aux",

    "*.log",

    "*.out",

    "*.toc",

    "*.lot",

    "*.lof",

    "*.nav",

    "*.snm",

    "*.vrb",

    "*.bbl",

    "*.blg",

    "*.idx",

    "*.ind",

    "*.ilg",

    "*.glo",

    "*.gls",

    "*.ist",

    "*.fls",

    "*.fdb_latexmk",

    "*.synctex.gz",

    "*.synctex(busy)",

    "*.pdfsync",

    "*.figlist",

    "*.makefile",

    "*.figlist.bak",

    "*.makefile.bak",

    "*.thm",

    "*.pyg",

    "*.auxlock",

    "*.bcf",

    "*.run.xml",

    "src/**/*.aux",

    "build/*.tmp"

]



[[project.compile.steps]]

tool = "pdflatex"

args = ["-interaction=nonstopmode", "${PROJECT_ROOT}/main.tex"]



[[project.compile.steps]]

tool = "bibtex"

args = ["${PROJECT_ROOT}/main.aux"]



[[project.compile.steps]]

tool = "pdflatex"

args = ["-interaction=nonstopmode", "${PROJECT_ROOT}/main.tex"]



[dependencies]

amsmath = "2.17"

geometry = "5.9"



[[repositories]]

name = "ctan"

url = "https://ctan.org/"

priority = 1



[[repositories]]

name = "texlive"

url = "https://mirror.ctan.org/systems/texlive/tlnet/"

priority = 2

```



## 📋 Commands Reference



### `tpmgr init [NAME]`



Initialize a new LaTeX project with package management. If `NAME` is not provided, the current directory is treated as the project root.



### `tpmgr install [PACKAGES]...`



Install one or more packages. If none specified, tpmgr detects dependencies and installs missing ones. Project-level by default; set `tpmgr config set install_global = true` to make global installation the default.



- `--global, -g`: Install globally

- `--path, -p`: Add dependencies only for the specified file

- `--compile, -c`: Use compilation mode to detect missing packages



### `tpmgr remove ...`



Remove one or more (project-level) packages. If none specified, removes all project-level packages.



- `--global, -g`: Remove globally



### `tpmgr update [PACKAGES]...`



Update one or more packages. If none specified, updates all packages.



### `tpmgr list`



List installed packages (current project).



- `--global, -g`: List global packages



### `tpmgr search `



Search for packages matching the query.



### `tpmgr info `



Show detailed information about a package.



### `tpmgr analyze [PATH]`



Analyze TeX file dependencies.



- `--path, -p`: TeX file or project directory

- `--verbose, -v`: Show detailed dependency info

- `--compile, -c`: Use compilation mode to detect missing packages



### `tpmgr compile [PATH]`



Compile TeX files according to the configured compile chain.



- `--path, -p`: TeX file or project directory

- `--clean, -c`: Clean intermediate files after compilation

- `--verbose, -v`: Show detailed compilation output



### `tpmgr config `



Configuration management.



- `show`: Display current configuration

  - `--global, -g`: Only show global configuration

- `set  `: Set configuration value

  - `--global, -g`: Set global configuration (applies to new projects)

- `get `: Get configuration value

  - `--global, -g`: Only read from global configuration

- `list`: List all configuration keys

  - `--global, -g`: Only show global configuration keys

- `reset`: Reset configuration to defaults

  - `--global, -g`: Only reset global configuration



### `tpmgr mirror `



Mirror management.



- `list`: List available mirrors

- `use `: Choose a mirror by name

- `use --auto`: Auto-select the fastest mirror



## 🤝 Contributing



Contributions are welcome! Please open a Pull Request.



For development and build instructions, see `docs/DEVELOPER.md`.



## 📄 License



MIT License — see [LICENSE](LICENSE).