Available Languages: | Deutsch | English | Español | Français | 日本語 (Nihongo) | Português | Русский (Russkiy) | 中文 (简) (Simplified Chinese) |

Running X11 on Darwin and Mac OS X

This document is about running X11 on Apple's Mac OS X and Darwin systems. It gives an introduction and a history of development, then goes on to describe the current situation and the X11 options available.


1 Introduction

1.1 What is X11?

The X Window System Version 11, or X11 for short, is a graphics display system with a network-transparent client-server architecture. It allows applications to draw pixels, lines, text, images, etc. on your screen. X11 also comes with additional libraries that let applications easily draw user interfaces, i.e. buttons, text fields, and so on.

X11 is the de facto standard graphics system in the Unix world. It comes with Linux, the *BSDs and most commercial Unix flavors. Desktop environments like CDE, KDE and GNOME run on top of it.

1.2 What is Mac OS X?

Mac OS X is an operating system produced by Apple. Like its predecessors NeXTStep and OpenStep, it is based on BSD and is thus a member of the Unix OS family. However, it comes with a proprietary graphics display system. The graphics engine is called Quartz and the look and feel is called Aqua, although the two names are often used intercheangably.

1.3 What is Darwin?

Darwin is basically a stripped-down version of Mac OS X that is available free of charge and with full source code. It does not contain Quartz, Aqua, or any other related technology. By default, it only offers a text console.

1.4 What is XFree86?

XFree86 is an open source implementation of X11. It was initially developed to run on Intel x86 PCs, hence the name. Nowadays, it runs on many architectures and operating systems, including OS/2, Darwin, Mac OS X and Windows.

Apple's X11 distributions on OS 10.2, 10.3 and 10.4 are derived from XFree86.

1.5 What is X.org?

X.org is an open source implementation of X11, and a successor to XFree86. It has supplanted XFree86 in most places.

Apple's X11 distributions on OS 10.5 and 10.6 are derived from X.org, as is XQuartz. Apple's X11 distribution on 10.7 is derived, in turn, from XQuartz.

1.6 What is XQuartz?

XQuartz is an X11 distribution for OS 10.5 and later which contains newer features than does the stock X11 on 10.5-10.7. On 10.5, XQuartz replaces the system's X11 distribution, whereas on 10.6 and 10.7 Xquartz and the system's X11 distribution coexist by installing in different base paths. On 10.8 Xquartz is the standard X11 distribution.

1.7 Client and Server

X11 has a client-server architecture. There is one central program that does the actual drawing and coordinates access by several applications; that is the server. An application that wants to draw using X11 connects to the server and tells it what to draw. Thus applications are called clients in the X11 world.

X11 allows the server and the clients to be on different machines, which often results in confusion over the terms. In an environment with workstations and servers, you will run the X11 display server on the workstation machine and the applications (the X clients) on the server machine. So when talking about the "server", that means the X11 display server program, not the machine hidden in your wardrobe.

1.8 What does rootless mean?

A little background: X11 models the screen as a hierarchy of windows contained in each other. At the top of the hierarchy is a special window which is the size of the screen and contains all other windows. This window contains the desktop background and is called the "root window".

Now back on topic: Like any graphical environment, X11 was written to stand alone and have full control over the screen. In Mac OS X, Quartz already governs the screen, so one must make arrangements if both are to get along together.

One arrangement is to let the two take turns. Each environment gets a complete screen, but only one of them is visible at a time and the user can switch between them. This is called full-screen or rooted mode. It is called rooted because there is a perfectly normal root window on the X11 screen that works like on other systems.

Another arrangement is to mix the two environments window by window. This eliminates the need to switch between two screens. It also eliminates the X11 root window, because Quartz already takes care of the desktop background. Because there is no (visible) root window, this mode is called "rootless". It is the most comfortable way to use X11 on Mac OS X.

1.9 What is a window manager?

In most graphical environments the look of window frames (title bar, close button, etc.) is defined by the system. X11 is different. With X11, the window frames (also called "decoration") are provided by a separate program, called the window manager. In most respects, the window manager is just another client application; it is started the same way and talks to the X server through the same channels.

