# Package versions and the lock file

Read the package versions, sources, and warnings recorded in lock.json.

Source: https://debark.dev/docs/concepts/lockfile

---
Every bundle includes `lock.json`, a record of the packages selected during the build.
The installer uses it to request exact versions from the bundle.

You normally don’t need to read or edit JSON. Start with the summary:

```bash
debark inspect ./bundle
```

Inspection reads the bundle’s records; it does not verify them. For a bundle you received from
someone else, [verify it](/docs/trust/verifying) before relying on its contents.

## What each entry records

| Field                     | Meaning                                                               |
| ------------------------- | --------------------------------------------------------------------- |
| `name`, `version`, `arch` | The selected binary package and version                               |
| `source_package`          | The source package used to build it, when known                       |
| `filename`                | The .deb file’s path inside the bundle                                |
| `size`, `sha256`          | File size and checksum                                                |
| `origin`                  | Where the package came from, including archive details when available |
| `reason`                  | Why it was included, such as a direct request or a dependency         |
| `publisher_verification`  | What was checked about the package’s source                           |
| `flags`                   | Package attributes that may need attention                            |

For example, `reason: dependency-of:jq` identifies a package included to satisfy the request
for `jq`. Field names and allowed values are defined in the
[bundle format reference](/docs/reference/bundle-format).

## How far the publisher was checked

| Value            | What it tells you                                                          |
| ---------------- | -------------------------------------------------------------------------- |
| `apt-signed`     | The package was checked through a signed apt archive                       |
| `url-unverified` | A URL or local file was supplied without additional publisher verification |
| `user-digest`    | The file matched a checksum you supplied                                   |
| `user-signature` | The format records verification with a supplied signature                  |

HTTPS protects the download connection, but doesn’t establish who built the package. For URL
inputs, `--digest URL=SHA256` checks against an expected checksum. Obtain that checksum from a
source you trust, such as the vendor’s published release checksums.

With `default_severity: deny`, the policy setting `require_signed_publisher` rejects
`url-unverified`. It accepts `user-digest`, so it does not require every input to have a digital signature.
See [vendor packages](/docs/guides/vendor-debs).

## Package flags

Flags can identify restricted archive components, packages that may use the network during
installation, Snap installers, or DKMS drivers. They help you decide what to check before
transferring the bundle.

Use [doctor](/docs/guides/policy-and-doctor) for a readable report. Missing flags don’t prove
that a package has no offline installation problems.

## How install reads the lock

Preview the result on the offline machine:

```bash
debark install ./bundle --key operator.pub --status
```

A normal install applies the lock’s requested package set. `--upgrade` adds the separately
recorded upgrade set. The installer doesn’t use unrelated newer versions from the machine’s
internet sources.

Files left in the package pool after a rebuild may not be part of the current plan or apt index.
Their presence alone does not make them installation candidates.

## Keep the lock with the bundle

The lock is covered by the manifest. Editing it after signing causes verification to fail.
Change the package request and rebuild instead.

A lock file records selected versions, but it doesn’t preserve packages on remote servers.
Keep the bundle or cached .deb files if you need those versions later.

<NextSteps
  items={[
    {
      title: 'Install a bundle',
      href: '/docs/operate/installing',
      description: 'Preview and apply the selected package versions.',
    },
    {
      title: 'Bundle format',
      href: '/docs/reference/bundle-format',
      description: 'Look up files and schemas in a bundle.',
    },
  ]}
/>