apt_preferences (5)





NAME

       apt_preferences - Preference control file for APT


DESCRIPTION

       The  APT  preferences  file /etc/apt/preferences can be used to control
       which version of a package will be selected for installation.

       Several versions of a package may be available  for  installation  when
       the sources.list(5) file contains references to more than one distribu-
       tion (for example, stable and testing); furthermore, several  instances
       of  the  same  version of a package may be available when the file con-
       tains references to more than one download site for a  particular  dis-
       tribution.   APT  assigns  a "priority" to each instance that is avail-
       able.  (In what follows, an "instance" will be an instance of a package
       that is available according to sources.list(5).)  Subject to dependency
       constraints, apt-get installs the instance with the  highest  priority.
       If  two  instances  have  the  same  priority then it installs the more
       recent one, that is, the one with the higher version number.

       The APT preferences file overrides the priorities that APT  assigns  to
       package  instances  by default, thus giving the user control over which
       one is selected for installation.

   APT'S DEFAULT PRIORITY ASSIGNMENTS
       If there is no preferences file, or if there is no entry  in  the  file
       that  applies  to  a particular instance, then the priority assigned to
       that instance is  the  priority  of  the  distribution  to  which  that
       instance  belongs.  It is possible to single out a distribution, called
       the "target release", which receives a higher priority than other  dis-
       tributions.   The target release can be set on the apt-get command line
       or in the APT configuration file /etc/apt/apt.conf.  For example,

       # Command to install the testing version of some-package
       apt-get install -t testing some-package

       # Configuration setting to make stable the target release
       APT::Default-Release "stable";

       If a target release has been specified  then  APT  uses  the  following
       algorithm to set the priorities of the instances of a package.  Assign:

       priority 100
              to the instance that is already installed (if any).

       priority 500
              to the instances that are not installed and do not belong to the
              target release.

       priority 990
              to the instances that are not installed and belong to the target
              release.

       If no target release has been specified then APT simply assigns  prior-
       ity  100  to  all  installed  package instances and priority 500 to all
       uninstalled package instances.

        Install the highest priority instance.

        If  two  or  more  instances have the same priority, install the most
         recent one.

        If two or more instances have the same version  number,  install  the
         one  whose  source  is  listed  earliest  in  sources.list(5).   (The
         installed instance, if there is one, is always preferred  in  such  a
         comparison unless apt-get --reinstall is used.)

       In  a  typical situation, the installed instance of a package (priority
       100) is not as recent as  one  of  the  instances  available  from  the
       sources listed in the sources.list(5) file (priority 500 or 990).  Then
       the package will be upgraded with the command: apt-get install or  apt-
       get dist-upgrade.

       Rarely,  the installed instance of a package is more recent than any of
       the other available instances.  The package will not be downgraded.

       Sometimes the installed instance of a package is more recent  than  the
       version belonging to the target release, but not as recent as a version
       belonging to some other distribution.  Such a package  will  indeed  be
       upgraded,  because at least one of the available instances has a higher
       priority than the installed instance.

   THE EFFECT OF APT PREFERENCES
       The APT preferences file allows the system administrator  to  customize
       priorities.   The file consists of one or more multi-line records sepa-
       rated by blank lines.  Records can have one of two  forms,  a  specific
       form and a general form.

        The "specific" form pins a priority (a "Pin-Priority") to a specified
         package and specified version or version  range.   For  example,  the
         following  record  pins  a  high priority to all versions of the perl
         package whose version number begins with "5.8".

         Package: perl
         Pin: version 5.8*
         Pin-Priority: 1001

        The "general" form pins a priority to all of the package versions  in
         a  given  distribution (that is, to all the versions of packages that
         are listed in a certain Release file),  or  to  all  of  the  package
         instances  coming  from  a particular Internet site, as identified by
         its fully qualified domain name.

         This general-form entry in the APT preferences file applies  only  to
         groups  of packages.  For example, the following record causes APT to
         assign a high priority to all package instances  available  from  the
         local site.

         Package: *
         Pin: origin ""
         Pin-Priority: 999

         A  note  of  caution: the keyword used here is "origin".  This should
         Package: *
         Pin: release a=unstable
         Pin-Priority: 50

         The  following  record  causes  APT  to assign a high priority to all
         package versions belonging to any release whose "Archive" (a) name is
         "stable" and whose release "Version" (v) number is "3.0".

         Package: *
         Pin: release a=unstable, v=3.0
         Pin-Priority: 50

   HOW APT INTERPRETS PRIORITIES
       Priorities (P) assigned in the APT preferences file must be positive or
       negative integers.  They are interpreted as follows (roughly speaking):

       P > 1000
              causes  an  instance  to be installed even if this constitutes a
              downgrade of the package

       990 < P <=1000
              causes an instance to be installed even if it does not come from
              the target release, unless the installed instance is more recent

       500 < P <=990
              causes an instance to be installed unless there is  an  instance
              available  belonging to the target release or the installed ver-
              sion is more recent

       100 < P <=500
              causes an instance to be installed unless there is  an  instance
              available  belonging to some other distribution or the installed
              version is more recent

       0 <= P <=100
              causes an instance to be installed only if there is no installed
              instance of the package

       P < 0  prevents the instance from being installed

       If  one  of the specific-form records described above matches an avail-
       able package instance, then that record determines the priority of  the
       instance.   If  two  specific-form records match an available instance,
       then the first record encountered determines the priority.  If two gen-
       eral-form  records  match  an available instance, then the first record
       encountered determines the priority.

       For example, suppose  the  APT  preferences  file  contains  the  three
       records presented earlier:

       Package: perl
       Pin: version 5.8*
       Pin-Priority: 1001

       Package: *
       Pin: origin ""
       Pin-Priority: 999
         version is 5.9*, then perl will be downgraded.

        An instance of any package other than perl that is available from the
         local  system  has  priority  over  other  instances,  even instances
         belonging to the target release.

        An instance of a package whose origin is not  the  local  system  but
         some  other  site  listed in sources.list(5), and which belongs to an
         "unstable" distribution, is only installed  if  it  is  selected  for
         installation and no instance of the package is already installed.

   DETERMINATION OF PACKAGE VERSION AND DISTRIBUTION PROPERTIES
       The  locations listed in a system's sources.list(5) file should provide
       Packages and Release files to describe the package instances  available
       at that location.

       The  Packages  file  is normally found in the directory .../dists/dist-
       name/component/arch:   for    example,    .../dists/stable/main/binary-
       i386/Packages.   It consists of a series of multi-line records, one for
       each package available in that  directory.   Only  two  lines  in  each
       record are relevant for setting APT priorities:

       the Package: line
              gives the package name

       the Version: line
              gives the version number for the named package

       The  Release  file  is  normally found in the directory .../dists/dist-
       name:       for       example,       .../dists/stable/Release,       or
       .../dists/woody/Release.   It  consists  of  a single multi-line record
       which applies to all of the package instances  in  the  directory  tree
       below its parent.  Unlike the Packages file, nearly all of the lines in
       a Release file are relevant for setting APT priorities:

       the Archive: line
              names the archive to which all  the  package  instances  in  the
              directory  tree  belong.   For example, the line Archive: stable
              specifies that all of the packages in the directory  tree  below
              the parent of the Release file are in the stable archive.  Spec-
              ifying this value in the APT preferences file would require  the
              line:

              Pin: release a=stable

       the Version: line
              names  the  release version.  For example, the package instances
              in the tree might belong to  Debian  GNU/Linux  release  version
              3.0.   There is normally no version number for the "testing" and
              "unstable"  distributions  because  they  have  not   yet   been
              released.   Specifying  this  in  the APT preferences file would
              require one of the following lines.

              Pin: release v=3.0
              Pin: release a=stable v=3.0
              Pin: release 3.0

              Pin: release c=main

       the Origin: line
              names the producer of the package  instances  in  the  directory
              tree of the Release file.  Most commonly, this is Debian.  Spec-
              ifying this origin in the APT preferences file would require the
              line:

              Pin: release o=Debian

       the Label: line
              seems  redundant.   Most  commonly,  this is Debian.  Specifying
              this label in the APT preferences file would require the line:

              Pin: release l=Debian

       All of the Packages and Release files retrieved from  locations  listed
       in    the    sources.list(5)   file   are   kept   in   the   directory
       /var/lib/apt/lists,  or   in   the   file   named   by   the   variable
       Dir::State::Lists   in  the  apt.conf  file.   For  example,  the  file
       debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release
       contains  the  Release  file retrieved from the site debian.lcs.mit.edu
       for binary-i386 architecture files from the contrib  component  of  the
       unstable distribution.

   OPTIONAL LINES IN AN APT PREFERENCES RECORD
       Each  record  in the APT preferences file can optionally begin with one
       or more lines beginning with the word Explanation:.  This  provides  an
       opportunity to comment on the record.

       The  Pin-Priority: line in each APT preferences record is optional.  If
       omitted, APT assigs a priority of 1 less than the last value  specified
       on a line beginning with Pin-Priority: release ....


EXAMPLES

   TRACKING STABLE
       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 ver-
       sions belonging to other Debian distributions.

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

       Explanation: Uninstall or do not install any Debian-originated
       Explanation: instances other than those in the stable distro
       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
       The following APT preferences file will cause APT to assign a high pri-
       ority  to  package  versions  from  the  testing distribution, a lesser
       priority to package versions from the unstable distribution, and a pro-
       hibitively low priority to package versions from other Debian distribu-
       tions.

       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 the above APT 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  dist-upgrade  and  the others will cause upgrade of the package to
       the latest unstable version.

       apt-get install package/unstable


SEE ALSO

       apt-get(8) apt-cache(8) apt.conf(5) sources.list(5)


BUGS

       See the APT bug page <URL:http://bugs.debian.org/apt>.  If you wish  to
       report a bug in APT, please see /usr/share/doc/debian/bug-reporting.txt
       or the reportbug(1) command.


AUTHOR

       APT was written by the APT team <apt@packages.debian.org>.

                                17 August 2003              apt_preferences(5)