PILF: Package Installation Log Format

The main purpose of this format is to let inventory tools reliably remind system administrators about packages they explicitly installed.

Current package-manager databases and logs are not enough for this. Some package managers do not retain useful transaction history; some rotate or delete logs; some expose install timestamps but not a durable selection class such as "this package was requested by an administrator" versus "this package was pulled in as a dependency". The transaction log described here is intended to be small, append-only, durable, and implementable by all package managers.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

The important distinctions are:

An inventory program can then answer this question directly: which currently installed packages did an administrator explicitly request, excluding base packages unless they were later explicitly manual?

Everything else in this specification is in support of that operation.

The log MUST be JSON Lines: UTF-8 text, one complete JSON object per line. This keeps the format append-friendly, streamable, recoverable after partial writes, and easy to inspect with ordinary tools.

A package manager may keep one or more journals under persistent state. System-scope journals MUST live at:

Recommended user-scope journals SHOULD live at:

The directory is deliberately under persistent state, not an ordinary log directory such as /var/log, because these records are package database provenance, not disposable diagnostics.

Best practice is to have only a single file representing the entire timeline of transactions recorded by possibly multiple package managers. In that case package managers MUST write-lock appends for atomicity. The preferred name for the single timeline is "journal.jsonl".

When permissions issues make a shared journal impossible, package managers MAY create multiple journal files names in any convenient way. Filenames SHOULD NOT be semantically loaded; records should remain self-describing when journals are concatenated, exported, moved, or analyzed outside their original path.

Each package-state line MUST describe a committed package-manager state change. Managers MUST NOT write records for planned actions that did not change package state, failed package operations that left package state unchanged, or ordinary diagnostic events. If a transaction partially succeeds, the manager MUST write records only for packages whose state actually changed. If a rollback changes package state, the manager MUST write records describing the resulting state changes, not a failure event.

Each package-state line should be independently useful even if transaction begin or end records are missing. This section specifies package-state records; adding other record types later would be a backward-incompatible shape change requiring a new required field.

Example package record:

There is no explicit schema-version field. Consumers recognize records by their shape: the required fields present, the types of values needed to interpret them, and the required-field values they understand.

Consumers MUST ignore records whose shapes they do not recognize. This includes records with missing required fields, unexpected value types, or required-field values the consumer does not understand. Consumers MUST NOT reject a journal merely because it contains unknown record shapes or extra fields. Consumers SHOULD ignore unknown optional fields in otherwise recognized records.

Each backward-incompatible change MUST be marked by either adding a new required field or introducing a new value for an existing required field, such as operation, selection, or reason. Adding a required record field to distinguish package records from other record types would be one example of such a shape change. This makes old consumers skip records they cannot safely interpret rather than misreading them.

The selection field describes current install intent after the operation. It is a state classification, not the reason this transaction touched the package.

The reason field should use a small shared vocabulary:

The format needs a first-class baseline transaction. During OS installation, image creation, package-manager bootstrap, or first profile creation, the manager SHOULD emit package records with operation set to bootstrap, reason set to base, and selection set to base.

Example baseline package record:

If an administrator later explicitly requests a base package, the manager SHOULD emit a mark record or a no-op request record with selection set to manual. This allows inventory tools to include the package as an intentional administrator selection even though it originated in the base system.

The first record below is an explicit administrator request. The second is a dependency installed to satisfy that request.

An inventory tool should replay records independently for each tuple of scope and package identity.

These rules intentionally make the current selection value authoritative. A package can move from auto to manual, manual to auto, base to manual, or manual to removed without requiring consumers to infer intent from old command lines.