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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PORTUPGRADE(1)          FreeBSD General Commands Manual         PORTUPGRADE(1)

     portupgrade, portinstall - tools to upgrade installed packages or install
     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/package 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/packages using the BUILD_DEPENDS and RUN_DEPENDS macros,
     dependent  Ports/packages that need this port/package.

     +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
         without 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 don't 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
                            regular expression preceded by a colon `:', or a
                            date range specification preceded by either `<' or
                            `>'.  See pkg_glob(1) for details and concrete

     --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

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

     --batch                Run an upgrading process in a batch mode (with

     -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

     --distclean            Delete failed distfiles and retry if checksum
                            fails.  Specified twice, do ``make distclean''
                            before 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
                            version, 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
                            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.

     --ignore-moved         Do not read MOVED file.

     --interactive          Turn on interactive mode.  You are asked for
                            approval before each suggested installation or
                            upgrade.  This option implies -v.

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

     -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 portname are given as arguments, in the order

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

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

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

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

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

     -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
                            extra 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
                            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         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 doesn't work either, the port
                            is used.

     --use-packages-only    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
                            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
                            uninstallation 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
                            pattern.  Exclusion is performed after recursing
                            dependency 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
                            implies -v and negates -n.

     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:

           1.   If -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.

           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
                installation, 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
                ENVIRONMENT section to know where) to save the backup tarball.
                (Perhaps a new option to omit backups will be added in the

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

           8.   Uninstall the given package forcibly, preserving shared
                libraries 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,

                      1.   Restore the old installation backed up in 6.

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

                      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

         When portupgrade deals with multiple packages, it automatically sorts
         the packages in dependency order before everything.

         -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
         regular 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
         downwards through dependencies.  In the above case, gtk and all GNOME
         related 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

               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

         -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
         installed 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
         anything 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
         another useful usage.  Use portupgrade like this, and all the
         dependencies on the old package (ghostscript-gnu) will be succeeded
         to the new one (ghostscript-afpl) cleanly, without leaving

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

               portupgrade -P glib

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

     +o   Let's perform a massive binary upgrade using the packages stored on a
         CD-ROM, but before that I want to 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 (*.tgz) to upgrade the
         package with is not available.

         If you don't 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
         features, such as recursive deinstall and shared library

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

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

     PKG_DBDIR         Alternative location for the installed package
                       database.  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.
                       Default is ``$PORTSDIR''.

     TMPDIR            (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)

     PACKAGES          Base directory where portupgrade creates packages.
                       Default 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
                       PKGNAME 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), portcvsweb(1), ports_glob(1), portsclean(1),
     portsdb(1), portversion(1), pkgtools.conf(5), ports(7)

     Akinori MUSHA <>
     Sergey Matveychuk <>

     SUSP (^Z) doesn't 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

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

FreeBSD                          June 15, 2001                         FreeBSD


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

home | help