Installation¶

Fledge is a Python 3.11+ command-line tool. Building a paper (check and prepare) also needs TeX and Poppler; see Tools.

System	Route
macOS	The installer, which also sets up TeX and Poppler, or pipx or uv if you have them
Linux	pipx or uv, plus the Linux packages
Windows	WSL 2 with the Linux route

macOS installer¶

From the source checkout or an extracted source distribution, preview the plan and then install:

bash install.sh --dry-run
bash install.sh

The installer reuses tools you already have, shows its plan and asks before changing anything. It supplies Python 3.11+, latexmk, pdfLaTeX, BibTeX and Poppler as needed. If TeX is absent, the plan includes MacTeX without GUI apps (mactex-no-gui), a multi-gigabyte installation that can require administrator access. A conflicting partial TeX installation stops with advice instead of being replaced. Homebrew is needed only when tools are missing; the installer does not install Homebrew itself.

Fledge goes into ~/.local/share/fledge, and the launcher is ~/.local/bin/fledge. The installer refuses an existing prefix or launcher, including a symlink, and edits no shell files. If ~/.local/bin is not on your PATH, type ~/.local/bin/fledge wherever these pages show fledge. The launcher’s own PATH contains only the detected tool directories, fallback directories and system directories, so a virtual environment active in your shell does not leak into builds.

Option	Purpose
`--dry-run`	Preview; make no changes
`--yes`	Accept the displayed plan without a prompt
`--with-optional`	Also install missing `qpdf`, MuPDF tools and `tex-fmt`
`--prefix DIR --bin-dir DIR`	Choose installation and launcher directories
`--uninstall`	Remove the installation directory and launcher; works with `--dry-run` and `--yes`

Upgrade or uninstall¶

bash install.sh --uninstall --dry-run
bash install.sh --uninstall

Use the same --prefix and --bin-dir as for the installation. Uninstalling removes the prefix and the launcher, and only when the installer wrote that launcher for that prefix; otherwise nothing is removed. It refuses a symlinked prefix or one containing your home directory, and it leaves Homebrew, TeX, Poppler, shell files and your projects untouched. To upgrade, uninstall, then run the installer from the newer source.

Install with pipx or uv¶

Fledge is published on PyPI as fledge-latex. Install it into its own environment with either tool:

pipx install fledge-latex
# or
uv tool install fledge-latex
fledge --version

This installs the fledge command, and latex-prep for older scripts. It does not install TeX or Poppler; add them as described under Tools, and for Linux and Windows below. The command finds them through your shell’s PATH, unlike the macOS installer’s launcher, which saves the tool directories it detected. To upgrade or remove it, use pipx upgrade fledge-latex or uv tool upgrade fledge-latex, and pipx uninstall fledge-latex or uv tool uninstall fledge-latex.

Warning

Install fledge-latex, not fledge. The PyPI package named fledge is an unrelated project, so pip install fledge does not install this tool.

Manual installation from source¶

Use Python 3.11+ and install the external tools yourself:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
fledge --help

For a wheel, use python -m pip install /path/to/package.whl. Installation downloads Click and Rich unless local copies are available. The wheel contains the CLI; the source archive also includes the installer, docs, examples, tests and the agent skill.

Builds run in a sandbox: sandbox-exec on macOS, or Bubblewrap with working user namespaces on Linux. Windows has no build sandbox. See limitations for what has been tested where.

Linux¶

Fledge’s Linux sandbox has passed controlled-command tests only; it has not yet been validated on a live Linux host. On Debian or Ubuntu, the intended package set, which matches Fledge’s Linux test job, is:

sudo apt-get install bubblewrap latexmk biber poppler-utils \
  texlive-latex-base texlive-latex-recommended texlive-fonts-recommended \
  texlive-bibtex-extra

Add texlive-xetex or texlive-luatex for those engines, and the TeX Live packages your paper needs. tex-fmt is not packaged by Ubuntu; to use it, put a release binary in a system directory such as /usr/local/bin.

Fledge refuses tools installed in your home directory or in the project, so use distribution packages or another installation under /usr.

Ubuntu 24.04 can block unprivileged user namespaces with AppArmor (kernel.apparmor_restrict_unprivileged_userns=1), and Bubblewrap needs them. If the sandbox cannot start, Fledge blocks the build and never falls back to running unsandboxed. Allowing user namespaces is a security decision for your host: relax that setting, or add an AppArmor profile that permits bwrap. Fledge’s own Linux test job sets it to 0 only on its disposable runner.

Windows¶

Native Windows has no build sandbox, so check and prepare cannot build there; inspect and bib check need only Python. To build on Windows, use WSL 2 with a Linux distribution such as Ubuntu and follow the Linux instructions inside it. The same caveat applies: that route is not yet validated on a live host.

Tools¶

Operation	Tools
`inspect`, `bib check`	Python package only
`check`, `prepare`	`latexmk`, the selected TeX engine and packages, the bibliography backend (BibTeX or Biber), plus Poppler
PDF analysis and comparison	`pdfinfo`, `pdftotext`, `pdftoppm`, `pdffonts`, `pdfdetach`, `pdfimages`; `pdftohtml` for text geometry
Formatting and optional PDF checks	`tex-fmt`; `qpdf` and MuPDF’s `mutool`

A tool is needed only for the checks that use it. When a configured check’s tool is missing, that check is reported as incomplete rather than passed. Fledge never installs tools during a run.

Migrating from latex-prep¶

Fledge was previously named latex-prep. Existing setups keep working:

The fledge-latex distribution also installs a latex-prep command. The macOS installer exposes only fledge.
Configuration files named .latex-prep.toml and latex-prep.toml, and the [tool.latex-prep] table in pyproject.toml, are still read. In one directory the order is .fledge.toml, fledge.toml, .latex-prep.toml, latex-prep.toml and then pyproject.toml, so a leftover latex-prep.toml shadows a [tool.fledge] table beside it (see discovery and precedence). A pyproject.toml with both [tool.fledge] and [tool.latex-prep] is an error.
Formatter-off markers with the latex-prep prefix are still accepted.
Installations under the former name are left untouched by the installer.
For development, LATEX_PREP_RUN_INTEGRATION=1 and LATEXPREP_RUN_SANDBOX_TESTS=1 still enable the live tests.
Do not install the former latex-preparation distribution next to fledge-latex: both provide the latexprep module. Use a fresh Python environment, or remove it with python -m pip uninstall latex-preparation.
Before this package was published, installations from a source checkout were registered as fledge. Remove such an installation with python -m pip uninstall fledge before installing fledge-latex into the same environment. The fledge package on PyPI is an unrelated project.