Choose and Test a Pager with sensible-pager

Debian's sensible-pager is a decision-making wrapper, not a pager in its own right, and its fallback order trips people up. You will finish with a predictable way to send text through it, choose a preferred pager, and diagnose a fallback that did not run.

The examples use sensible-utils 0.0.22, installed here as /usr/bin/sensible-pager. Allow about ten minutes. You need a shell and a command that produces text. No root access is needed, and this guide does not edit shell startup files or system configuration. The command only chooses and starts a pager for the current invocation.

1. Check the installed command

Confirm which executable your shell will start and record the package version. These are ordinary, read-only checks:

$ command -v sensible-pager
/usr/bin/sensible-pager
$ dpkg-query -W -f='${Package} ${Version}\n' sensible-utils
sensible-utils 0.0.22

The installed manpage describes sensible-pager as a decision-making wrapper. It is not itself a full-screen pager. It tries suitable commands in an order controlled by the environment, then reports an error if none can be started.

Checkpoint: if command -v finds a different copy, use that copy's manpage and package version. Wrapper details can vary between Debian releases and local installations.

2. Understand the selection order

For each invocation, this Debian script considers $PAGER first, then $SENSIBLE_PAGER, then the commands pager and more. An empty variable is skipped. The first candidate that runs with an exit status other than 126 or 127 becomes the result of the wrapper.

The variables are command strings, not just fixed executable paths. The wrapper passes them to a shell with the input arguments appended. Treat them as trusted local configuration. Do not copy an untrusted value into PAGER or SENSIBLE_PAGER, because a value containing shell syntax can run a different command than the one you intended.

3. Run a harmless first test

Set PAGER=cat only for one command. This avoids an interactive screen and makes the selected candidate obvious from the output:

$ printf 'pager-check\n' | PAGER=cat SENSIBLE_PAGER= sensible-pager
pager-check

The assignment before sensible-pager affects this process only. It does not change your shell's future environment. cat reads the wrapper's standard input and writes it unchanged, so this test is useful in a terminal, a script, or a non-interactive job.

Checkpoint: verify the exit status when putting the command into a script:

$ printf 'pager-check\n' | PAGER=cat sensible-pager
pager-check
$ printf 'exit status: %s\n' "$?"
exit status: 0

Status 0 means the selected command returned 0. It does not mean that every pager is installed, or that a later command will display text in the same way.

4. Test the next fallback without changing files

To prove that the second environment variable can be reached, give PAGER a deliberately missing command and set SENSIBLE_PAGER to cat:

$ printf 'fallback-check\n' | PAGER=command-that-does-not-exist SENSIBLE_PAGER=cat sensible-pager
PAGER: 1: command-that-does-not-exist: not found
fallback-check
$ printf 'exit status: %s\n' "$?"
exit status: 0

The shell diagnostic is expected. The wrapper continues because the missing command produced status 127, then cat handled the input. The exact diagnostic prefix can vary with the shell, so check the final status and output rather than matching the whole error line in a brittle test.

Do not use a fake missing command as a permanent setting. Remove the one-command assignment, or correct the real value:

$ unset PAGER SENSIBLE_PAGER
$ printf 'default-candidate-check\n' | sensible-pager

Recovery: unset changes the current shell environment. It is reversible: close the shell, start a new one, or export the values you actually want again. If your shell startup files set either variable, inspect them before making a permanent edit.

5. Use a real pager for interactive output

For a terminal session, choose an installed pager explicitly. For example, if less is present:

$ command -v less
/usr/bin/less
$ PAGER=less sensible-pager /var/log/dpkg.log

The file path is only an example. Replace it with a readable text file on your machine. Press q to leave less. This reads the file; it does not modify it. If the file may contain secrets, do not paste its contents into a terminal recording, ticket or chat transcript.

When a program already invokes sensible-pager, pass the program's output through it rather than adding another pager around the result. Nested pagers are distracting and can make input appear to hang while each process waits for the other.

6. Diagnose a pager that does not appear

First check the variables and commands without changing anything:

$ printf 'PAGER=%s\nSENSIBLE_PAGER=%s\n' "$PAGER" "$SENSIBLE_PAGER"
$ command -v pager
$ command -v more

An empty command -v result means that candidate is not available through your current PATH. A variable can also name a command that exists but exits immediately, sends output elsewhere, or expects options you did not provide. Test the value with a harmless input and cat as shown earlier before blaming the wrapper.

The script skips a candidate that resolves back to sensible-pager. This recursion guard prevents a loop when, for example, a pager link or environment variable points back to the wrapper. It does not repair a broken pager installation. Set PAGER to a real pager such as less, or use cat for non-interactive output.

If every candidate is missing or recursive, the wrapper writes Couldn't find a pager! to standard error, suggests setting $PAGER, and exits with status 1. That is a configuration failure. Installing or changing packages requires your normal system-management process and may require elevated privileges; the checks and environment assignments in this guide do not.

Done means