{
    "mode": "man",
    "parameter": "apt_preferences",
    "section": "5",
    "url": "https://www.chedong.com/phpMan.php/man/apt_preferences/5/json",
    "generated": "2026-07-05T16:01:44Z",
    "sections": {
        "NAME": {
            "content": "aptpreferences - Preference control file for APT\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The APT preferences file /etc/apt/preferences and the fragment files in the\n/etc/apt/preferences.d/ folder can be used to control which versions of packages will be\nselected for installation.\n\nSeveral versions of a package may be available for installation when the sources.list(5) file\ncontains references to more than one distribution (for example, stable and testing). APT\nassigns a priority to each version that is available. Subject to dependency constraints,\napt-get selects the version with the highest priority for installation. The APT preferences\noverride the priorities that APT assigns to package versions by default, thus giving the user\ncontrol over which one is selected for installation.\n\nSeveral instances of the same version of a package may be available when the sources.list(5)\nfile contains references to more than one source. In this case apt-get downloads the instance\nlisted earliest in the sources.list(5) file. The APT preferences do not affect the choice of\ninstance, only the choice of version.\n\nPreferences are a strong power in the hands of a system administrator but they can become\nalso their biggest nightmare if used without care! APT will not question the preferences, so\nwrong settings can lead to uninstallable packages or wrong decisions while upgrading\npackages. Even more problems will arise if multiple distribution releases are mixed without a\ngood understanding of the following paragraphs. Packages included in a specific release\naren't tested in (and therefore don't always work as expected in) older or newer releases, or\ntogether with other packages from different releases. You have been warned.\n\nNote that the files in the /etc/apt/preferences.d directory are parsed in alphanumeric\nascending order and need to obey the following naming convention: The files have either no or\n\"pref\" as filename extension and only contain alphanumeric, hyphen (-), underscore () and\nperiod (.) characters. Otherwise APT will print a notice that it has ignored a file, unless\nthat file matches a pattern in the Dir::Ignore-Files-Silently configuration list - in which\ncase it will be silently ignored.\n",
            "subsections": [
                {
                    "name": "APT's Default Priority Assignments",
                    "content": "If there is no preferences file or if there is no entry in the file that applies to a\nparticular version then the priority assigned to that version is the priority of the\ndistribution to which that version belongs. It is possible to single out a distribution, \"the\ntarget release\", which receives a higher priority than other distributions do by default. The\ntarget release can be set on the apt-get command line or in the APT configuration file\n/etc/apt/apt.conf. Note that this has precedence over any general priority you set in the\n/etc/apt/preferences file described later, but not over specifically pinned packages. For\nexample,\n\napt-get install -t testing some-package\n\n\n\nAPT::Default-Release \"stable\";\n\nIf the target release has been specified then APT uses the following algorithm to set the\npriorities of the versions of a package. Assign:\n\npriority 1\nto the versions coming from archives which in their Release files are marked as\n\"NotAutomatic: yes\" but not as \"ButAutomaticUpgrades: yes\" like the Debian experimental\narchive, as well as versions that are not phased on this systems.\n\npriority 100\nto the version that is already installed (if any) and to the versions coming from\narchives which in their Release files are marked as \"NotAutomatic: yes\" and\n\"ButAutomaticUpgrades: yes\" like the Debian backports archive since squeeze-backports.\n\npriority 500\nto the versions that do not belong to the target release.\n\npriority 990\nto the versions that belong to the target release.\nThe highest of those priorities whose description matches the version is assigned to the\nversion.\n\nIf the target release has not been specified then APT simply assigns priority 100 to all\ninstalled package versions and priority 500 to all uninstalled package versions, except\nversions coming from archives which in their Release files are marked as \"NotAutomatic: yes\"\n- these versions get the priority 1 or priority 100 if it is additionally marked as\n\"ButAutomaticUpgrades: yes\".\n\nAPT then applies the following rules, listed in order of precedence, to determine which\nversion of a package to install.\n\n•   Never downgrade unless the priority of an available version exceeds 1000. (\"Downgrading\"\nis installing a less recent version of a package in place of a more recent version. Note\nthat none of APT's default priorities exceeds 1000; such high priorities can only be set\nin the preferences file. Note also that downgrading a package can be risky.)\n\n•   Install the highest priority version.\n\n•   If two or more versions have the same priority, install the most recent one (that is, the\none with the higher version number).\n\n•   If two or more versions have the same priority and version number but either the packages\ndiffer in some of their metadata or the --reinstall option is given, install the\nuninstalled one.\n\nIn a typical situation, the installed version of a package (priority 100) is not as recent as\none of the versions available from the sources listed in the sources.list(5) file (priority\n500 or 990). Then the package will be upgraded when apt-get install some-package or apt-get\nupgrade is executed.\n\nMore rarely, the installed version of a package is more recent than any of the other\navailable versions. The package will not be downgraded when apt-get install some-package or\napt-get upgrade is executed.\n\nSometimes the installed version of a package is more recent than the version belonging to the\ntarget release, but not as recent as a version belonging to some other distribution. Such a\npackage will indeed be upgraded when apt-get install some-package or apt-get upgrade is\nexecuted, because at least one of the available versions has a higher priority than the\ninstalled version.\n"
                },
                {
                    "name": "Phased Updates",
                    "content": "APT understands a field called Phased-Update-Percentage which can be used to control the\nrollout of a new version. It is an integer between 0 and 100.\n\nA system's eligibility to a phased update is determined by seeding random number generator\nwith the package source name, the version number, and /etc/machine-id, and then calculating\nan integer in the range [0, 100]. If this integer is larger than the\nPhased-Update-Percentage, the version is pinned to 1, and thus held back. Otherwise, normal\npolicy rules apply.\n\nIn case you have multiple systems that you want to receive the same set of updates, you can\nset APT::Machine-ID to a UUID such that they all phase the same, or set\nAPT::Get::Never-Include-Phased-Updates or APT::Get::Always-Include-Phased-Updates to true\nsuch that APT will never/always consider phased updates.\n"
                },
                {
                    "name": "The Effect of APT Preferences",
                    "content": "The APT preferences file allows the system administrator to control the assignment of\npriorities. The file consists of one or more multi-line records separated by blank lines.\nRecords can have one of two forms, a specific form and a general form.\n\n•   The specific form assigns a priority (a \"Pin-Priority\") to one or more specified packages\nwith a specified version or version range. For example, the following record assigns a\nhigh priority to all versions of the perl package whose version number begins with\n\"5.20\". Multiple packages can be separated by spaces.\n\nPackage: perl\nPin: version 5.20*\nPin-Priority: 1001\n\n•   The general form assigns a priority to all of the package versions in a given\ndistribution (that is, to all the versions of packages that are listed in a certain\nRelease file) or to all of the package versions coming from a particular Internet site,\nas identified by the site's fully qualified domain name.\n\nThis general-form entry in the APT preferences file applies only to groups of packages.\nFor example, the following record assigns a high priority to all package versions\navailable from the local site.\n\nPackage: *\nPin: origin \"\"\nPin-Priority: 999\n\nA note of caution: the keyword used here is \"origin\" which can be used to match a\nhostname. The following record will assign a high priority to all versions available from\nthe server identified by the hostname \"ftp.de.debian.org\"\n\nPackage: *\nPin: origin \"ftp.de.debian.org\"\nPin-Priority: 999\n\nThis should not be confused with the Origin of a distribution as specified in a Release\nfile. What follows the \"Origin:\" tag in a Release file is not an Internet address but an\nauthor or vendor name, such as \"Debian\" or \"Ximian\".\n\nThe following record assigns a low priority to all package versions belonging to any\ndistribution whose Archive name is \"unstable\".\n\nPackage: *\nPin: release a=unstable\nPin-Priority: 50\n\nThe following record assigns a high priority to all package versions belonging to any\ndistribution whose Codename is \"bookworm\".\n\nPackage: *\nPin: release n=bookworm\nPin-Priority: 900\n\nThe following record assigns a high priority to all package versions belonging to any\nrelease whose Archive name is \"stable\" and whose release Version number is \"11\".\n\nPackage: *\nPin: release a=stable, v=11\nPin-Priority: 500\n\nThe effect of the comma operator is similar to an \"and\" in logic: All conditions must be\nsatisfied for the pin to match. There is one exception: For any type of condition (such as\ntwo \"a\" conditions), only the last such condition is checked.\n"
                },
                {
                    "name": "Matching packages in the Package field",
                    "content": "The Package field specifies the package that a pinning priority is applied to. The field can\neither contain a binary package name, a source package name (prefixed with \"src:\"), a glob(7)\nexpression or a regular expression (surrounded by slashes). Multiple package names, glob(7)\nexpressions and regular expressions can be listed separated by whitespace in which case the\nrecord will match any of the matched packages.\n\nBy default, only packages of the native architecture are matched. To match binary packages of\nany architecture, add the :any suffix to the package name. You can also limit matching to a\nspecific architecture by appending the architecture name to the package name, separated by a\ncolon character.\n\nFor example, the following example uses a glob expression and a regular expression to assign\nthe priority 500 to all packages from experimental where the name starts with gnome (as a\nglob(7)-like expression) or contains the word kde (as a POSIX extended regular expression\nsurrounded by slashes).\n\nPackage: gnome* /kde/\nPin: release a=experimental\nPin-Priority: 500\n\nThe rule for those expressions is that they can occur anywhere where a string can occur.\nThus, the following pin assigns the priority 990 to all packages from a release starting with\nhirsute.\n\nPackage: *\nPin: release n=hirsute*\nPin-Priority: 990\n\nIf a regular expression occurs in a Package field, the behavior is the same as if this\nregular expression were replaced with a list of all package names it matches. It is undecided\nwhether this will change in the future; thus you should always list wild-card pins first, so\nlater specific pins override it. The pattern \"*\" in a Package field is not considered a\nglob(7) expression in itself.\n\nTo pin all binaries produced by the apt source package of this APT's version to 990, you can\ndo:\n\nPackage: src:apt\nPin: version 2.4.14\nPin-Priority: 990\n\nSource package pinning can be combined with regular expressions and glob patterns, and can\nalso take a binary architecture.\n\nFor example, let's pin all binaries for all architectures produced by any source package\ncontaining apt in its name to 990:\n\nPackage: src:*apt*:any\nPin: version *\nPin-Priority: 990\n\nThe :any suffix makes sure to select binary packages from any architecture. Without that\nsuffix, apt implicitly assumes the :native suffix which would only select packages from the\nnative architecture.\n"
                },
                {
                    "name": "How APT Interprets Priorities",
                    "content": "Priorities (P) assigned in the APT preferences file must be positive or negative integers.\nThey are interpreted as follows (roughly speaking):\n\nP >= 1000\ncauses a version to be installed even if this constitutes a downgrade of the package\n\n990 <= P < 1000\ncauses a version to be installed even if it does not come from the target release, unless\nthe installed version is more recent\n\n500 <= P < 990\ncauses a version to be installed unless there is a version available belonging to the\ntarget release or the installed version is more recent\n\n100 <= P < 500\ncauses a version to be installed unless there is a version available belonging to some\nother distribution or the installed version is more recent\n\n0 < P < 100\ncauses a version to be installed only if there is no installed version of the package\n\nP < 0\nprevents the version from being installed\n\nP = 0\nhas undefined behaviour, do not use it.\n\nThe first specific-form record matching an available package version determines the priority\nof the package version. Failing that, the priority of the package is defined as the maximum\nof all priorities defined by generic-form records matching the version. Records defined using\npatterns in the Pin field other than \"*\" are treated like specific-form records.\n\nFor example, suppose the APT preferences file contains the three records presented earlier:\n\nPackage: perl\nPin: version 5.20*\nPin-Priority: 1001\n\nPackage: *\nPin: origin \"\"\nPin-Priority: 999\n\nPackage: *\nPin: release unstable\nPin-Priority: 50\n\nThen:\n\n•   The most recent available version of the perl package will be installed, so long as that\nversion's version number begins with \"5.20\". If any 5.20* version of perl is available\nand the installed version is 5.24*, then perl will be downgraded.\n\n•   A version of any package other than perl that is available from the local system has\npriority over other versions, even versions belonging to the target release.\n\n•   A version of a package whose origin is not the local system but some other site listed in\nsources.list(5) and which belongs to an unstable distribution is only installed if it is\nselected for installation and no version of the package is already installed.\n\n"
                },
                {
                    "name": "Determination of Package Version and Distribution Properties",
                    "content": "The locations listed in the sources.list(5) file should provide Packages and Release files to\ndescribe the packages available at that location.\n\nThe Packages file is normally found in the directory .../dists/dist-name/component/arch: for\nexample, .../dists/stable/main/binary-i386/Packages. It consists of a series of multi-line\nrecords, one for each package available in that directory. Only two lines in each record are\nrelevant for setting APT priorities:\n\nthe Package: line\ngives the package name\n\nthe Version: line\ngives the version number for the named package\n\nThe Release file is normally found in the directory .../dists/dist-name: for example,\n.../dists/stable/Release, or .../dists/bullseye/Release. It consists of a single multi-line\nrecord which applies to all of the packages in the directory tree below its parent. Unlike\nthe Packages file, nearly all of the lines in a Release file are relevant for setting APT\npriorities:\n\nthe Archive: or Suite: line\nnames the archive to which all the packages in the directory tree belong. For example,\nthe line \"Archive: stable\" or \"Suite: stable\" specifies that all of the packages in the\ndirectory tree below the parent of the Release file are in a stable archive. Specifying\nthis value in the APT preferences file would require the line:\n\nPin: release a=stable\n\nthe Codename: line\nnames the codename to which all the packages in the directory tree belong. For example,\nthe line \"Codename: bookworm\" specifies that all of the packages in the directory tree\nbelow the parent of the Release file belong to a version named bookworm. Specifying this\nvalue in the APT preferences file would require the line:\n\nPin: release n=bookworm\n\nthe Version: line\nnames the release version. For example, the packages in the tree might belong to Debian\nrelease version 11. Note that there is normally no version number for the testing and\nunstable distributions because they have not been released yet. Specifying this in the\nAPT preferences file would require one of the following lines.\n\nPin: release v=11\nPin: release a=stable, v=11\nPin: release 11\n\nthe Component: line\nnames the licensing component associated with the packages in the directory tree of the\nRelease file. For example, the line \"Component: main\" specifies that all the packages in\nthe directory tree are from the main component, which entails that they are licensed\nunder terms listed in the Debian Free Software Guidelines. Specifying this component in\nthe APT preferences file would require the line:\n\nPin: release c=main\n\nthe Origin: line\nnames the originator of the packages in the directory tree of the Release file. Most\ncommonly, this is Debian. Specifying this origin in the APT preferences file would\nrequire the line:\n\nPin: release o=Debian\n\nthe Label: line\nnames the label of the packages in the directory tree of the Release file. Most commonly,\nthis is Debian. Specifying this label in the APT preferences file would require the line:\n\nPin: release l=Debian\n\nAll of the Packages and Release files retrieved from locations listed in the sources.list(5)\nfile are stored in the directory /var/lib/apt/lists, or in the file named by the variable\nDir::State::Lists in the apt.conf file. For example, the file\ndebian.lcs.mit.edudebiandistsunstablecontribbinary-i386Release contains the Release\nfile retrieved from the site debian.lcs.mit.edu for binary-i386 architecture files from the\ncontrib component of the unstable distribution.\n"
                },
                {
                    "name": "Optional Lines in an APT Preferences Record",
                    "content": "Each record in the APT preferences file can optionally begin with one or more lines beginning\nwith the word Explanation:. This provides a place for comments.\n"
                }
            ]
        },
        "EXAMPLES": {
            "content": "",
            "subsections": [
                {
                    "name": "Tracking Stable",
                    "content": "The following APT preferences file will cause APT to assign a priority higher than the\ndefault (500) to all package versions belonging to a stable distribution and a prohibitively\nlow priority to package versions belonging to other Debian distributions.\n\nExplanation: Uninstall or do not install any Debian-originated\nExplanation: package versions other than those in the stable distro\nPackage: *\nPin: release a=stable\nPin-Priority: 900\n\nPackage: *\nPin: release o=Debian\nPin-Priority: -10\n\nWith a suitable sources.list(5) file and the above preferences file, any of the following\ncommands will cause APT to upgrade to the latest stable version(s).\n\napt-get install package-name\napt-get upgrade\napt-get dist-upgrade\n\nThe following command will cause APT to upgrade the specified package to the latest version\nfrom the testing distribution; the package will not be upgraded again unless this command is\ngiven again.\n\napt-get install package/testing\n\n"
                },
                {
                    "name": "Tracking Testing or Unstable",
                    "content": "The following APT preferences file will cause APT to assign a high priority to package\nversions from the testing distribution, a lower priority to package versions from the\nunstable distribution, and a prohibitively low priority to package versions from other Debian\ndistributions.\n\nPackage: *\nPin: release a=testing\nPin-Priority: 900\n\nPackage: *\nPin: release a=unstable\nPin-Priority: 800\n\nPackage: *\nPin: release o=Debian\nPin-Priority: -10\n\nWith a suitable sources.list(5) file and the above preferences file, any of the following\ncommands will cause APT to upgrade to the latest testing version(s).\n\napt-get install package-name\napt-get upgrade\napt-get dist-upgrade\n\nThe following command will cause APT to upgrade the specified package to the latest version\nfrom the unstable distribution. Thereafter, apt-get upgrade will upgrade the package to the\nmost recent testing version if that is more recent than the installed version, otherwise, to\nthe most recent unstable version if that is more recent than the installed version.\n\napt-get install package/unstable\n\n"
                },
                {
                    "name": "Tracking the evolution of a codename release",
                    "content": "The following APT preferences file will cause APT to assign a priority higher than the\ndefault (500) to all package versions belonging to a specified codename of a distribution and\na prohibitively low priority to package versions belonging to other Debian distributions,\ncodenames and archives. Note that with this APT preference APT will follow the migration of a\nrelease from the archive testing to stable and later oldstable. If you want to follow for\nexample the progress in testing notwithstanding the codename changes you should use the\nexample configurations above.\n\nExplanation: Uninstall or do not install any Debian-originated package versions\nExplanation: other than those in the distribution codenamed with bookworm or sid\nPackage: *\nPin: release n=bookworm\nPin-Priority: 900\n\nExplanation: Debian unstable is always codenamed with sid\nPackage: *\nPin: release n=sid\nPin-Priority: 800\n\nPackage: *\nPin: release o=Debian\nPin-Priority: -10\n\nWith a suitable sources.list(5) file and the above preferences file, any of the following\ncommands will cause APT to upgrade to the latest version(s) in the release codenamed with\nbookworm.\n\napt-get install package-name\napt-get upgrade\napt-get dist-upgrade\n\nThe following command will cause APT to upgrade the specified package to the latest version\nfrom the sid distribution. Thereafter, apt-get upgrade will upgrade the package to the most\nrecent bookworm version if that is more recent than the installed version, otherwise, to the\nmost recent sid version if that is more recent than the installed version.\n\napt-get install package/sid\n\n"
                }
            ]
        },
        "FILES": {
            "content": "/etc/apt/preferences\nVersion preferences file. This is where you would specify \"pinning\", i.e. a preference to\nget certain packages from a separate source or from a different version of a\ndistribution. Configuration Item: Dir::Etc::Preferences.\n\n/etc/apt/preferences.d/\nFile fragments for the version preferences. Configuration Item:\nDir::Etc::PreferencesParts.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "apt-get(8) apt-cache(8) apt.conf(5) sources.list(5)\n",
            "subsections": []
        },
        "BUGS": {
            "content": "APT bug page[1]. If you wish to report a bug in APT, please see\n/usr/share/doc/debian/bug-reporting.txt or the reportbug(1) command.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "",
            "subsections": [
                {
                    "name": "APT team",
                    "content": ""
                }
            ]
        },
        "NOTES": {
            "content": "1. APT bug page\nhttp://bugs.debian.org/src:apt\n\n\n\nAPT 2.4.14                                 03 January 2022                        APTPREFERENCES(5)",
            "subsections": []
        }
    },
    "summary": "aptpreferences - Preference control file for APT",
    "flags": [],
    "examples": [
        "The following APT preferences file will cause APT to assign a priority higher than the",
        "default (500) to all package versions belonging to a stable distribution and a prohibitively",
        "low priority to package versions belonging to other Debian distributions.",
        "Explanation: Uninstall or do not install any Debian-originated",
        "Explanation: package versions other than those in the stable distro",
        "Package: *",
        "Pin: release a=stable",
        "Pin-Priority: 900",
        "Package: *",
        "Pin: release o=Debian",
        "Pin-Priority: -10",
        "With a suitable sources.list(5) file and the above preferences file, any of the following",
        "commands will cause APT to upgrade to the latest stable version(s).",
        "apt-get install package-name",
        "apt-get upgrade",
        "apt-get dist-upgrade",
        "The following command will cause APT to upgrade the specified package to the latest version",
        "from the testing distribution; the package will not be upgraded again unless this command is",
        "given again.",
        "apt-get install package/testing",
        "The following APT preferences file will cause APT to assign a high priority to package",
        "versions from the testing distribution, a lower priority to package versions from the",
        "unstable distribution, and a prohibitively low priority to package versions from other Debian",
        "distributions.",
        "Package: *",
        "Pin: release a=testing",
        "Pin-Priority: 900",
        "Package: *",
        "Pin: release a=unstable",
        "Pin-Priority: 800",
        "Package: *",
        "Pin: release o=Debian",
        "Pin-Priority: -10",
        "With a suitable sources.list(5) file and the above preferences file, any of the following",
        "commands will cause APT to upgrade to the latest testing version(s).",
        "apt-get install package-name",
        "apt-get upgrade",
        "apt-get dist-upgrade",
        "The following command will cause APT to upgrade the specified package to the latest version",
        "from the unstable distribution. Thereafter, apt-get upgrade will upgrade the package to the",
        "most recent testing version if that is more recent than the installed version, otherwise, to",
        "the most recent unstable version if that is more recent than the installed version.",
        "apt-get install package/unstable",
        "The following APT preferences file will cause APT to assign a priority higher than the",
        "default (500) to all package versions belonging to a specified codename of a distribution and",
        "a prohibitively low priority to package versions belonging to other Debian distributions,",
        "codenames and archives. Note that with this APT preference APT will follow the migration of a",
        "release from the archive testing to stable and later oldstable. If you want to follow for",
        "example the progress in testing notwithstanding the codename changes you should use the",
        "example configurations above.",
        "Explanation: Uninstall or do not install any Debian-originated package versions",
        "Explanation: other than those in the distribution codenamed with bookworm or sid",
        "Package: *",
        "Pin: release n=bookworm",
        "Pin-Priority: 900",
        "Explanation: Debian unstable is always codenamed with sid",
        "Package: *",
        "Pin: release n=sid",
        "Pin-Priority: 800",
        "Package: *",
        "Pin: release o=Debian",
        "Pin-Priority: -10",
        "With a suitable sources.list(5) file and the above preferences file, any of the following",
        "commands will cause APT to upgrade to the latest version(s) in the release codenamed with",
        "bookworm.",
        "apt-get install package-name",
        "apt-get upgrade",
        "apt-get dist-upgrade",
        "The following command will cause APT to upgrade the specified package to the latest version",
        "from the sid distribution. Thereafter, apt-get upgrade will upgrade the package to the most",
        "recent bookworm version if that is more recent than the installed version, otherwise, to the",
        "most recent sid version if that is more recent than the installed version.",
        "apt-get install package/sid"
    ],
    "see_also": [
        {
            "name": "apt-get",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/apt-get/8/json"
        },
        {
            "name": "apt-cache",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/apt-cache/8/json"
        },
        {
            "name": "apt.conf",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/apt.conf/5/json"
        },
        {
            "name": "sources.list",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/sources.list/5/json"
        }
    ]
}