There is a large number of different window managers to choose from. xwinman.org has a comprehensive list. Most popular ones allow the user to customize the appearance via so-called themes. Many window managers also provide additional functionality, like pop up menus in the root window, docks or launch buttons.

Many window managers have been packaged for Fink; here is a current list.

1.10 What are Quartz/Aqua, Gnome, and KDE?

They are desktop environments, and there are many others. Their purpose is to provide additional framework to applications, so that their look, feel, and behaviour can be visually consistent. Example:

graphics engine : X11

window manager: sawfish

desktop: Gnome

The lines between graphics display engine, window manager, and desktop are blurred because similar, or the same functionality, may be implemented by one or more of them. This is one reason why a particular window manager may not be able to be used with a particular desktop environment.

Many applications are developed to integrate with a particular desktop. Most often by installing the libraries for the desktop environment (and the other underlying libraries) that an application was developed for, the application will work with limited or no function loss. Examples are the increasing selection of GNOME applications available to be installed and run without running GNOME. Unfortunately, the same progress is not quite yet able to be made with KDE applications.

2 History

[Sorry for the epic language, I couldn't resist...]

2.1 The early days

In the beginning, there was void. Darwin was in its infancy, Mac OS X was still in development and there was no X11 implementation for both of them.

Then there came John Carmack and ported XFree86 to Mac OS X Server, which was the only OS in the Darwin family available at that time. Later that port was updated for XFree86 4.0 and Darwin 1.0 by Dave Zarzycki. The patches found their way into the Darwin CVS repository and slept there, waiting for things to come.

2.2 XonX forms

One fine day Torrey T. Lyons came along and gave the Darwin patches the attention they had been waiting for. Finally, he brought them to a new home, the official XFree86 CVS repository. This was the time of the Mac OS X Public Beta and Darwin 1.2. XFree86 4.0.2 worked fine on Darwin, but on Mac OS X it required users to log out of Aqua and go to the console to run it. So Torrey gathered the XonX team around him and set out on a voyage to bring XFree86 to Mac OS X.

At about the same time Tenon started to build Xtools, using XFree86 4.0 as the foundation.

2.3 To root or not to root

Soon the XonX team had XFree86 running in a fullscreen mode in parallel to Quartz and was putting out test releases for adventurous users. The test releases were called XFree86-Aqua, or XAqua for short. Since Torrey had taken the lead, changes went directly to XFree86's CVS repository, which was heading towards the 4.1.0 release.

In the first stages interfacing with Quartz was done via a small application called Xmaster.app (written with Carbon, then rewritten with Cocoa). Later that code was integrated into the X server proper, giving birth to XDarwin.app. Shared library support was also added at this time (and Tenon was convinced to use this set of patches instead of their own to ensure binary compatibility). There was even good progress on a rootless mode (using the Carbon API), but alas, it was too late to get it into XFree86 4.1.0. And the rootless patch was free, and continued to float around the net. After XFree86 4.1.0 shipped with just the fullscreen mode, work on the rootless mode continued, now using the Cocoa API. An experimental rootless mode was put into XFree86's CVS repository.

In the meantime, Apple released Mac OS X 10.0 and Darwin 1.3, and Tenon released Xtools 1.0 some weeks after that.

Development continued on integrating the rootless mode into XFree86, so that by the time XFree86 4.2.0 shipped in January 2002, the Darwin/Mac OS X version had been completely integrated into the main XFree86 distribution.

2.4 Apple's X11 distributions

On January 7, 2003, Apple released a beta version of its own custom X11 implementation for OS 10.2. It was based on XFree86-4.2 and included Quartz rendering and accelerated OpenGL. A new version was released on February 10, 2003 with additional features and bugfixes. A third release (i.e. Beta 3) was made on March 17, 2003 with further additional features and bugfixes.

On October 24, 2003, Apple released Panther (10.3), which included the first release version of their X11 distribution, based on XFree86-4.3.

On April 29, 2005, Apple released Tiger (10.4), which included an X11 distribution based on XFree86-4.4.

On October 26, 2007, Apple released Leopard (10.5), which included an X11 distribution based on X.org-7.2.

On August 28, 2009, Apple released Snow Leopard (10.6), which included an X11 distribution based on X.org-7.2.

On July 20, 2011, Apple released Lion (10.7), which included an X11 distribution based on XQuartz-2.6.4.

On July 25, 2012, Apple relased Mountain Lion (10.8). For this version of OS X, XQuartz-2.7.2 or later is the appropriate X11 distribution to use.

3 Getting and Installing X11

3.1 Apple's Distributions

All of the OS X versions currently supported by Fink use an X11 distribution from Apple. The supported configurations are:

To build packages, if you're using the stock X11 on 10.5-10.7, for Xcode <= 4.2.1 you will also need to make sure that the X11 SDK is installed (though this is normally the case by default). XQuartz users on 10.5 should not do this, since XQuartz contains everything. On 10.7, the Command Line Tools for Xcode >= 4.3 contains the X11 SDK. On 10.8, you only need to install XQuartz.

All of the X11 packages support both full-screen and rootless operation, and have OpenGL support.

For more information on using Apple's X11, check out this article at the Apple Developer Connection.

3.2 Using X11 via Fink

Fink keeps track of X11 via a set of virtual packages. The most important of these are:

Note: The presence of the separate system-xfree86* and x11* families is a holdover from OS versions prior to 10.5, where Fink had its own X11 packages which also provided the x11 family.

If you are missing any of these packages, then you're missing files from your X11 installation and may need to (re)install something. For example, if x11-dev and system-xfree86-dev are missing, this often indicates that the X11 SDK hasn't been installed.

4 Starting X11

4.1 Starting the Display Server

There are basically three ways to start X11 under Mac OS X.

One is by running the application bundle, e.g. via double-clicking the app in the Finder. This is typically /Applications/Utilities/X11(.app), if you are on 10.5-10.7, or /Applications/Utilities/XQuartz(.app) if you're using Xquartz (e.g. on 10.8).

Another way is via entering the startx command from a terminal window.

The third method is to attempt to run a program that needs X11 from a terminal window. on 10.5 and later this will automatically start an X11 server.

4.2 Customizing startup using the .xinitrc.d directory

The preferred method in current versions of X11 to customize your startup is to create a directory named .xinitrc.d at the top of your home directory, and to fill that with executable scripts to run programs that you want to use at startup, including window managers

Important: make sure to put an '&'; after the names of programs that aren't window managers, or they will block other programs, including a window manager, from being run. Also make sure that window managers do not have an '&' after their names or they won't remain running, unless there is a session manager. that is set to run after them. The xinit program interprets such a condition that as "the session has ended, I should kill the X server now, too".

Example: to run the WindowMaker window manager on startup, start with the following commands:

mkdir -p $HOME/.xinitrc.d
nano $HOME/.xinitrc.d/94-wmaker.sh

(or use your favorite editor). Then put the following contents in 94-wmaker.sh:

. /opt/sw/bin/init.sh
quartz-wm --only-proxy &
exec wmaker

Save the file, then use

chmod a+x 94-wmaker.sh

to make the script executable (quartz-wm --only-proxy will be discussed in a later section).

Example: to run the xlogo program on startup, start with the following commands:

mkdir -p $HOME/.xinitrc.d
nano $HOME/.xinitrc.d/74-xlogo.sh

(again, feel free to use your favorite editor). Then put the following contents in 74-xlogo.sh:

. /opt/sw/bin/init.sh
xlogo &

Save the file, then use

chmod a+x 74-xlogo.sh

to make the script executable.

If you were to create both scripts above, the result would be that X11 would start up, run xlogo, and then the wmaker window manager.

Example: full GNOME session. Create an executable 94-gnome-session.sh with the following contents:

. /opt/sw/bin/init.sh
quartz-wm --only-proxy &
metacity &
exec gnome-session

Example: rootless GNOME session. Create an executable 94-gnome-panel.sh with the following contents:

. /opt/sw/bin/init.sh
quartz-wm --only-proxy &
metacity &
exec gnome-panel

Example: KDE3. Create an executable 94-startkde.sh with the following contents:

. /opt/sw/bin/init.sh
exec startkde

(startkde automatically starts a window manager and uses quartz-wm --only-proxy)

Example: KDE4. Create an executable 94-startkde.sh with the following contents:

. /opt/sw/bin/init.sh
exec /opt/sw/opt/kde4/x11/bin/startkde


4.3 The .xinitrc File

Note: the use of scripts in $HOME/.xinitrc.d is preferred.

If a file named .xinitrc exists in your home directory, it will be used to start some initial X clients, e.g. the window manager and some xterms or a desktop environment like GNOME. The .xinitrc file is a /bin/sh script that contains the commands to do this. It is not necessary to put the usual #!/bin/sh in the first line or to set the executable bit on the file; xinit will always run it through the /bin/sh shell.

When there is no .xinitrc file in your home directory, and if $HOME/.xinitrc.d is not present, then X11 will use its default file, /usr/X11/lib/X11/xinit/xinitrc. You can use the default file as a starting point for your own .xinitrc:

cp /usr/X11/lib/X11/xinit/xinitrc ~/.xinitrc

To ensure reliable operation of Fink programs in .xinitrc, you should put . /opt/sw/bin/init.sh right at the beginning of the file to make sure the environment is set up correctly.

You can put fairly arbitrary commands in an .xinitrc, but there are some caveats. First, the shell that interprets the file will by default wait for every program to finish before it starts the next one. If you want several programs to run in parallel, you must tell the shell to put them "in the background" by adding a & at the end of the line.

Second, xinit waits for the .xinitrc script to finish and interprets that as "the session has ended, I should kill the X server now, too". This means that the last command of your .xinitrc must not be run in the background and it should be a long-living program. Customarily, the window manager or session manager is used for this purpose. In fact, most window managers or session managers assume that xinit is waiting for them to finish and use this to make the "Log out" entry in their menus work. (Note: To save some memory and CPU cycles, you can put an exec before the last line like in the examples below.)

Example: turn the X11 bell off, starts some clients and finally execute the Enlightenment window manager:

. /opt/sw/bin/init.sh

xset b off

xclock -geometry -0+0 &
xterm &
xterm &

exec enlightenment

Example: start GNOME:

. /opt/sw/bin/init.sh
quartz-wm --only-proxy &
metacity &
exec gnome-session

Finally, to start KDE3:

. /opt/sw/bin/init.sh
exec startkde

4.4 The 'xinitrc' package

Certain Fink packages need to be able to perform actions upon X11 startup. To allow them to do this, there is a package called xinitrc (somewhat confusing, admittedly). One side effect of installing this package, which is in the dependency chains of GNOME and KDE, is to circumvent the default behavior of using scripts from $HOME/.xinitrc.d. There are currently a couple of methods available to allow user customization of the X11 startup and allow Fink packages to do their startup tasks:

5 Other X11 Possibilities

5.1 VNC

VNC is a network-capable graphics display system similar in design to X11. However, it works at a lower level, making implementation easier. With the Xvnc server and a Mac OS X display client, it is possible to run X11 applications with Mac OS X. Fink provides X11-based VNC packages for some platforms. Check the entries here

5.2 WeirdX

WeirdX is an X11 server written in Java. It also supports rootless mode. Sources and a java jar file are available at the web site.

6 Troubleshooting XFree86

6.1 When I launch X11, it quits or crashes almost immediately

First of all: Don't Panic! There are lots of things than can go wrong with X11, and a good number of them can cause startup failures. Further, it is not unusual that X11 crashes when it experiences startup problems. This section tries to provide a comprehensive list of problems you may come across. But first, you need to gather two important pieces of information:

Display server version. You can find the version of the display server in the Finder by clicking once on the X11 or XQuartz icon and then selecting "Get Info" from the menu.

Error messages. These are essential in pinpointing the particular problem you experience. How you get the error messages depends on how you started X11. If you ran startx from a Terminal window, you'll have the messages right there in that window. Remember that you can scroll up. If you started X11 by double-clicking the X11 or XQuartz icon, the messages end up in the system log, which you can access through the Console application in the Utilities folder. Be sure to pick the right set of messages, e.g. the last one.

We'll start with a list of the messages you may see:

_XSERVTransmkdir: Owner of /tmp/.X11-unix should be set to root
_IceTransmkdir: Owner of /tmp/.ICE-unix should be set to root

Class: Harmless. X11 creates hidden directories in /tmp to store the socket "files" for local connections. For security reasons, X11 prefers if these directories are owned by root, but since they are world-writable anyway it will still run without any problems. (Note: It's quite hard to have these dirs owned by root, as Mac OS X wipes out /tmp on reboots and X11 doesn't run with root privileges and doesn't need to.)

cat: /Users/chrisp/.Xauthority: No such file or directory

Class: Mostly harmless. This issue seems to have no impact on operations. You can get rid of them by running touch .Xauthority in your home directory.

Gdk-WARNING **: locale not supported by C library

Class: Harmless. This just means what it says and won't keep the application from working. For more information, see below.

Warning: no access to tty (Inappropriate ioctl for device).
Thus no job control in this shell.

Class: Mostly harmless. X11 launches an interactive shell behind the scenes to run your client startup file (.xinitrc). This was done so that you don't have to add statements to set up PATH in that file. Some shells complain that they're not connected to a real terminal, but that can be ignored since that shell instance is not used for anything that requires job control or the like.

The XKEYBOARD keymap compiler (xkbcomp) reports:
> Error:            Can't find file "unknown" for geometry include
>                   Exiting
>                   Abandoning geometry file "(null)"
Errors from xkbcomp are not fatal to the X server

Class: Mostly harmless. As the message says, it is not fatal. To my knowledge, X11 on Macs doesn't use the XKB extension at all. Probably some client program tries to use it anyway...

startx: Command not found.

Class: Fatal. This can happen when your shell initialization files are not set up to add the X11 executable directory, e.g. /usr/X11/bin, to the PATH variable. Fink is normally set up to do this automatically, so this may indicate that your Fink environment isn't being loaded. Running


in a terminal window, and then starting a new window, will typically resolve this.

_XSERVTransSocketUNIXCreateListener: ...SocketCreateListener() failed
_XSERVTransMakeAllCOTSServerListeners: server already running
Fatal server error:
Cannot establish any listening sockets - Make sure an X server isn't already

Class: Fatal. This can happen when you accidentally run several instances of X11 at once, or maybe after an unclean shutdown (i.e. crash) of X11. It might also be a file permission problem with the sockets for local connections. You can try to clean that up with rm -rf /tmp/.X11-unix. Restarting the computer also helps in most cases (Mac OS X automatically cleans up /tmp when it boots, and the network stack is reset).

Xlib: connection to ":0.0" refused by server
Xlib: Client is not authorized to connect to Server

Class: Fatal. The client programs can't connect to the display server (X11 or XQuartz) because they use bogus authentication data. This can be caused by some VNC installations, by running X11-based apps through sudo, and probably some other freak accidents. The usual fix is to delete the .Xauthority file (which stores the authentication data) in your home directory and re-create an empty file:

rm .Xauthority
touch .Xauthority

Possibly no obvious error:

Class: Fatal. Probably the common cause for X11 startup failures is an incorrect startup file. Typically, a window manager listed in $HOME/.xinitrc or $HOME/.xinitrc.d doesn't get run due to having been uninstalled, or not being in the PATH, or runs in the background rather than the foreground due to having an '&' at the end of its line. In any case, $HOME/.xinitrc reaches its end, xinit interprets this as "the user's session has ended", and kills X11. If the executable cannot be found, there will be an error message to that effect in the terminal window or console log. On the other hand, if the last file has an '&', there will be no error, but X11 will quit. See the sections on .xinitrc.d and the .xinitrc file for more details.

To avoid this, remember to set up the PATH using

. /opt/sw/bin/init.sh

in your startup files, and also to end with a long-lived program that is not started in the background, e.g. a window manager or session manager with no '&'. You might also add exec xterm as a fallback for when your window manager or other long-lived item can't be found, e.g. if you remove it.

6.2 "Warning: locale not supported by C library"

These messages are quite common, but harmless. It just means what it says - internationalization is not supported through the standard C library, the program will use the default English messages, date formats, and so on. There are several ways to deal with this:

7 Usage Tips

7.1 Launching X11 apps from the Applications menu

Programs that require calling other programs which reside within your Fink tree for some of their functions may need special treatment to get them to work when called from the Application menu. Instead of putting just the full path to the filename, e.g.


you'll want to use something like the following, if you're using bash as your default shell:

. /opt/sw/bin/init.sh ; emacs

and if you're using tcsh:

source /opt/sw/bin/init.csh ; emacs

This makes sure that the application has the correct PATH information. You can use this syntax for any Fink-installed application.

Note: some programs appear not to be launchable in this manner.

7.2 Launching X11 apps from Terminal.app

Launching X11 applications from a Terminal(.app) window (or one from another non-X11 terminal program) is straightforward with current versions of X11 on OS 10.5 and later. Enter the application's name as you would for a command-line program, OS X will start X11 if it isn't already running, and then run your application.

Important Note: Prior to 10.5, it was required to set the DISPLAY environment variable in your terminal session for it to talk to X11. Don't do this on 10.5 and later, since OS X automatically sets it to the right value.

7.3 Launching Aqua apps from an xterm

One way to launch Aqua applications from an xterm (or any other shell, actually) is the open command. Some examples:

open /Applications/TextEdit.app
open SomeDocument.rtf
open -a /Applications/TextEdit.app index.html

The second example opens the document in the application that is associated with it, the third example explicitly gives an application to use.

The launch command from Fink's launch package works the same way, and provides some additional functionality.

7.4 Copy and Paste

Copy and Paste generally works between the Aqua and X11 environments. There are still some bugs. Emacs is reported to be picky about the current selection. Copy and paste from Classic to X11 doesn't work.

Anyway, the trick is to use the respective methods of the environment you're in. To transfer text from Aqua to X11, use Cmd-C in Aqua, then bring the destination window to the front and use the "middle mouse button", i.e. Option-click on a single-button mouse (turn on "Emulate three button mouse" in the X11 Preferences), to paste. To transfer text from X11 to Aqua, simply select the text with the mouse in X11, use Cmd-C to copy it, then use Cmd-V in Aqua to paste it. Depending on your OS and X11 versions, you may also be able to use the copy function from your X11 application to copy your selection, too.

The X11 system actually has several separate clipboards (called "cut buffers" in X11 speak), and some applications have weird views which one should be used. In particular, pasting into GNU Emacs or XEmacs sometimes hasn't worked because of this. Apple's quartz-wm window manager smooths out synchronization between the buffers. If you want to use a different window manager, you can still get the benefits of quartz-wm on 10.5-10.7, by using the --only-proxy flag:

quartz-wm --only proxy &
exec <your window manager here>

Note: this flag is no longer used in quartz-wm from Xquartz-2.7.x .

The program autocutsel is deprecated, but is still available on 10.5 and 10.6 if you don't want to use quartz-wm --only proxy. It automatically synchronizes the two main cut buffers. To run it, install the autocutsel Fink package and add the following line to your .xinitrc or in its own .xinitrc.d shell script:

autocutsel &

(Make sure this runs before the line that exec's the window manager and never returns! Don't just add it at the end, it won't be executed.)

In any case, if you encounter problems copying or pasting from Aqua to X11 and vice-versa, you may first try to do the pasting part twice (it may happen that the copy does not occur at once), then use intermediate applications, e.g. TextEdit or Terminal.app on the Aqua side, nedit or an xterm on the X11 side. In my experience, there is always a solution.

Copyright Notice

Copyright (c) 2001 Christoph Pfisterer, Copyright (c) 2001-2020 The Fink Project. You may distribute this document in print for private purposes, provided the document and this copyright notice remain complete and unmodified. Any commercial reproduction and any online publication requires the explicit consent of the author.

Generated from $Fink: x11.en.xml,v 1.26 2023/08/04 5:08:13 nieder Exp $