Skip to content

Migration from upstream

Jump to bottom
YadeWira edited this page Jun 10, 2026 · 2 revisions

Migration from upstream packjpg/packJPG

If you've been using the original packjpg/packJPG by Matthias Stirner (last release v2.5k) and are switching to this fork (YadeWira/packJPG, current LTS v4.0e), here's what changes and how to handle existing archives.

TL;DR

  • Existing v2.5 / v3.x .pjg archives: decode them with the upstream binary or with the v3.1d build of this fork, re-encode with v4.0e. Direct decode of v2.x or v3.x by v4.0e is not supported.
  • CLI: mostly compatible. New flags (-th, -sfth, -fs, -od, etc.) are additive; existing scripts keep working.
  • License: upstream is GPL-3.0; this fork is LGPL-3.0 (more permissive for static linking).
  • Format: v4.0e uses version byte 0x28 (= 40) plus sub-marker 0x02. The upstream's last format used a different version byte and won't decode under v4.0e.

How to handle existing .pjg archives

The format break between v3.1d and v4.0 was intentional — v4.0 introduced cross-component DC and the new sub-marker scheme that wouldn't fit cleanly into the older header. To migrate:

Option 1 — Two-binary workflow (recommended for big archives)

Keep an old binary on hand for decode, use v4.0e for encode going forward:

# Decode legacy archive with old binary
old_packJPG x legacy.pjg
# Re-encode with new binary
packJPG a legacy.jpg
rm legacy.jpg legacy_old.pjg

The v3.1d build of this fork is available at the v3.1d release and decodes both v2.5x and v3.x archives.

Option 2 — Bulk migration script (sketch)

#!/bin/sh
# Migrate a directory of legacy .pjg files to v4.0e format
for old in *.pjg; do
    base="${old%.pjg}"
    /path/to/old_packJPG x "$old"        # → $base.jpg
    /path/to/new_packJPG a -o "$base.jpg"   # → $base.pjg (v4.0e format)
    rm "$base.jpg"
done

Option 3 — Don't migrate

Old archives keep working under the old binary. There's no functional advantage to forcing them into the new format unless you want a single-binary deployment.

CLI compatibility

Most upstream commands work as-is.

Upstream behaviour This fork
packJPG file.jpg (auto-detect) Use packJPG mix file.jpg for the same auto-detect; or packJPG a file.jpg to force compress, packJPG x to force decompress. New default requires explicit subcommand.
-v0 / -v1 / -v2 Same.
-d (discard meta) Same.
-o (overwrite) Same.
-p (proceed on warnings) Same.
-ver (verify) Same.

New flags introduced after the fork

  • -th<N> — multi-file batch threading (run N files in parallel).
  • -sfth — single-file three-cores threading (parallelize one file's pre-pack stages).
  • -r — recurse into subdirectories.
  • -fs — preserve source folder structure under -od when used with -r (added in v4.0c).
  • -od<DIR> — write output to a specific directory.
  • -dry — dry run, don't write any files.
  • -module — machine-friendly output (OK/ERROR + time only).
  • --no-color — disable ANSI color (also respects NO_COLOR env var).

License changes

  • Upstream (packjpg/packJPG): GPL-3.0. Linking restrictions apply for proprietary applications.
  • This fork (YadeWira/packJPG): LGPL-3.0. Static and dynamic linking permitted in proprietary applications subject to LGPL terms (essentially: users must be able to relink with a modified packJPG).

If your use case requires a more permissive license, this fork is friendlier. If you need the original GPL terms specifically, use upstream.

What this fork added

A non-exhaustive list of changes since the upstream packJPG v2.5k:

  • Re-licensing to LGPL-3.0.
  • C++17 modernization (std::filesystem, std::thread, std::optional, etc.).
  • Thread safety throughout (model state, I/O, error reporting).
  • SoF1 (extended sequential) and SoF2 (progressive) JPEG support.
  • Native multi-threading: -th<N> for batch, -sfth for single-file pre-pack.
  • New CLI subcommands (a, x, mix, list, stats).
  • Cross-component DC prediction (Cb/Cr use Y's bit-length as extra context).
  • Diagonal DC neighbour context (4-bucket variance from |L-T| + |T-TR|).
  • make pgo / make native build targets for profile-guided / max-perf builds.
  • Linux package builds: .deb, .rpm, .tar.gz.
  • Windows legacy x86/x64 builds (XP / Vista / 7 / 8 compatible).

Reporting issues

If you find a bug specific to this fork, file it on this repo's Issues tab, not on the upstream — they aren't tracking the fork's changes.

If the bug also reproduces on upstream v2.5k, mention that in the report so we know it's pre-existing.

Clone this wiki locally