Desktop-installer: Use your Cleverness for Creativity
How would you like to spend minimal time setting up your workstation
or laptop, and most of it doing creative work? This is the
design goal of desktop-installer, and FreeBSD helps make it possible.
The core purpose of desktop-installer is to help you quickly and easily
create the most reliable and secure desktop system available, so you can
spend your time on productive work rather than tedious systems management.
FreeBSD provides the vast majority of the features necessary to make a great
desktop system for
WEB browsing, editing documents, playing music and videos, developing
software, and much more. It also offers solid support for most popular PC
hardware. However, fully configuring a stock FreeBSD desktop system by hand
is a bit like assembling a 1,000-piece jigsaw puzzle. Unless your goal is
to learn how to integrate the components of a Unix desktop environment, manual
configuration would not be a good use of your valuable time.
There are some important issues that new FreeBSD users are unlikely to know
about, such as ensuring that your ports tree and packages are in sync, how to
correctly configure devd, sound devices and graphics drivers, to name a few.
Desktop-installer is a post-install script that embodies the extensive
knowledge needed to configure a clean, reliable FreeBSD desktop system.
the process of configuring a FreeBSD workstation or laptop computer, allowing
typical users to set up a fully functional desktop environment in less than an
More than a dozen popular desktop environments and window managers are
explicitly supported and any other can be configured with relative ease
using the "Custom" option.
Desktop-installer installs and configures desktop-independent tools
and features, such as
a GUI application that is automatically launched when removable media
The VirtualBox guest
environment is automatically detected and configured with the VirtualBox
guest additions, so you can easily try out desktop-installer
even if you don't have a spare PC. Parallels and VMWare Fusion are also
automatically detected and configured with a basic graphics setup. Hyper V
can also run FreeBSD, but in our experience it is slow and unreliable.
Windows users are advised to install VirtualBox instead. Note that Hyper V
should be disabled via Control Panel if you are running a different
Desktop-installer is strictly a configuration tool, i.e. a convenient user
interface for integrating standard FreeBSD tools and ports. Unlike most
desktop distributions built on FreeBSD and Linux, desktop-installer does not
duplicate components of or add components to the FreeBSD base. Our goal is to
work with the underlying operating system, not around it, integrating the many
features already provided by FreeBSD to create a fast, stable, and secure
Any general enhancements made to FreeBSD for the sake of desktop-installer
will be desktop-independent and available via the ports collection for use
with or without desktop-installer.
One of the primary objectives
of desktop-installer is long-term sustainability. Since man-hours are costly,
efforts are focused on
improving the functionality of the end-result, not the appearance of the tool.
Desktop-installer does not try to compensate for FreeBSD's shortcomings.
We prefer to leave them exposed so that there is motivation to fix them in
the FreeBSD base or ports system.
Desktop-installer will not impose any arbitrary limitations.
While the GUI distributions tend to support only AMD64 systems running the
latest FreeBSD release, desktop-installer allows you to use any supported
version of FreeBSD on any supported CPU architecture. ARM, PowerPC,
RISC-V and Sparc are treated no differently than x86. Desktop-installer is
tested on an iMac G5 and a Rock 64, in addition to numerous x86 PCs and
laptops. While we can't guarantee that all
ports/packages will work on all platforms, desktop-installer
won't stand in your way.
How it Works
The desktop-installer script installs necessary ports/packages, configures
the graphical desktop of your choice and
performs basic setup for devices and services such as devd, WiFi, sound,
Bluetooth, printing and remote login.
Using desktop-installer, a typical desktop system can
be fully configured and ready to use in less than an hour on reasonably
modern hardware with a reasonably fast Internet connection.
Some user input is required, but desktop-installer should provide
sufficient guidance. You should not have to search the web for complicated
instructions on configuring software and services.
Anything that does not work out-of-the-box is considered a bug and should
The end-user is only expected to run desktop-installer and answer the
Is FreeBSD the Right OS for your Desktop?
Should you use FreeBSD + desktop-installer, GhostBSD, Ubuntu Linux,
one of the many
other open source options, or just get a Mac? It depends on your specific
preferences, of course. If you're not sure and you want to increase your
odds of getting it right the first time, check out
our mostly unbiased summary of the topic.
Desktop-installer is meant for people with a little Unix experience who want
freedom to configure a stock FreeBSD system, but don't want (or can't afford)
to spend time on
tedious systems setup tasks like configuring Xorg, USB device support,
WiFi drivers, CUPS printing services, NTP, EXFAT support, etc.
One of the goals is to help budding Unix gurus take the next step beyond
point-and-click systems and begin to learn more about the internals of a
traditional Unix system. Desktop-installer helps you set up such a system
quickly and securely, so you have a usable system where you can learn at
your own pace while getting other work done.
Examples of users likely to benefit from using desktop-installer:
Unix developers who prefer to spend their time on creative work rather
than configuring their desktop environment
Sysadmins doing mass-deployments of Unix desktop systems
Server admins who want a simple GUI in the data center
Anyone who is ready to move beyond the limitations of a point-and-click
system aimed at novice users
Anyone who can benefit from the unique features and reliability of FreeBSD
Configuring your Desktop System
FreeBSD supports two major releases at any given time, currently 12.x and 13.x.
We strongly recommend using the latest major FreeBSD release for desktop
systems. Legacy releases may be preferred for certain server applications,
but they may not have the latest device drivers and base libraries needed
for some desktop applications.
First perform a basic FreeBSD installation by booting from an install
CD, DVD, or USB drive. The standard FreeBSD installer, BSDInstall, is
easy to use and flexible enough for most installations. Use one of the
images at https://ftp.freebsd.org/pub/FreeBSD/releases/ISO-IMAGES/
or one of the mirrors, ftp2, ftp3, etc.
To install from a USB stick, download the a ".img" image file and
image the USB drive with it. Under Windows, you can use a tool such as
Rufus. On Unix systems (including macOS), you can use the dd command.
Replace "file.img" with the name of the file you downloaded and
"/dev/da0" with the name of the device that appears in /dev when you plug in
a USB stick.
dd if=file.img of=/dev/da0 bs=64k conv=sync
If installing from a CD/DVD drive or installing on a virtual machine,
download a .iso image. Use CD/DVD burning software to burn a disc for
real hardware, or just load the .iso into the virtual CD/DVD drive in
the virtual machine. A -disc1.iso file is a generally a good choice.
The -disc1.iso.xz files will download faster and can be uncompressed
with "unxz" if you have it. Choose "amd64" for an x86-based PC, or
"aarch64" for a VM on ARM-based Macs.
Boot from the USB stick or CD/DVD drive and follow the instructions on
the screen to install FreeBSD. This can be completed in a few minutes
by experienced users, but your first time through, you should take your
time and read all instructions carefully.
Desktop-installer will install and replace base components as needed, but
you can speed up the process by making the following choices during the OS
Install the src component, since it is required by some ports that build
DO NOT INSTALL A PORTS TREE AT THIS STAGE. The ports tree in the install
images will need to be replaced by a git clone anyway, so don't waste your
Do not add users. You can use the more user-friendly auto-admin menu
for this after running desktop-installer.
If installing under VirtualBox, we DO NOT recommend using the VM images
provided by FreeBSD. A fresh install from the disc1 ISO image can be
completed in under 5 minutes, so a preconfigured VM image doesn't offer much
convenience. A fresh install also allows you to configure your VM settings,
disk size, and base FreeBSD installation as you want instead of figuring out
how to modify the preconfigured VM image.
Also important for VirtualBox: Use the vboxsvga virtual GPU rather than
vmsvga. At the time of this writing, it works better with VirtualBox guest
additions for features such as automatic screen resize.
Lastly, adjusting the boot order of the VM will make the guest OS
installation a bit smoother. Configure the VM to boot from hard
disk first, then optical disk (you will use a .iso file for install).
The VM will then boot from the .iso image during install, and from
the virtual hard disk after install.
If you have a high-end machine with 4 or more GiB of RAM, you may want to
try booting from ZFS. BSDinstall makes booting from ZFS easy whether
you are using a single disk, a mirror, or a RAID-Z array with multiple disks.
For low-end machines with less than 4 GiB of RAM, UFS2, with its small memory
footprint, may provide better overall performance.
UFS2 is a highly underrated file system offering great performance,
reliability, and features,
so don't think you're missing out by not using ZFS. ZFS is most
beneficial to high-end storage servers and usually not much of an advantage
on the average laptop or desktop machine.
BSDInstall is menu-driven and fairly self-explanatory if you
take default options, but if you want to customize your installation or if
you're new to operating system installations and want detailed instructions,
you can find them in the
Below are some basic pointers to get you through without all the gory
If installing under VirtualBox:
Select the VBoxSVGA video adapter
Load the FreeBSD disc1 or other ISO file into the virtual CDROM
1G RAM is sufficient
Accept default answers to most questions.
A few pointers:
Full hostname, e.g. freebsd13.local, freebsd13.my.domain
Don't bother with ports, will install later
Installing src now will save a little time
Auto (UFS) for most installs, ZFS for high-end systems
Entire disk, GPT for most systems
If installing on real hardware:
Enable ntpdate, ntpd, powerd
Whether real hardware or virtual machine:
Enable moused (solves problems with various mouse drivers)
Add users: no (auto-admin does this better)
If installing under VirtualBox:
It's hard to eject CD fast enough after Reboot
Use ACPI shutdown in Machine menu instead, then eject virtual CD
After completing the installation and rebooting, log in as root
and install the desktop-installer port or package:
pkg install -y desktop-installer
Run desktop-installer as the root user and follow the instructions on the
Note that desktop-installer will halt on most errors. This is
fairly rare, but it can happen. Broken ports/packages are the most common
cause of this. If you run into any problems while running desktop-installer,
resolve the problem manually, and simply run desktop-installer again. It
will remember your previous answers, so you can quickly get back to where you
The script begins with
some basic questions about how you want your system configured, and then
runs unattended while installing the desktop system and other common
software. After the desktop environment is installed, it will ask a few
more questions about configuring your graphics environment and some typical
optional software and services.
Selecting a desktop during setup...
Most popular desktop environments and a few window managers are explicitly
supported. You can also use any other DE or WM in the FreeBSD ports tree
by selecting "Custom".
To use "Custom", you need only know the category/portname of the desktop you
want, and the command for starting the desktop from xinit or xsession,
e.g. start-lumina-desktop for the Lumina desktop. This command can be found
in category/portname/pkg-plist. The only other advantage to explicitly
supported desktops is automatic installation of a few common utilities, such
as qpdfview and qterminal for Lumina. You can easily install the utilities
you want using "pkg install" or "auto-admin" after a Custom desktop install.
Typically less than an hour later...
Maintaining your Desktop System
Many common tasks, including some described below, can be performed via
the auto-admin menu. Simply run "auto-admin"
and select an option.
Subscribe to the FreeBSD
security notifications list. This is a spam-free, very low-volume
email list to notify users about important security updates for FreeBSD.
Typically a small group of security fixes are announced once every few
Update your system frequently using "auto-update-system" (also available
in the auto-admin menu). This script,
automatically installed as a dependency of desktop-installer,
ensures that your installed packages, ports tree, and base system are
and that the ports tree and installed packages remain in sync.
With no command-line options, it runs interactively. To update everything
unattended, run "auto-update-system --defaults" or
"auto-update-system --yes" (same as --defaults + reboot).
Run "auto-update-system --help" for more details.
Most software on FreeBSD systems is installed from the FreeBSD ports
collection. The ports system allows you to quickly install pre-built
binary packages, or just as easily (but slowly) build from source with
build options such as additional compiler optimizations or optional
features. FreeBSD's ability to automatically install from source also
you to cleanly and easily install software whose license forbids
redistribution as a binary package.
To install a binary package, use "pkg install package-name".
To build from source, use "cd /usr/ports/category/package-name && make install".
Run "man ports" and "man pkg", or browse the
for additional info.
You can browse the ports collection on the
via the auto-admin menu to list all available binary packages in a
Note: Your currently
installed packages should be reasonably up-to-date before installing new
software. The system does a good job ensuring that appropriate versions
of dependencies are installed, but if your installed packages are months old,
you may encounter problems.
FreeBSD has strong default security settings and is immune to most malware,
but even a technically secure system is only as safe as your own habits.
Secure your password and change it
Be careful about running arbitrary software downloaded from the web
or from a USB stick.
Installing all of your software via FreeBSD ports adds a strong layer of
security, but not a guarantee.
Back up your important files regularly, preferably off-site. It's easy
to do using rsync
or one of the backup tools available in the FreeBSD ports collection.
If your disk fails, just install a new disk, quickly rebuild your system
using desktop installer again, and restore your files.
Use the auto-admin menu to manage user accounts. Be sure to add new users
to the "wheel" group to allow "su" to root, the "operator" group to allow
use of "shutdown", and the "video" group to ensure optimal graphics
At this stage, the main focus of desktop-installer development is improving
reliability and usability. We want desktop-installer to be the most
trouble-free experience you've ever had with setting up a desktop system.
We're not there yet, but we're moving fast in that direction.
No major new features
are planned, but new desktop environments and window managers may be added
to the menu.
Source code and problem reports are available on