FreeBSD Handbook
Prev | Chapter 4 Installing Applications: Packages and Ports | Next

# 4.4 Using the Packages System

Contributed by Chern Lee.

There are several different tools used to manage packages on FreeBSD:

- The `sysinstall` utility can be invoked on a running system to install, delete, and list available and installed packages. For more information, see Section 2.10.11.

- The package management command line tools, which are the subject of the rest of this section.

## 4.4.1 Installing a Package

You can use the pkg_add(1) utility to install a FreeBSD software package from a local file or from a server on the network.

Example 4-1. Downloading a Package Manually and Installing It Locally

    # ftp -a ftp2.FreeBSD.org
    Connected to ftp2.FreeBSD.org.
    220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready.
    331 Guest login ok, send your email address as password.
    230-
    230-     This machine is in Vienna, VA, USA, hosted by Verio.
    230-         Questions? E-mail freebsd@vienna.verio.net.
    230-
    230-
    230 Guest login ok, access restrictions apply.
    Remote system type is UNIX.
    Using binary mode to transfer files.
    ftp> cd /pub/FreeBSD/ports/packages/sysutils/
    250 CWD command successful.
    ftp> get lsof-4.56.4.tgz
    local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
    200 PORT command successful.
    150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
    100% |**************************************************| 92375       00:00 ETA
    226 Transfer complete.
    92375 bytes received in 5.60 seconds (16.11 KB/s)
    ftp> exit
    # pkg_add lsof-4.56.4.tgz

If you do not have a source of local packages (such as a FreeBSD CD-ROM set) then it will probably be easier to use the `-r` option to pkg_add(1). This will cause the utility to automatically determine the correct object format and release and then fetch and install the package from an FTP site.

    # pkg_add -r lsof

The example above would download the correct package and add it without any further user intervention. If you want to specify an alternative FreeBSD Packages Mirror, instead of the main distribution site, you have to set the `PACKAGESITE` environment variable accordingly, to override the default settings. pkg_add(1) uses fetch(3) to download the files, which honors various environment variables, including `FTP_PASSIVE_MODE`, `FTP_PROXY`, and `FTP_PASSWORD`. You may need to set one or more of these if you are behind a firewall, or need to use an FTP/HTTP proxy. See fetch(3) for the complete list. Note that in the example above `lsof` is used instead of `lsof-4.56.4`. When the remote fetching feature is used, the version number of the package must be removed. pkg_add(1) will automatically fetch the latest version of the application.

> Note: pkg_add(1) will download the latest version of your application if you are using FreeBSD-CURRENT or FreeBSD-STABLE. If you run a -RELEASE version, it will grab the version of the package that was built with your release. It is possible to change this behavior by overriding `PACKAGESITE`. For example, if you run a FreeBSD 5.4-RELEASE system, by default pkg_add(1) will try to fetch packages from `ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-5.4-release/Latest/`. If you want to force pkg_add(1) to download FreeBSD 5-STABLE packages, set `PACKAGESITE` to `ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-5-stable/Latest/`.

Package files are distributed in `.tgz` and `.tbz` formats. You can find them at ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/, or on the FreeBSD CD-ROM distribution. Every CD on the FreeBSD 4-CD set (and the PowerPak, etc.) contains packages in the `/packages` directory. The layout of the packages is similar to that of the `/usr/ports` tree. Each category has its own directory, and every package can be found within the `All` directory.

The directory structure of the package system matches the ports layout; they work with each other to form the entire package/port system.

## 4.4.2 Managing Packages

pkg_info(1) is a utility that lists and describes the various packages installed.

    # pkg_info
    cvsup-16.1          A general network file distribution system optimized for CV
    docbook-1.2         Meta-port for the different versions of the DocBook DTD
    ...

pkg_version(1) is a utility that summarizes the versions of all installed packages. It compares the package version to the current version found in the ports tree.

    # pkg_version
    cvsup                       =
    docbook                     =
    ...

The symbols in the second column indicate the relative age of the installed version and the version available in the local ports tree.

Symbol | Meaning
--- | ---
= | The version of the installed package matches the one found in the local ports tree.
< | The installed version is older than the one available in the ports tree.
> | The installed version is newer than the one found in the local ports tree. (The local ports tree is probably out of date.)
? | The installed package cannot be found in the ports index. (This can happen, for instance, if an installed port is removed from the Ports Collection or renamed.)
* | There are multiple versions of the package.
! | The installed package exists in the index but for some reason, `pkg_version` was unable to compare the version number of the installed package with the corresponding entry in the index.

## 4.4.3 Deleting a Package

To remove a previously installed software package, use the pkg_delete(1) utility.

    # pkg_delete xchat-1.7.1

Note that pkg_delete(1) requires the full package name and number; the above command would not work if `xchat` was given instead of `xchat-1.7.1`. It is, however, easy to use pkg_version(1) to find the version of the installed package. You could instead simply use a wildcard:

    # pkg_delete xchat\*

in this case, all packages whose names start with `xchat` will be deleted.

## 4.4.4 Miscellaneous

All package information is stored within the `/var/db/pkg` directory. The installed file list and descriptions of each package can be found within files in this directory.

Prev | Home | Next
Finding Your Application | Up | Using the Ports Collection

This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.