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

FreeBSD Manual Pages


home | help
PORTMASTER(8)		  BSD System Manager's Manual		 PORTMASTER(8)

     portmaster	-- manage your ports without external databases	or languages

     Common Flags: [--force-config -CGHgntvw -[B|b] -[uf|i] -[D|d]]
     [-m arguments for make] [-x glob pattern to exclude from building]
     portmaster	[Common	Flags] full name of port directory in /var/db/pkg
     portmaster	[Common	Flags] full path to /usr/ports/foo/bar
     portmaster	[Common	Flags] glob pattern of directories from	/var/db/pkg

		PLEASE NOTE: Glob patterns now update every port that matches.
		This is	a change from pre-version-2.3 behavior.

     portmaster	[Common	Flags] Multiple	full names or paths from /usr/ports or
		/var/db/pkg, and/or multiple globs from	/var/db/pkg
     portmaster	[Common	Flags] -p port directory in /usr/ports
     portmaster	[Common	Flags]
		 . (Use	in /usr/ports/foo/bar to build that port)
     portmaster	--show-work [-Gv -m args] <single port,	as above>
     portmaster	[Common	Flags] -o _new port dir	in /usr/ports_ _installed
     portmaster	[Common	Flags] [-R] -r name/glob of port in /var/db/pkg
     portmaster	[Common	Flags] -a
     portmaster	-[l|L]
     portmaster	[-b -[D|d]] -e full name of port directory in /var/db/pkg
     portmaster	[-b -[D|d]] -s
     portmaster	--clean-distfiles
     portmaster	--clean-distfiles-all
     portmaster	--check-depends
     portmaster	-h|--help
     portmaster	--version

     The portmaster utility is a tool for updating your	ports.	It uses	no ex-
     ternal database to	track what you have installed.	Rather it uses the ex-
     isting ports infrastructure, including what is located in /var/db/pkg.
     The focus of this tool is to keep the dependency tracking information for
     your ports	up to date, which allows you to	update a specific port without
     having to update all of the ports "above" it.  In the rare	case where you
     do	need to	recompile ports	which depend on	a port you are updating, the
     -r	option exists to accomplish this.

     By	default	portmaster updates the port you	specify	on the command line
     whether there is a	new version for	it or not.  It will first recurse
     through the port and all of its dependencies (if any) to handle any port
     OPTIONS via the 'make config' interface.  You will	be presented with an
     OPTIONS dialog if you have	never built the	port before, or	if the OPTIONS
     have changed.  You	can force dialogs for all ports	by using the
     --force-config option.  It	will then start	building all ports that	need
     updating.	While recursing	through	dependencies, a	'make checksum'
     process will be launched in the background	to either verify that the cor-
     rect distfiles are	available, or start downloading	the new	ones.  If you
     stop portmaster with ^C, an attempt will be made to kill off the child
     processes started for this	purpose.

     If	the recursion through the ports	for 'make config' does not find	a port
     that needs	updating, the dependency check step will be skipped prior to
     building the port specified on the	command	line.  In addition to this op-
     timization, information about up-to-date dependencies, choices made on
     which ports to build for interactive mode,	and ports already visited for
     'make config' are all cached to enhance performance and prevent dupli-
     cated efforts.

     While recursing through the dependencies, if a port is marked IS_INTERAC-
     TIVE this will be flagged.	 In the	absence	of this	notification, under
     normal circumstances the only user	interaction required after the port
     starts building is	to answer questions about the deletion of stale	dist-
     files.  This can be eliminated with the -d	or -D options.

     While checking dependencies, if a port has	CONFLICTS set, the list	will
     be	checked	against	your installed ports, and if you have installed	an al-
     ternate version of	a port that is required	by the port you	are building,
     it	will be	used in	place of the default dependency.

     If	there is no -B option specified	when updating an existing port,	a
     backup package will be created before pkg_delete(1) is called.  If	you
     are using the -b option, these packages can be found in a directory
     called "portmaster-backup"	in the directory specified by the PACKAGES en-
     vironment variable, usually /usr/ports/packages.  If there	is no -b op-
     tion specified, the backup	package	will be	deleted	once the new version
     of	the port is successfully installed.  If	the installation fails for
     whatever reason, a	helpful	message	will be	printed, along with instruc-
     tions on where to find the	backup package.

     After the port is built, if the -w	option is being	used, all shared li-
     braries installed by the old port (if any)	will be	saved to
     /usr/local/compat/pkg.  After installation	if there are any new files
     with the same names as those in /usr/local/compat/pkg the old files will
     be	deleted, and ldconfig(8) will be run via /etc/rc.d/ldconfig.

     After the new port	is built, but before it	is installed the runtime de-
     pendencies	will be	checked	to make	sure they are up to date.  If the -g
     option is used, a package will be created for the new (or newly in-
     stalled) version.

     When installing a port or using the --check-depends option, if there are
     other ports that depend on	this port the dependent	ports +CONTENTS
     file(s), and the +REQUIRED_BY file	for the	new port will be updated.

     At	the conclusion of a successful installation, any pkg-message files
     that were installed, and a	summary	of the work performed will be dis-

     The options are as	follows:

	 run 'make config' for all ports (must be the first option)

     -B	 prevents creation of the backup package for the installed port

     -C	 prevents 'make	clean' from being run before building

     -G	 prevents the recursive	'make config' (overrides --force-config)

     -H	 hide details of the port build	and install in a log file

     -K	 prevents 'make	clean' from being run after building

     -b	 create	and keep a backup package of an	installed port

     -g	 create	a package of the new port

     -n	 run through configure,	but do not make	or install any ports

     -t	 recurse dependencies thoroughly, using	all-depends-list

     -v	 verbose output

     -w	 save old shared libraries before deinstall

     -u	 unattended mode -- accept defaults for	all but	'make config'

	 PLEASE	NOTE: Under most circumstances this option is not necessary,
	 and may produce unwanted results.  If you experience problems with
	 portmaster, please try	running	it without this	option first.

     [-R] -f
	 always	rebuild	ports (overrides -i)

     -i	 interactive update mode -- ask	whether	to rebuild ports

     -D	 no cleaning of	distfiles

     -d	 always	clean distfiles

     -m	arguments for make
	 any arguments to supply to make(1)

     -x	 avoid building	or updating ports that match this pattern

     -p	port directory in /usr/ports
	 specify the full path to a port directory

	 show what dependent ports are,	and are	not installed (implies -t).
	 This flag must	come first on the command line.

     -o	_new port dir in /usr/ports_ _installed	port_
	 replace the installed port with a port	from a different origin

     [-R] -r name/glob of port in /var/db/pkg
	 rebuild the specified port, and all ports that	depend on it

     -R	 restart an update, skipping ports already up to date.	Used with -r
	 or -f options.

     -a	 check all ports, update as necessary

     -l	 list all installed ports by category

     -L	 list all installed ports by category, and search for updates

     -e	name of	port directory in /var/db/pkg
	 expunge port using pkg_delete(1), and optionally remove all dist-
	 files.	 Calls -s after	it is done expunging in	case removing the port
	 causes	a dependency to	no longer be necessary.

     -s	 clean out stale ports that used to be depended	on

     -F	 fetch distfiles only.	Cannot be used with -G,	but may	be used	with
	 --force-config	and -[aftv].

	 recurse through the installed ports to	get a list of distinfo files,
	 then recurse through all files	in /usr/ports/distfiles	to make	sure
	 that they are still associated	with an	installed port.	 If not, offer
	 to delete the stale file.

	 does the same as above, but deletes all files without prompting.

	 cross-check and update	dependency information for all ports

	 display help message

	 display the version only.

     The directory pointed to by the PACKAGES variable (by default
     /usr/ports/packages) will be used to store	new and	backup packages.  When
     using 'make package' for the -g option, the ports infrastructure will
     store packages in /usr/ports/packages/All,	aka PKGREPOSITORY.  When using
     the -b option, portmaster stores its backup packages in
     /usr/ports/packages/portmaster-backup so that you can create both a
     backup package and	a package of the newly installed port even if they
     have the same version.

     The UPGRADE_TOOL variable is set to "portmaster", and the UPGRADE_PORT
     and UPGRADE_PORT_VER variables are	set to the full	package	name string
     and version of the	existing package being replaced, if any.

	   Optional system and user configuration files.  The variables	set in
	   the script's	getopts	routine	can be specified in these files	to en-
	   able	those options.	These files will be read by the	parent
	   portmaster process, and all variables in them will be exported.

	   PLEASE NOTE:	In versions before 2.3 /etc/portmaster.rc was recom-
	   mended.  However placing this file in LOCALBASE is the correct
	   thing to do.	 In future versions of portmaster support for
	   /etc/portmaster.rc will be removed.

	   Here	are examples of	variables that are likely to be	useful,	along
	   with	their related options.

	   # Sample portmaster rc file.
	   # Place in $HOME/.portmasterrc or /usr/local/etc/portmaster.rc
	   # Do	not create temporary backup packages before pkg_delete (-B)
	   # NO_BACKUP=Bopt
	   # Always save the backup packages of	the old	port (-b)
	   # BACKUP=bopt
	   # Make and save a package of	the new	port (-g)
	   # MAKE_PACKAGE=gopt
	   # Do	not preclean the port's	build directory	(-C)
	   # Do	not clean the port's build directory after installation	(-K)
	   # Never search for stale distfiles to delete	(-D)
	   # Always delete stale distfiles without prompting (-d)
	   # Do	not run	'make config' for ports	that need updating (-G)
	   # (This unsets --force-config)
	   # Hide the build and	install	processes in a log file	(-H)
	   # HIDE_BUILD=Hopt
	   # Arguments to pass to make (-m)
	   # Recurse through every dependency, and child dependencies (-t)
	   # Be	verbose	(-v)
	   # Save copies of old	shared libraries (recommended) (-w)
	   # SAVE_SHARED=wopt

	   If this file	exists,	several	things will happen:

	   1. The port will be ignored for all purposes, including
	       dependency updates, if there is no directory for	it in
	       /usr/ports, and there is	no entry for it	in /usr/ports/MOVED.
	       If the -v option	is used, the fact that the port	is being ig-
	       nored will be mentioned.

	   2. If using the
	       -L option, and a	new version exists, the	existence of the
	       +IGNOREME file will be mentioned.

	   3. If you do	a regular update of the	port, or if the
	       -a option is being used,	you will be asked if you want to up-
	       date the	port anyway; unless the	-u option is being used, in
	       which case the port will	be ignored.

	   Indicates to	a subsequent -f	or -r run which	includes the -R	option
	   that	a port has already been	rebuilt, so it can be safely ignored
	   if it is up to date.
	   If the -H option is used, and the installation or upgrade is	not
	   successful, the results of the build	and install will be saved in
	   this	file.  Substitute the value of TMPDIR in your environment as

     The portmaster utility exits 0 on success,	and >0 if an error occurs.

     The ports infrastructure has limited support for performing various oper-
     ations as an unpriviliged user.  It does this by defining SU_CMD, which
     is	typically su(1).  In order to support complete management of your
     ports as an unprivileged user, escalating to "root" privileges only when
     necessary,	portmaster can use sudo(1) to handle the escalated privileges.
     To	accomplish this	you must have the following directories	configured so
     that the unprivileged user	can access them:

     1.	WRKDIRPREFIX - This is usually set to /usr/ports/category/port/work,
	 however it is suggested that you configure another directory outside
	 your ports tree for access by the unprivileged	user, and assign this
	 variable to that value	in your	/etc/make.conf.

     2.	DISTDIR	- This is usually set to /usr/ports/distfiles.
	 This directory	can be safely set up for access	by the unprivileged
	 user, or a new	directory can be specified as above.

     3.	TMPDIR - Usually /tmp,
	 but can also be set to	another	directory in your shell	environment if

     It	is further assumed that	the following directories will be owned	by



     LOCALBASE - Usually /usr/local

     PACKAGES -	Usually	/usr/ports/packages


     You will then need	to install and configure sudo(1).  This	can easily be
     done with /usr/ports/security/sudo.  Then you will	need to	define
     PM_SU_CMD in your /etc/portmaster.rc file,	or your	$HOME/.portmasterrc
     file.  For	example:


     You can optionally	define the PM_SU_VERBOSE option	as well	to notify you
     each time portmaster uses the PM_SU_CMD.  This is particularly useful if
     you are experimenting with	a tool other than sudo(1) to handle the	privi-
     lege escalation, although at this time sudo(1) is the only	supported op-

     PLEASE NOTE: You cannot upgrade the sudo(1) port itself using this

     The following are examples	of typical usage of the	portmaster command:

	   portmaster fooport-1.23
	   portmaster fooport
	   portmaster fooport-1.23 barport-4.56
	   portmaster -p /usr/ports/foo/fooport
	   portmaster foo/fooport
	   portmaster -r fooport-1.23
	   portmaster -o emulators/linux_base-fc4 linux_base-8-8.0_15
	   portmaster -x cvsup -f -a

     Print only	the ports that have available updates.	This can be used as an
     alias in your shell.  Be sure to fix the line wrapping appropriately.
	   portmaster -L |
	   egrep -B1 '(ew|ort) version|Aborting|installed|dependencies|
	   IGNORE|marked|Reason:|MOVED'	| grep -v '^--'

     Using portmaster to do a complete reinstallation of all your ports:
	   1. portmaster -l > ~/installed-port-list
	   2. Update your ports	tree
	   3. portmaster --clean-distfiles-all
	   4. portmaster -Faf
	   5. pkg_delete '*'
	   6. rm -rf /usr/local/lib/compat/pkg
	   7. Manually check through /usr/local	to make	sure it	is really

	   Now look at the list	you generated in the first step	and install
	   all the root	and leaf ports that you	want to	have again. The	trunk
	   and branch ports are	dependencies, and will automatically be
	   installed as	needed.	 You probably want to use the -D option	for
	   the installations and then run --clean-distfiles-all	again when
	   you are done.

     make(1), pkg_delete(1), su(1), ports(7), ldconfig(8), sudo(8)

     This manual page was written by Doug Barton <>.

BSD				 July 28, 2008				   BSD


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

home | help