Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PORTUPGRADE(1)		  BSD General Commands Manual		PORTUPGRADE(1)

     portupgrade, portinstall -- tools to upgrade installed packages or	in-
     stall new ones via	ports or packages

     portupgrade [-habcCDDefFiknNOpPPqrRsuvwWy]	[-A command] [-B command]
		 [-l file] [-L format] [-S command] [-x	pkgname_glob]
		 [[-o origin] [-m make_args] [-M make_env] pkgname_glob	...]

     The portupgrade command is	used to	upgrade	installed packages via ports
     or	packages.  The portinstall command is equivalent to portupgrade	-N.

     Before reading these instructions,	you must understand that a port/pack-
     age can have the following	two types of related ports/packages:
     required	Ports/packages that a port/package needs for it	to be built
		and/or run.  Port Makefiles refer to this type of ports/pack-
		ages using the BUILD_DEPENDS and RUN_DEPENDS macros, respec-
     dependent	Ports/packages that need this port/package.

     When portupgrade deals with multiple packages, it automatically sorts the
     packages in dependency order using	the equivalent of tsort(1).

     +o	 Please	read this manual page carefully	and understand what you	are
	 doing with portupgrade.

     +o	 When the tools	suggest	running	"pkgdb -F", run	it.  Upgrade a certain
	 number	of packages at once with an inconsistent package database will
	 surely	cause bad results.

     +o	 Since portupgrade allows you to upgrade your installed	packages with-
	 out rebuilding	and reinstalling dependent packages, upgraded packages
	 may occasionally cause	binary incompatibilities.  To cope with	this
	 situation, use	the -f,	-r and -R options as necessary.

     +o	 Do not	abort portupgrade while	it is updating the package database,
	 or it will leave you a	half modified, inconsistent database.  Even if
	 you do	not do anything	wrong, a package database may get corrupt
	 somehow when it is heavily updated.  In such cases, run "pkgdb	-fu"
	 to rebuild the	database and rescue the	tools from coredumping.	 If it
	 makes no effect, remove a database file (/var/db/pkg/pkgdb.db)	and
	 rerun the command.

     +o	 Do not	be lazy	about backing up your precious data and	configuration
	 files,	including the package database in "/var/db/pkg".

     The following command line	arguments are supported:

     pkgname_glob	    Specify one	of these: a full pkgname, a pkgname
			    without version, a shell glob pattern in which you
			    can	use wildcards `*', `?',	and an extended	regu-
			    lar	expression preceded by a colon `:', or a date
			    range specification	preceded by either `<' or `>'.
			    See	pkg_glob(1) for	details	and concrete examples.

     --help		    Show help and exit.

     --all		    Do with all	the installed packages.	 Equivalent to
			    specify '*'	as pkgname_glob.

     -A	CMD
     --afterinstall CMD	    Run	the specified command as root after each in-

     --backup-packages	    Keep backup	packages of the	old versions.

     --batch		    Run	an upgrading process in	a batch	mode (with
			    BATCH=yes).	 This will only	process	ports in a
			    100% automated way,	without	requiring any user in-
			    teraction.	Options	dialogs	will not be presented.
			    Also see -c	and -C.	 See ports(7) for more de-

     -B	CMD
     --beforebuild CMD	    Run	the specified command before each build.  If
			    the	command	exits in failure, the port/package
			    will be skipped.  Here is some typical uses:

				  portupgrade -B 'cvs update' 'gnome*'

				  portupgrade -B 'ports_glob -M	$(pwd) | (cd
				  ../..; xargs cvs up)'	slave/port

				  portupgrade -aB 'test	! `make	-V

     --config		    Run	"make config-conditional" before everything
			    for	all tasks.

     --force-config	    Run	"make config" before everything	for all	tasks.

     --distclean	    Delete failed distfiles and	retry if checksum
			    fails.  Specified twice, do	"make distclean" be-
			    fore each fetch or build.

     --emit-summaries	    Emit summary info after each port processing.

     --force		    Force the upgrade of a package even	if it is to be
			    a downgrade	or just	a reinstall of the same	ver-
			    sion, or the port is held by user using the
			    HOLD_PKGS variable in pkgtools.conf.

     --fetch-only	    Only fetch distfiles or packages (if -P is speci-
			    fied), do not build, upgrade or install anything.
			    This is useful if you want to download all the
			    needed distfiles or	packages at once in advance of
			    installing or upgrading.

			    By default,	if a port or a package fails to	build
			    or install,	its dependents will be skipped.

     --ignore-moved	    Do not read	MOVED file.

     --interactive	    Turn on interactive	mode.  You are asked for ap-
			    proval before each suggested installation or up-
			    grade.  This option	implies	-v.

     --keep-going	    Force the upgrade of a package even	if some	of the
			    requisite packages have failed to upgrade in ad-

     -l	FILE
     --results-file FILE    Specify a file name	to save	the results to.	 By
			    default, portupgrade does not save results as a

     -L	FORMAT
     --log-file	FORMAT	    Specify a printf(3)	style format to	determine the
			    log	file name for each port.  "%s::%s" is appended
			    if it does not contain a `%'.  Category and	port-
			    name are given as arguments, in the	order named.

     --make-args	    Specify arguments to append	to each	make(1)	com-
			    mand line.

     --make-env		    Specify arguments to prepend to each make(1) com-
			    mand line.

     --noexecute	    Do not actually install, upgrade or	fetch any
			    packages; just show	what would be done.  This op-
			    tion implies -v and	negates	-i and -y.

     --new		    Install a new port/package when a specified	pack-
			    age	is not installed.  Prior to the	installation a
			    new	port/package, all the required packages	are

			    If this option is specified, you can specify a
			    portorigin glob as well as a pkgname glob to spec-
			    ify	which port to install.	See portsdb(1) for the
			    details of the `portorigin glob'.

			    This option	makes portupgrade behave as if it were
			    called as portinstall.

     -o	ORIGIN
     --origin ORIGIN	    Specify a port to upgrade the following package

     --omit-check	    Omit sanity	checks for dependencies.  By default,
			    portupgrade	checks if all the packages to upgrade
			    have consistent dependencies, though it takes ex-
			    tra	time to	calculate dependencies.	 If you	are
			    sure you have run "pkgdb -F" in advance, you can
			    specify this option	to omit	the sanity checks.

     --package		    Build a package when each specified	port is	in-
			    stalled or upgraded.  If a package is upgraded and
			    its	dependent packages are given from the command
			    line (including the	case where -r is specified),
			    build packages for them as well.

     --use-packages	    Use	packages instead of ports whenever available.
			    portupgrade	searches the local directories listed
			    in PKG_PATH	for each package to install or upgrade
			    the	current	installation with, and if none is
			    found, pkg_fetch(1)	is invoked to fetch one	from a
			    remote site.  If it	does not work either, the port
			    is used.

			    However, the source	will still be used if the port
			    is listed in USE_PORTS_ONLY	variable in

     --use-packages-only    Never use the port even if a package is not	avail-
			    able either	locally	or remotely, although you
			    still have to keep your ports tree up-to-date so
			    that portupgrade can check out what	the latest
			    version of each port is.

     --quiet		    Do not display a message when -N specified and
			    there is already installed package.

     --noconfig		    Do not read	the configuration file -

     --recursive	    Act	on all those packages depending	on the given
			    packages as	well.

     --upward-recursive	    Act	on all those packages required by the given
			    packages as	well. (When specified with -F, fetch
			    recursively, including the brand new, uninstalled
			    ports that an upgraded port	requires)

     --sudo		    Run	commands under sudo(8) where needed.

     -S	CMD
     --sudo-command CMD	    Specify an alternative to sudo(8).	e.g.  "'su
			    root -c %s '" (default: sudo)

     --uninstall-shlibs	    Do not preserve old	shared libraries.  By default,
			    portupgrade	preserves shared libraries on unin-
			    stallation for safety.  See	the pkg_deinstall(1)
			    manpage and	check out the -P option	for details.

     --verbose		    Turn on verbose output.

     --noclean		    Do not "make clean"	before each build.

     --nocleanup	    Do not "make clean"	after each installation.

     --without-env-upgrade  Do not set UPGRADE_* environment variables.

     -x	GLOB
     --exclude GLOB	    Exclude packages matching the specified glob pat-
			    tern.  Exclusion is	performed after	recursing de-
			    pendency in	response to -r and/or -R, which	means,
			    for	example, the following command will upgrade
			    all	the packages depending on XFree86 but leave
			    XFree86 as it is:

				  portupgrade -rx XFree86 XFree86

     --yes		    Answer yes to all the questions.  This option im-
			    plies -v and negates -n.

     portupgrade upgrades installed packages via ports or packages without
     necessarily having	to reinstall required or dependent packages by adjust-
     ing the package registry database.

     The procedures it takes are briefly shown as below:

	   1.	If -P is not given, jump to 4.	Otherwise search the local di-
		rectories listed in PKG_PATH for a newer package tarball.  If
		found, jump to 5.

	   2.	Fetch the latest package from a	remote site using
		pkg_fetch(1).  If the fetched package is the latest, jump to
		5.  If -P is given twice (i.e.	-PP) and the fetched package
		is not the latest but at least newer than the current instal-
		lation,	jump to	5.

	   3.	If -P is given twice (i.e.  -PP), stop the task.

	   4.	Build the corresponding	port of	the given installed package.

	   5.	Fix the	dependency information of the packages that depend on
		the given package.

	   6.	Back up	the current installation of the	given package using
		pkg_create(1).	Note that the backup tarball will be very
		large if the package is	a big monster like XFree86.  Please
		ensure you have	sufficient disk	space (refer to	the ENVIRON-
		MENT section to	know where) to save the	backup tarball.	(Per-
		haps a new option to omit backups will be added	in the future)

	   7.	Back up	the current package registration files of the given

	   8.	Uninstall the given package forcibly, preserving shared	li-
		braries	unless -u is specified.

	   9.	Install	the new	version	via ports or packages, depending on
		the conditions in 1, 2 and 3.

	   10.	If the installation fails,

		      10.1.   Restore the old installation backed up in	6.

		      10.2.   Restore the old package registration files
			      backed up	in 7.

		      10.3.   Revert the dependency information	fixed in 5.

	   11.	Remove the dependencies	obsoleted in this upgrade.

	   12.	Run "portsclean	-L" to delete duplicate	libraries and put away
		old libraries.

	   13.	Run "pkgdb -aF"	to fix up stale	dependencies and reconstruct
		+REQUIRED_BY files.

     +o	 Upgrade glib:

	       portupgrade glib

	 As you	see, you can omit version numbers.  If multiple	versions are
	 installed, each of them is upgraded unless they share a port origin.
	 (For example you may probably have foo-1.02 and foo-1.03 recorded
	 somehow; run "pkgdb -F" to fix	the situation)

     +o	 Upgrade XFree86 and Mesa, passing -DWANT_GGI to make(1) for Mesa:

	       portupgrade XFree86 -m '-DWANT_GGI' Mesa

	 -m / --make-args is the option	to specify options to pass to make(1).

     +o	 Upgrade all the GNOME packages, keeping build logs in

	       portupgrade -L /var/tmp/portupgrade-%s::%s.log '*gnome*'

	 You can use the wildcards as in sh(1).	 Perl compatible extended reg-
	 ular expressions are also available by	prepending a colon `': to a
	 pattern.  In the above	case, you could	type: :gnome.

	 -L / --log-prefix is the option to tell portupgrade to	keep the build
	 log as	a file for each	port build.  Regardless	of the option,
	 portupgrade always watches the	build output of	each port and when a
	 build fails it	guesses	the reason why it has failed.

     +o	 Upgrade sawfish and all that sawfish depends on, building binary
	 packages for the upgraded packages, with the verbose mode on:

	       portupgrade -Rpv	sawfish

	 -R / --upward-recursive is the	option to tell portupgrade to recurse
	 upwards through dependencies.	In the above case, rep-gtk, librep,
	 imlib,	gnomelibs, XFree86 etc.	would be upgraded.

	 -p / --package	is the option to tell portupgrade to build a binary
	 package while it upgrades a package.

	 -v / --verbose	is the option to turn the verbose mode on.

     +o	 Upgrade glib and all that depend on it, confirming each upgrade:

	       portupgrade -ri glib

	 -r / --recursive is the option	to tell	portupgrade to recurse down-
	 wards through dependencies.  In the above case, gtk and all GNOME re-
	 lated packages	would be upgraded.

	 -i / --interactive is the option to tell portupgrade to ask you for
	 approval before performing something important.

     +o	 Rebuild and reinstall all ports that depend on	sdl, but not sdl it-

	       portupgrade -rfx	sdl sdl

	 -f / --force is the option to force portupgrade to upgrade a package
	 even if it does not seem to be	needed judging from a version compari-

	 -x / --exclude	is the option to specify an exclusion pattern.

     +o	 Rebuild and reinstall all that	ports that were	installed prior	to the
	 date 2001-09-20:

	       portupgrade -f '<2001-09-20'

	 You can also select packages by a date	range.

     +o	 Rebuild and reinstall all the dependent packages of png that were in-
	 stalled prior to png:

	       portupgrade -fr png -x '>=png'

	 You may use a package to specify a date.

     +o	 Fetch all the distfiles that are needed to upgrade all	the installed
	 packages at once, but do not upgrade anything yet:

	       portupgrade -aFR

	 -a / --all is equivalent to specifying	an `*'.

	 -F / --fetch is the option to tell portupgrade	to not upgrade any-
	 thing but just	fetch distfiles.

	 It is necessary to specify -R in addition to -a because some of the
	 upgraded ports	might require new ports	that are not installed yet.

     +o	 Replace ghostscript-gnu with ghostscript-afpl:

	       portupgrade -o print/ghostscript-afpl ghostscript-gnu

	 -o / --origin was originally the option to supply a missing origin of
	 an outdated package before FreeBSD 4.2, but this example shows	an-
	 other useful usage.  Use portupgrade like this, and all the dependen-
	 cies on the old package (ghostscript-gnu) will	be succeeded to	the
	 new one (ghostscript-afpl) cleanly, without leaving inconsistency.

     +o	 Upgrade glib using a package.	If necessary, download one from	a re-
	 mote ftp site:

	       portupgrade -P glib

	 -P / --use-packages is	the option to tell portupgrade to use packages
	 instead of ports where	available.

     +o	 Perform a massive binary upgrade using	the packages stored on a CD-
	 ROM, but before that, figure out what will be upgraded:

	       env PKG_PATH=/mnt/cdrom/packages/All portupgrade	-anPP

	 -n / --noexecute is the option	to tell	portupgrade not	to commit any
	 upgrade but just show what would be done.

	 Double	-P tells portupgrade to	use packages only; portupgrade will
	 not upgrade a package if a package file (*.tbz) to upgrade the	pack-
	 age with is not available.

	 If you	do not want portupgrade	to download packages which are not on
	 the CD-ROM, set PKG_FETCH to something	like "/bin/false".

     +o	 After performing a binary upgrade, it is strongly recommended that
	 you run "pkgdb	-F" to fix broken dependencies introduced by the newly
	 installed packages.

     +o	 Do a massive network binary upgrade:

	       portupgrade -aPPR

     +o	 When in doubt,	use the	portupgrade options such as -n and -i to see
	 what would be done, or	use pkg_glob(1)	to see how it expands glob

     +o	 To perform upgrades effectively and correctly,	remember to run
	 pkgdb(1) with -F on occasions to fix dependency discrepancies,	and
	 run portsdb(1)	with -Uu every time you	CVSup the ports	tree to	keep
	 your ports INDEX database up-to-date in sync with the tree.

     +o	 To check for available	upgrades, give portversion(1) a	try instead of
	 pkg_version(1).  It has comparable usage with pkg_version(1) but runs
	 much faster.  Also the	output script of "portversion -c" utilizes
	 portupgrade(1)	for upgrading.

     +o	 To deinstall packages,	give pkg_deinstall(1) a	try instead of
	 pkg_delete(1).	 It is a wrapper of pkg_delete(1) with additional fea-
	 tures,	such as	recursive deinstall and	shared library preservation.

     +o	 To clean unreferenced distfiles, working directories and old shared
	 libraries, use	portsclean(1).

     +o	 To track the change history of	a port,	use portsvnweb(1).

     PKG_DBDIR	       Alternative location for	the installed package data-
		       base.  Default is "/var/db/pkg".

     PORTSDIR	       Alternative location for	the ports tree.	 Default is

     PORTS_INDEX       Alternative location for	the ports INDEX	file.  Default
		       is "$PORTSDIR/INDEX".

     PORTS_DBDIR       Alternative location for	the ports database files.  De-
		       fault is	"$PORTSDIR".

     TMPDIR	       (In that	order) Temporary directory where portupgrade
		       attempts	to create backup files.	 If neither is de-
		       fined, "/var/tmp" is used.  Note	that this directory
		       must have enough	free space when	upgrading a big	pack-
		       age. (See the TECHNICAL DETAILS above)

     PACKAGES	       Base directory where portupgrade	creates	packages.  De-
		       fault is	"$PORTSDIR/packages".

     PKG_PATH	       A list of directories where portupgrade searches	for
		       packages, separated by colons.  Default is

     PKG_SUFX	       Suffix for packages.  Default is	the value defined in or /etc/make.conf.

     PKGTOOLS_CONF     Configuration file for the pkgtools suite.  Default is

     PORTUPGRADE       Default options for portupgrade (e.g.  -v)

     UPGRADE_TOOL      The environment variable	is set to upgrade tool name.
		       Always is set to	"portupgrade".

     UPGRADE_PORT      The variable is set to a	port name and version (as PKG-
		       NAME make variable) which is upgraded.

     UPGRADE_PORT_VER  A version number	extracted from UPGRADE_PORT (it's the
		       same as in PKGVERSION make variable).

     /var/tmp			Temporary directory for	creating backup	files,
				if environmental variables PKG_TMPDIR or
				TMPDIR do not point to a suitable directory.

     /var/db/pkg		Default	location of the	installed package

     /usr/ports			Default	location of the	ports tree and the
				ports database files.

     /usr/ports/packages/All	Default	location of backup packages saved with

     $PREFIX/etc/pkgtools.conf	Default	location of the	pkgtools configuration

     pkg_add(1), pkg_deinstall(1), pkg_delete(1), pkg_glob(1), pkg_info(1),
     pkg_sort(1), pkgdb(1), portsvnweb(1), ports_glob(1), portsclean(1),
     portsdb(1), portversion(1), pkgtools.conf(5), ports(7)

     Akinori MUSHA <>
     Sergey Matveychuk <>
     Stanislav Sedov <>
     Bryan Drewery <>

     SUSP (^Z) does not	work during a build/install.

     Sometimes a database may get corrupt and the pkgtools commands start to
     abort due to segmentation fault.  In such cases, run "pkgdb -fu" to re-
     build the database, and the problems will go away.	 If the	command	failed
     itself, remove a database file (/var/db/pkg/pkgdb.db) and run it again.

     Some third-party or hand-made packages have invalid package names which
     make portupgrade and the related tools angry.  To completely hide the ex-
     istence of	a package from them, put (just touch(1)) a dummy file named
     "+IGNOREME" in the	package	directory.

FreeBSD				 June 17, 2013			       FreeBSD


Want to link to this manual page? Use this URL:

home | help