1dpkg(1) dpkg suite dpkg(1)
2
6 dpkg - package manager for Debian
7
9 dpkg [options] action
10
12 This manual is intended for users wishing to understand dpkg's command
13 line options and package states in more detail than that provided by
14 dpkg --help.
15 It should not be used by package maintainers wishing to understand how
17 dpkg will install their packages. The descriptions of what dpkg does
18 when installing and removing packages are particularly inadequate.
19
21 dpkg is a tool to install, build, remove and manage Debian packages.
22 The primary and more user-friendly front-end for dpkg is aptitude(1).
23 dpkg itself is controlled entirely via command line parameters, which
24 consist of exactly one action and zero or more options. The action-
25 parameter tells dpkg what to do and options control the behavior of the
26 action in some way.
27 dpkg can also be used as a front-end to dpkg-deb(1). The following are
29 dpkg-deb actions, and if they are encountered, dpkg just runs dpkg-deb
30 with the parameters given to it:
31 -b, --build,
32 -c, --contents,
33 -I, --info,
34 -f, --field,
35 -e, --control,
36 -x, --extract,
37 -X, --vextract, and
38 --fsys-tarfile.
39 Please refer to dpkg-deb(1) for information about these actions.
40
42 dpkg maintains some usable information about available packages. The
43 information is divided in three classes: states, selection states and
44 flags. These values are intended to be changed mainly with dselect.
45 PACKAGE STATES
47 not-installed
48 The package is not installed on your system.
49 config-files
51 Only the configuration files of the package exist on the system.
52 half-installed
54 The installation of the package has been started, but not com‐
55 pleted for some reason.
56 unpacked
58 The package is unpacked, but not configured.
59 half-configured
61 The package is unpacked and configuration has been started, but
62 not yet completed for some reason.
63 triggers-awaited
65 The package awaits trigger processing by another package.
66 triggers-pending
68 The package has been triggered.
69 installed
71 The package is unpacked and configured OK.
72 PACKAGE SELECTION STATES
74 install
75 The package is selected for installation.
76 hold A package marked to be on hold is not handled by dpkg, unless
78 forced to do that with option --force-hold.
79 deinstall
81 The package is selected for deinstallation (i.e. we want to
82 remove all files, except configuration files).
83 purge The package is selected to be purged (i.e. we want to remove
85 everything, even configuration files).
86 PACKAGE FLAGS
88 reinst-required
89 A package marked reinst-required is broken and requires rein‐
90 stallation. These packages cannot be removed, unless forced with
91 option --force-remove-reinstreq.
92
94 -i, --install package_file...
95 Install the package. If --recursive or -R option is specified,
96 package_file must refer to a directory instead.
97 Installation consists of the following steps:
99 1. Extract the control files of the new package.
101 2. If another version of the same package was installed before
103 the new installation, execute prerm script of the old package.
104 3. Run preinst script, if provided by the package.
106 4. Unpack the new files, and at the same time back up the old
108 files, so that if something goes wrong, they can be restored.
109 5. If another version of the same package was installed before
111 the new installation, execute the postrm script of the old pack‐
112 age. Note that this script is executed after the preinst script
113 of the new package, because new files are written at the same
114 time old files are removed.
115 6. Configure the package. See --configure for detailed informa‐
117 tion about how this is done.
118 --unpack package_file...
120 Unpack the package, but don't configure it. If --recursive or -R
121 option is specified, package_file must refer to a directory
122 instead.
123 --configure package...|-a|--pending
125 Reconfigure an unpacked package. If -a or --pending is given
126 instead of package, all unpacked but unconfigured packages are
127 configured.
128 Configuring consists of the following steps:
130 1. Unpack the conffiles, and at the same time back up the old
132 conffiles, so that they can be restored if something goes wrong.
133 2. Run postinst script, if provided by the package.
135 --triggers-only package...|-a|--pending
137 Processes only triggers. All pending triggers will be processed.
138 If package names are supplied only those packages' triggers will
139 be processed, exactly once each where necessary. Use of this
140 option may leave packages in the improper triggers-awaited and
141 triggers-pending states. This can be fixed later by running:
142 dpkg --configure --pending.
143 -r, --remove, -P, --purge package...|-a|--pending
145 Remove an installed package. -r or --remove remove everything
146 except conffiles. This may avoid having to reconfigure the pack‐
147 age if it is reinstalled later. (Conffiles are configuration
148 files that are listed in the DEBIAN/conffiles control file). -P
149 or --purge removes everything, including conffiles. If -a or
150 --pending is given instead of a package name, then all packages
151 unpacked, but marked to be removed or purged in file
152 /var/lib/dpkg/status, are removed or purged, respectively. Note:
153 some configuration files might be unknown to dpkg because they
154 are created and handled separately through the configuration
155 scripts. In that case, dpkg won't remove them by itself, but the
156 package's postrm script (which is called by dpkg), has to take
157 care of their removal during purge.
158 Removing of a package consists of the following steps:
160 1. Run prerm script
162 2. Remove the installed files
164 3. Run postrm script
166 --update-avail, --merge-avail Packages-file
168 Update dpkg's and dselect's idea of which packages are avail‐
169 able. With action --merge-avail, old information is combined
170 with information from Packages-file. With action --update-avail,
171 old information is replaced with the information in the Pack‐
172 ages-file. The Packages-file distributed with Debian is simply
173 named Packages. dpkg keeps its record of available packages in
174 /var/lib/dpkg/available.
175 A simpler one-shot command to retrieve and update the available
177 file is dselect update. Note that this file is mostly useless if
178 you don't use dselect but an APT-based frontend: APT has its own
179 system to keep track of available packages.
180 -A, --record-avail package_file...
182 Update dpkg and dselect's idea of which packages are available
183 with information from the package package_file. If --recursive
184 or -R option is specified, package_file must refer to a direc‐
185 tory instead.
186 --forget-old-unavail
188 Now obsolete and a no-op as dpkg will automatically forget unin‐
189 stalled unavailable packages.
190 --clear-avail
192 Erase the existing information about what packages are avail‐
193 able.
194 -C, --audit
196 Searches for packages that have been installed only partially on
197 your system. dpkg will suggest what to do with them to get them
198 working.
199 --get-selections [package-name-pattern...]
201 Get list of package selections, and write it to stdout. Without
202 a pattern, non-installed packages (i.e. those which have been
203 previously purged) will not be shown.
204 --set-selections
206 Set package selections using file read from stdin. This file
207 should be in the format '<package> <state>', where state is one
208 of install, hold, deinstall or purge. Blank lines and comment
209 lines beginning with '#' are also permitted.
210 --clear-selections
212 Set the requested state of every non-essential package to dein‐
213 stall. This is intended to be used immediately before
214 --set-selections, to deinstall any packages not in list given to
215 --set-selections.
216 --yet-to-unpack
218 Searches for packages selected for installation, but which for
219 some reason still haven't been installed.
220 --print-architecture
223 Print architecture of packages dpkg installs (for exam‐
224 ple, "i386").
225 --compare-versions ver1 op ver2
227 Compare version numbers, where op is a binary operator.
228 dpkg returns success (zero result) if the specified con‐
229 dition is satisfied, and failure (nonzero result) other‐
230 wise. There are two groups of operators, which differ in
231 how they treat an empty ver1 or ver2. These treat an
232 empty version as earlier than any version: lt le eq ne ge
233 gt. These treat an empty version as later than any ver‐
234 sion: lt-nl le-nl ge-nl gt-nl. These are provided only
235 for compatibility with control file syntax: < << <= = >=
236 >> >.
237 --command-fd <n>
239 Accept a series of commands on input file descriptor <n>.
240 Note: additional options set on the command line, and
241 thru this file descriptor, are not reset for subsequent
242 commands executed during the same run.
243 --help Display a brief help message.
245 --force-help
247 Give help about the --force-thing options.
248 -Dh, --debug=help
250 Give help about debugging options.
251 --licence, --license
253 Display dpkg licence.
254 --version
256 Display dpkg version information.
257 dpkg-deb actions
259 See dpkg-deb(1) for more information about the following
260 actions.
261 -b, --build directory [archive|directory]
263 Build a deb package.
264 -c, --contents archive
265 List contents of a deb package.
266 -e, --control filename [directory]
267 Extract control-information from a package.
268 -x, --extract archive directory
269 Extract the files contained by package.
270 -X, --vextract archive directory
271 Extract and display the filenames contained by a
272 package.
273 -f, --field archive [control-field...]
274 Display control field(s) of a package.
275 --fsys-tarfile archive
276 Display the filesystem tar-file contained by a
277 Debian package.
278 -I, --info archive [control-file...]
279 Show information about a package.
280 dpkg-query actions
283 See dpkg-query(1) for more information about the follow‐
284 ing actions.
285 -l, --list package-name-pattern...
288 List packages matching given pattern.
289 -s, --status package-name...
290 Report status of specified package.
291 -L, --listfiles package-name...
292 List files installed to your system from package-name.
293 -S, --search filename-search-pattern...
294 Search for a filename from installed packages.
295 -p, --print-avail package-name...
296 Display details about package-name, as found in
297 /var/lib/dpkg/available. Users of APT-based frontends
298 should use apt-cache show package-name instead.
299
301 All options can be specified both on the command line and in the
302 dpkg configuration file /etc/dpkg/dpkg.cfg or the files on the
303 configuration directory /etc/dpkg/dpkg.cfg.d/. Each line in the
304 configuration file is either an option (exactly the same as the
305 command line option but without leading dashes) or a comment (if
306 it starts with a #).
307 --abort-after=number
309 Change after how many errors dpkg will abort. The default
310 is 50.
311 -B, --auto-deconfigure
313 When a package is removed, there is a possibility that
314 another installed package depended on the removed pack‐
315 age. Specifying this option will cause automatic decon‐
316 figuration of the package which depended on the removed
317 package.
318 -Doctal, --debug=octal
320 Switch debugging on. octal is formed by bitwise-orring
321 desired values together from the list below (note that
322 these values may change in future releases). -Dh or
323 --debug=help display these debugging values.
324 number description
326 1 Generally helpful progress information
327 2 Invocation and status of maintainer scripts
328 10 Output for each file processed
329 100 Lots of output for each file processed
330 20 Output for each configuration file
331 200 Lots of output for each configuration file
332 40 Dependencies and conflicts
333 400 Lots of dependencies/conflicts output
334 10000 Trigger activation and processing
335 20000 Lots of output regarding triggers
336 40000 Silly amounts of output regarding triggers
337 1000 Lots of drivel about e.g. the dpkg/info dir
338 2000 Insane amounts of drivel
339 --force-things, --no-force-things, --refuse-things
341 Force or refuse (no-force and refuse mean the same thing)
343 to do some things. things is a comma separated list of
344 things specified below. --force-help displays a message
345 describing them. Things marked with (*) are forced by
346 default.
347 Warning: These options are mostly intended to be used by
349 experts only. Using them without fully understanding
350 their effects may break your whole system.
351 all: Turns on (or off) all force options.
353 downgrade(*): Install a package, even if newer version of
355 it is already installed.
356 Warning: At present dpkg does not do any dependency
358 checking on downgrades and therefore will not warn you if
359 the downgrade breaks the dependency of some other pack‐
360 age. This can have serious side effects, downgrading
361 essential system components can even make your whole sys‐
362 tem unusable. Use with care.
363 configure-any: Configure also any unpacked but unconfig‐
365 ured packages on which the current package depends.
366 hold: Process packages even when marked "hold".
368 remove-reinstreq: Remove a package, even if it's broken
370 and marked to require reinstallation. This may, for exam‐
371 ple, cause parts of the package to remain on the system,
372 which will then be forgotten by dpkg.
373 remove-essential: Remove, even if the package is consid‐
375 ered essential. Essential packages contain mostly very
376 basic Unix commands. Removing them might cause the whole
377 system to stop working, so use with caution.
378 depends: Turn all dependency problems into warnings.
380 depends-version: Don't care about versions when checking
382 dependencies.
383 breaks: Install, even if this would break another pack‐
385 age.
386 conflicts: Install, even if it conflicts with another
388 package. This is dangerous, for it will usually cause
389 overwriting of some files.
390 confmiss: Always install a missing conffile. This is dan‐
392 gerous, since it means not preserving a change (removing)
393 made to the file.
394 confnew: If a conffile has been modified always install
396 the new version without prompting, unless the
397 --force-confdef is also specified, in which case the
398 default action is preferred.
399 confold: If a conffile has been modified always keep the
401 old version without prompting, unless the --force-confdef
402 is also specified, in which case the default action is
403 preferred.
404 confdef: If a conffile has been modified always choose
406 the default action. If there is no default action it will
407 stop to ask the user unless --force-confnew or
408 --force-confold is also been given, in which case it will
409 use that to decide the final action.
410 overwrite: Overwrite one package's file with another's
412 file.
413 overwrite-dir Overwrite one package's directory with
415 another's file.
416 overwrite-diverted: Overwrite a diverted file with an
418 undiverted version.
419 architecture: Process even packages with the wrong archi‐
421 tecture.
422 bad-path: PATH is missing important programs, so problems
424 are likely.
425 not-root: Try to (de)install things even when not root.
427 bad-verify: Install a package even if it fails authentic‐
429 ity check.
430 --ignore-depends=package,...
433 Ignore dependency-checking for specified packages (actu‐
434 ally, checking is performed, but only warnings about con‐
435 flicts are given, nothing else).
436 --new, --old
438 Select new or old binary package format. This is a
439 dpkg-deb(1) option.
440 --nocheck
442 Don't read or check contents of control file while build‐
443 ing a package. This is a dpkg-deb(1) option.
444 --no-act, --dry-run, --simulate
446 Do everything which is supposed to be done, but don't
447 write any changes. This is used to see what would happen
448 with the specified action, without actually modifying
449 anything.
450 Be sure to give --no-act before the action-parameter, or
452 you might end up with undesirable results. (e.g. dpkg
453 --purge foo --no-act will first purge package foo and
454 then try to purge package --no-act, even though you prob‐
455 ably expected it to actually do nothing)
456 -R, --recursive
458 Recursively handle all regular files matching pattern
459 *.deb found at specified directories and all of its sub‐
460 directories. This can be used with -i, -A, --install,
461 --unpack and --avail actions.
462 -G Don't install a package if a newer version of the same
464 package is already installed. This is an alias of
465 --refuse-downgrade.
466 --admindir=dir
468 Change default administrative directory, which contains
469 many files that give information about status of
470 installed or uninstalled packages, etc. (Defaults to
471 /var/lib/dpkg)
472 --instdir=dir
474 Change default installation directory which refers to the
475 directory where packages are to be installed. instdir is
476 also the directory passed to chroot(2) before running
477 package's installation scripts, which means that the
478 scripts see instdir as a root directory. (Defaults to /)
479 --root=dir
481 Changing root changes instdir to dir and admindir to
482 dir/var/lib/dpkg.
483 -O, --selected-only
485 Only process the packages that are selected for installa‐
486 tion. The actual marking is done with dselect or by dpkg,
487 when it handles packages. For example, when a package is
488 removed, it will be marked selected for deinstallation.
489 -E, --skip-same-version
491 Don't install the package if the same version of the
492 package is already installed.
493 --pre-invoke=command
495 --post-invoke=command
496 Set an invoke hook command to be run via “sh -c” before
497 or after the dpkg run for the unpack, configure, install,
498 triggers-only, remove and purge dpkg actions. This option
499 can be specified multiple times. The order the options
500 are specified is preserved, with the ones from the con‐
501 figuration files taking precedence. The environment
502 variable DPKG_HOOK_ACTION is set for the hooks to the
503 current dpkg action. Note: front-ends might call dpkg
504 several times per invocation, which might run the hooks
505 more times than expected.
506 --status-fd n
508 Send machine-readable package status and progress infor‐
509 mation to file descriptor n. This option can be specified
510 multiple times. The information is generally one record
511 per line, in one of the following forms:
512 status: package: status
514 Package status changed; status is as in the status
515 file.
516 status: package : error : extended-error-message
518 An error occurred. Unfortunately at the time of
519 writing extended-error-message can contain new‐
520 lines, although in locales where the translators
521 have not made mistakes every newline is followed
522 by at least one space.
523 status: file : conffile-prompt : 'real-old' 'real-new'
525 useredited distedited
526 User is being asked a conffile question.
527 processing: stage: package
529 Sent just before a processing stage starts. stage
530 is one of upgrade, install (both sent before
531 unpacking), configure, trigproc, disappear,
532 remove, purge.
533 --log=filename
535 Log status change updates and actions to filename,
536 instead of the default /var/log/dpkg.log. If this option
537 is given multiple times, the last filename is used. Log
538 messages are of the form `YYYY-MM-DD HH:MM:SS status
539 <state> <pkg> <installed-version>' for status change
540 updates; `YYYY-MM-DD HH:MM:SS <action> <pkg> <installed-
541 version> <available-version>' for actions where <action>
542 is one of install, upgrade, remove, purge; and `YYYY-MM-
543 DD HH:MM:SS conffile <filename> <decision>' for conffile
544 changes where <decision> is either install or keep.
545 --no-debsig
547 Do not try to verify package signatures.
548 --no-triggers
550 Do not run any triggers in this run (activations will
551 still be recorded). If used with --configure package or
552 --triggers-only package then the named package postinst
553 will still be run even if only a triggers run is needed.
554 Use of this option may leave packages in the improper
555 triggers-awaited and triggers-pending states. This can be
556 fixed later by running: dpkg --configure --pending.
557 --triggers
559 Cancels a previous --no-triggers.
560
562 /etc/dpkg/dpkg.cfg
563 Configuration file with default options.
564 /var/log/dpkg.log
566 Default log file (see /etc/dpkg/dpkg.cfg(5) and option
567 --log).
568 The other files listed below are in their default directories,
570 see option --admindir to see how to change locations of these
571 files.
572 /var/lib/dpkg/available
574 List of available packages.
575 /var/lib/dpkg/status
577 Statuses of available packages. This file contains infor‐
578 mation about whether a package is marked for removing or
579 not, whether it is installed or not, etc. See section
580 INFORMATION ABOUT PACKAGES for more info.
581 The status file is backed up daily in /var/backups. It
583 can be useful if it's lost or corrupted due to filesys‐
584 tems troubles.
585 The following files are components of a binary package. See
587 deb(5) for more information about them:
588 control
590 conffiles
592 preinst
594 postinst
596 prerm
598 postrm
600
602 DPKG_NO_TSTP
603 Define this to something if you prefer dpkg starting a
604 new shell rather than suspending itself, while doing a
605 shell escape.
606 SHELL The program dpkg will execute when starting a new shell.
608 COLUMNS
610 Sets the number of columns dpkg should use when display‐
611 ing formatted text. Currently only used by -l.
612 DPKG_RUNNING_VERSION
614 Defined by dpkg on the maintainer script environment to
615 the version of the currently running dpkg instance.
616 DPKG_MAINTSCRIPT_PACKAGE
618 Defined by dpkg on the maintainer script environment to
619 the package name being handled.
620 DPKG_MAINTSCRIPT_ARCH
622 Defined by dpkg on the maintainer script environment to
623 the architecture the package got built for.
624
626 To list packages related to the editor vi(1):
627 dpkg -l '*vi*'
628 To see the entries in /var/lib/dpkg/available of two packages:
630 dpkg --print-avail elvis vim | less
631 To search the listing of packages yourself:
633 less /var/lib/dpkg/available
634 To remove an installed elvis package:
636 dpkg -r elvis
637 To install a package, you first need to find it in an archive or
639 CDROM. The "available" file shows that the vim package is in
640 section "editors":
641 cd /cdrom/pool/main/v/vim
642 dpkg -i vim_4.5-3.deb
643 To make a local copy of the package selection states:
645 dpkg --get-selections >myselections
646 You might transfer this file to another computer, and install it
648 there with:
649 dpkg --clear-selections
650 dpkg --set-selections <myselections
651 Note that this will not actually install or remove anything, but
653 just set the selection state on the requested packages. You will
654 need some other application to actually download and install the
655 requested packages. For example, run apt-get dselect-upgrade.
656 Ordinarily, you will find that dselect(1) provides a more conve‐
658 nient way to modify the package selection states.
659
661 Additional functionality can be gained by installing any of the
662 following packages: apt, aptitude and debsums.
663
665 aptitude(1), apt(1), dselect(1), dpkg-deb(1), dpkg-query(1),
666 deb(5), deb-control(5), dpkg.cfg(5), and dpkg-reconfigure(8).
667
669 --no-act usually gives less information than might be helpful.
670
672 See /usr/share/doc/dpkg/THANKS for the list of people who have
673 contributed to dpkg.
674Debian Project 2009-11-12 dpkg(1)