||FreeBSD General Commands Manual
tools to upgrade installed packages or install new ones via
ports or packages
portupgrade command is used to upgrade installed
packages via ports or packages. The
command is equivalent to
Before reading these instructions, you must understand that a
port/package can have the following two types of related ports/packages:
- Ports/packages that a port/package needs for it to be built and/or run.
Port Makefiles refer to this type of ports/packages using the
RUN_DEPENDS macros, respectively.
- Ports/packages that need this port/package.
portupgrade deals with multiple
packages, it automatically sorts the packages in dependency order using the
The following command line arguments are supported:
- Please read this manual page carefully and understand what you are doing
- When the tools suggest running “
-F”, run it. Upgrade a certain number of packages at once
with an inconsistent package database will surely cause bad results.
portupgrade allows you to upgrade your
installed packages without rebuilding and reinstalling dependent packages,
upgraded packages may occasionally cause binary incompatibilities. To cope
with this situation, use the
-R options as
- 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.
- Do not be lazy about backing up your precious data and configuration
files, including the package database in
- Specify one of these: a full pkgname, a pkgname without version, a shell
glob pattern in which you can use wildcards ‘*’,
‘?’, and an extended regular expression preceded by a colon
‘:’, or a date range specification preceded by either
‘<’ or ‘>’. See
for details and concrete examples.
- Show help and exit.
- Do with all the installed packages. Equivalent to specify
'*' as pkgname_glob.
- Run the specified command as root after each installation.
- Keep backup packages of the old versions.
- 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
interaction. Options dialogs will not be presented. Also see
for more details.
- 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'
portupgrade -B 'ports_glob -M
$(pwd) | (cd ../..; xargs cvs up)' slave/port
portupgrade -aB 'test ! `make -V
- Run “
make config-conditional” before
everything for all tasks.
- Run “
make config” before everything
for all tasks.
- Delete failed distfiles and retry if checksum fails. Specified twice, do
make distclean” before each fetch
- Emit summary info after each port processing.
- Force the upgrade of a package even if it is to be a downgrade or just a
reinstall of the same version, or the port is held by user using the
HOLD_PKGS variable in pkgtools.conf.
- Only fetch distfiles or packages (if
specified), 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.
- Do not read MOVED file.
- Turn on interactive mode. You are asked for approval before each suggested
installation or upgrade. This option implies
- Force the upgrade of a package even if some of the requisite packages have
failed to upgrade in advance.
- Specify a file name to save the results to. By default,
portupgrade does not save results as a file.
- Specify a
style format to determine the log file name for each port.
“%s::%s” is appended if it does not contain a
‘%’. Category and portname are given as arguments, in the
- Specify arguments to append to each
- Specify arguments to prepend to each
- Do not actually install, upgrade or fetch any packages; just show what
would be done. This option implies
-v and negates
- Install a new port/package when a specified package is not installed.
Prior to the installation a new port/package, all the required packages
If this option is specified, you can specify a portorigin glob
as well as a pkgname glob to specify which port to install. See
for the details of the ‘portorigin glob’.
This option makes
as if it were called as
- Specify a port to upgrade the following package with.
- Omit sanity checks for dependencies. By default,
portupgrade checks if all the packages to upgrade
have consistent dependencies, though it takes extra time to calculate
dependencies. If you are sure you have run “
-F” in advance, you can specify this option to omit the
- Build a package when each specified port is installed 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 instead of ports whenever available.
portupgrade searches the local directories listed
PKG_PATH for each package to install or upgrade
the current installation with, and if none is found,
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 pkgtools.conf.
- Never use the port even if a package is not available either locally or
remotely, although you still have to keep your ports tree up-to-date so
portupgrade can check out what the latest
version of each port is.
- Do not display a message when -N specified and there is already installed
- Do not read the configuration file -
- Act on all those packages depending on the given packages as well.
- Act on all those packages required by the given packages as well. (When
-F, fetch recursively, including
the brand new, uninstalled ports that an upgraded port requires)
- Run commands under
- Specify an alternative to
e.g. “'su root -c %s '” (default:
- Do not preserve old shared libraries. By default,
portupgrade preserves shared libraries on
uninstallation for safety. See the
manpage and check out the
-P option for details.
- Turn on verbose output.
- Do not “
make clean” before each
- Do not “
make clean” after each
- Do not set UPGRADE_* environment variables.
- Exclude packages matching the specified glob pattern. Exclusion is
performed after recursing dependency in response to
-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
- Answer yes to all the questions. This option implies
-v and negates
portupgrade upgrades installed packages via ports or
packages without necessarily having to reinstall required or dependent
packages by adjusting the package registry database.
The procedures it takes are briefly shown as below:
-P is not given, jump to 4.
Otherwise search the local directories listed in
PKG_PATH for a newer package tarball. If found,
jump to 5.
- Fetch the latest package from a remote site using
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 installation, jump to
-P is given twice (i.e.
-PP), stop the task.
- Build the corresponding port of the given installed package.
- Fix the dependency information of the packages that depend on the given
- Back up the current installation of the given package using
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 ENVIRONMENT section to know where) to save the backup tarball.
(Perhaps a new option to omit backups will be added in the future)
- Back up the current package registration files of the given package.
- Uninstall the given package forcibly, preserving shared libraries unless
-u is specified.
- Install the new version via ports or packages, depending on the conditions
in 1, 2 and 3.
- If the installation fails,
- Restore the old installation backed up in 6.
- Restore the old package registration files backed up in
- Revert the dependency information fixed in 5.
- Remove the dependencies obsoleted in this upgrade.
- Run “
portsclean -L” to delete
duplicate libraries and put away old libraries.
- Run “
pkgdb -aF” to fix up stale
dependencies and reconstruct +REQUIRED_BY
- Upgrade 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
- Upgrade XFree86 and Mesa,
portupgrade XFree86 -m
--make-args is the option to specify options to
- Upgrade all the GNOME packages, keeping build logs in
You can use the wildcards as in
Perl compatible extended regular expressions are also available by
prepending a colon ‘’: to a pattern. In the above case,
you could type: :gnome.
--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
- Upgrade sawfish and all that sawfish depends on,
building binary packages for the upgraded packages, with the verbose mode
--upward-recursive is the option to tell
portupgrade to recurse upwards through
dependencies. In the above case, rep-gtk,
gnomelibs, XFree86 etc.
would be upgraded.
is the option to tell
portupgrade to build a
binary package while it upgrades a package.
is the option to turn the verbose mode on.
- Upgrade glib and all that depend on it, confirming
portupgrade -ri glib
--recursive is the option to tell
portupgrade to recurse downwards through
dependencies. In the above case, gtk and all GNOME
related packages would be upgraded.
--interactive is the option to tell
portupgrade to ask you for approval before
performing something important.
- Rebuild and reinstall all ports that depend on sdl,
but not sdl itself:
portupgrade -rfx sdl
is the option to force
portupgrade to upgrade a
package even if it does not seem to be needed judging from a version
is the option to specify an exclusion pattern.
- Rebuild and reinstall all that ports that were installed prior to the date
You can also select packages by a date range.
- Rebuild and reinstall all the dependent packages of
png that were installed prior to
portupgrade -fr png -x
You may use a package to specify a date.
- Fetch all the distfiles that are needed to upgrade all the installed
packages at once, but do not upgrade anything yet:
equivalent to specifying an ‘*’.
is the option to tell
portupgrade to not upgrade
anything but just fetch distfiles.
It is necessary to specify
-a because some of the upgraded
ports might require new ports that are not installed yet.
- Replace ghostscript-gnu with
was originally the option to supply a missing origin of an outdated
package before FreeBSD 4.2, but this example
shows another useful usage. Use
this, and all the dependencies on the old package
(ghostscript-gnu) will be succeeded to the new one
(ghostscript-afpl) cleanly, without leaving
- Upgrade glib using a package. If necessary, download
one from a remote ftp site:
portupgrade -P glib
--use-packages is the option to tell
portupgrade to use packages instead of ports
- Perform a massive binary upgrade using the packages stored on a CD-ROM,
but before that, figure out what will be upgraded:
PKG_PATH=/mnt/cdrom/packages/All portupgrade -anPP
--noexecute is the option to tell
portupgrade not to commit any upgrade but just
show what would be done.
portupgrade to use packages only;
portupgrade will not upgrade a package if a
package file (*.tbz) to upgrade the package with
is not available.
If you do not want
download packages which are not on the CD-ROM, set
PKG_FETCH to something like
- After performing a binary upgrade, it is strongly recommended that you run
pkgdb -F” to fix broken
dependencies introduced by the newly installed packages.
- Do a massive network binary upgrade:
- When in doubt, use the
portupgrade options such as
-i to see what
would be done, or use
to see how it expands glob patterns.
- To perform upgrades effectively and correctly, remember to run
-F on occasions to fix dependency
discrepancies, and run
-Uu every time you CVSup the ports tree to
keep your ports INDEX database up-to-date in sync with the tree.
- To check for available upgrades, give
a try instead of
It has comparable usage with
but runs much faster. Also the output script of
portversion -c” utilizes
- To deinstall packages, give
a try instead of
It is a wrapper of
with additional features, such as recursive deinstall and shared library
- To clean unreferenced distfiles, working directories and old shared
- To track the change history of a port, use
- Alternative location for the installed package database. Default is
- Alternative location for the ports tree. Default is
- Alternative location for the ports INDEX file. Default is
- Alternative location for the ports database files. Default is
- (In that order) Temporary directory where
portupgrade attempts to create backup files. If
neither is defined, “/var/tmp” is
used. Note that this directory must have enough free space when upgrading
a big package. (See the TECHNICAL DETAILS above)
- Base directory where
portupgrade creates packages.
Default is “$PORTSDIR/packages”.
- A list of directories where
for packages, separated by colons. Default is
- Suffix for packages. Default is the value defined in
- Configuration file for the pkgtools suite. Default is
- Default options for
- The environment variable is set to upgrade tool name. Always is set to
- The variable is set to a port name and version (as PKGNAME make variable)
which is upgraded.
- A version number extracted from UPGRADE_PORT (it's the same as in
PKGVERSION make variable).
Akinori MUSHA ⟨knu@iDaemons.org⟩
- Temporary directory for creating backup files, if environmental variables
not point to a suitable directory.
- Default location of the installed package database.
- Default location of the ports tree and the ports database files.
- Default location of backup packages saved with -b.
- Default location of the pkgtools configuration file.
Sergey Matveychuk ⟨sem@FreeBSD.org⟩
Stanislav Sedov ⟨stas@FreeBSD.org⟩
Bryan Drewery ⟨bdrewery@FreeBSD.org⟩
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 rebuild 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
portupgrade and the related tools angry.
To completely hide the existence of a package from them, put (just
a dummy file named "+IGNOREME" in the package directory.
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.