# info > APT_PREFERENCES

---
type: CommandReference
command: apt_preferences
mode: man
section: 5
source: man-pages
---

## Quick Reference

- `Package: perl; Pin: version 5.20*; Pin-Priority: 1001` — Pin perl to version 5.20*
- `Package: *; Pin: origin ""; Pin-Priority: 999` — Pin all packages from local site
- `Package: *; Pin: release a=stable; Pin-Priority: 900` — Prefer stable distribution
- `Package: *; Pin: release a=unstable; Pin-Priority: 50` — Lower priority for unstable
- `Package: *; Pin: release n=bookworm; Pin-Priority: 900` — Pin to codename bookworm
- `Package: *; Pin: release a=stable, v=11; Pin-Priority: 500` — Pin to stable version 11
- `Package: src:apt; Pin: version 2.4.14; Pin-Priority: 990` — Pin all binaries from source apt
- `Package: gnome* /kde/; Pin: release a=experimental; Pin-Priority: 500` — Pin by glob and regex

## Name

Preference control file for APT

## Synopsis

The APT preferences file `/etc/apt/preferences` and fragment files in `/etc/apt/preferences.d/` control which versions of packages are selected for installation. APT assigns default priorities; the preferences file overrides them.

## Description

The file consists of one or more records separated by blank lines. Each record has three fields: `Package:`, `Pin:`, and `Pin-Priority:`, with an optional `Explanation:` comment line.

`Package:` specifies the package(s) to pin. Can be a binary package name, source package name (prefix `src:`), a glob pattern (e.g., `gnome*`), or a POSIX extended regular expression (e.g., `/kde/`). Multiple entries separated by whitespace. Use `:any` suffix to match all architectures, or `:arch` to limit to a specific architecture.

`Pin:` specifies the target for pinning. The value can be:
- `version <version>` — pin to a specific version or version range (e.g., `5.20*`, `2.4.14`)
- `release <conditions>` — pin to a release. Conditions are key=value pairs separated by commas, using single-letter abbreviations: `a` for archive/suite, `n` for codename, `v` for version, `c` for component, `o` for origin, `l` for label. Multiple conditions must all match; duplicate conditions only check the last.
- `origin "<hostname>"` — pin to a specific site (e.g., `"ftp.de.debian.org"`). Note: this matches the hostname, not the `Origin:` tag in Release files.

`Pin-Priority:` is an integer. Interpretation:
- P >= 1000: allow downgrade
- 990 <= P < 1000: install even if not from target release, unless installed version is newer
- 500 <= P < 990: install unless a version from target release or installed version is newer
- 100 <= P < 500: install unless a version from another distribution or installed version is newer
- 0 < P < 100: install only if no installed version
- P < 0: prevent installation
- P = 0: undefined, do not use

Default priorities (without preferences file): installed version gets 100, uninstalled versions get 500 (or 990 if from target release, 1 if NotAutomatic, 100 if NotAutomatic+ButAutomaticUpgrades). Phased updates use a field `Phased-Update-Percentage` to pin to 1 if not eligible.

Files in `/etc/apt/preferences.d/` must have no extension or `.pref` and contain only alphanumeric, hyphen, underscore, period characters. Otherwise APT may ignore them (silently if the pattern matches `Dir::Ignore-Files-Silently`).

## Options

The configuration file format uses the following fields:

- `Package:` — Package(s) to pin. Supports globs, regular expressions, source prefix `src:`, architecture suffixes `:native`, `:any`, `:arch`.
- `Pin:` — Target specification. One of:
  - `version <version>` — version string, may include globs
  - `release <conditions>` — release conditions using key=value pairs (see above)
  - `origin <hostname>` — hostname of the source
- `Pin-Priority:` — Integer priority value.
- `Explanation:` — Optional comment line(s).

## Examples

**Tracking Stable:**

text
Package: *
Pin: release a=stable
Pin-Priority: 900

Package: *
Pin: release o=Debian
Pin-Priority: -10
**Tracking Testing or Unstable:**

text
Package: *
Pin: release a=testing
Pin-Priority: 900

Package: *
Pin: release a=unstable
Pin-Priority: 800

Package: *
Pin: release o=Debian
Pin-Priority: -10
**Tracking a codename release:**

text
Package: *
Pin: release n=bookworm
Pin-Priority: 900

Package: *
Pin: release n=sid
Pin-Priority: 800

Package: *
Pin: release o=Debian
Pin-Priority: -10
## See Also

- [apt-get(8)](http://localhost/phpMan.php/man/apt-get/8/markdown)
- [apt-cache(8)](http://localhost/phpMan.php/man/apt-cache/8/markdown)
- [apt.conf(5)](http://localhost/phpMan.php/man/apt.conf/5/markdown)
- [sources.list(5)](http://localhost/phpMan.php/man/sources.list/5/markdown)

## Files

- `/etc/apt/preferences` — Main preferences file. Configuration item: `Dir::Etc::Preferences`.
- `/etc/apt/preferences.d/` — Fragment directory. Configuration item: `Dir::Etc::PreferencesParts`.

## Exit Codes

Not documented.