More than just another window manager!
A complete environment for X11 on Mac OS X



(Out of date)




Lists and



Introduction to
X11 on OS X




Troubleshooting OroborOSX

General Questions about X11:

If you have questions about X11, such as "what is XDarwin?", or "How do I forward X11 from a remote computer?", then you should read the Introduction to X11 on OS X.

Other Sources of Help for OroborOSX:

There are now forums and e-mail lists which you can search through, or post requests. However, I do recommend that you have a look through this page and the forums/lists before posting anything. In particular, read this list of useful tests that you can perform yourself to try and help with diagnosing problems. Thanks!

Problems launching OroborOSX:

Problems using OroborOSX:

Problems with Interleaving:

  • I cannot run the interleaving scripts - I get a message from the Terminal application saying that it "Couldn't start up the shell..." . (See the "known problems")
  • Interleaving does not always work - sometimes I get all the X11 windows coming in front when I click on one of them. (See the "known problems")

Known Problems:

  • There are occasions when OroborOSX hangs with a spinning CD cursor if it has been in the background for a while. One of the reasons this occurs is due to problem with NetInfo/lookupd in OS X 10.0 (10.1 seems to be OK). However, there may well be other issues (especially with the v0.8 releases). I have created a small "sh" script (Download it) which you can run from the Terminal when you get a hang. (Note that the script is included from v0.8 preview 3, and is automatically run when a hang is detected - the ouput goes to the console log). What it does attach the gdb debugger to the OroborOSX and XDarwin processes, and will then provide trace information which you can post to the Help forum. Thanks!
  • On one monitor the cursor becomes constrained below height of other monitor. I think this is down to the way XDarwin creates screens for Xinerama when the leftmost screen is lower than the rightmost screen. I have heard that a click in the frontmost X11 window will free up the cursor and allow it to move correctly. I would very much like to know if this is a problem with other window managers.
    Update! Xinerama problems found and fixed in XDarwin -see the note below (and check out the latest XDarwin)...
  • Blank windows on second monitor. The alpha 3/4/5 releases have an attempt at a workaround for this problem (but it does not completely solve the problem). However, I suspect the origin of this is down to XDarwin, even though many other window managers seem to be OK -try running XDarwin without a window manager, and see if the windows are blank! (Anyone who looks through the source code for OroborOSX and for other window managers, and has some ideas what's going on here, please let me know!)
    Update! The source of this problem has been found in XDarwin (along with a number of other multi-screen/Xinerama problems). The latest release of XDarwin.app (v1.0.6) for XFree86 4.1 is now available. Note that the XDarwin application that comes with XFree86 4.2 is version 1.1 (i.e. newer than 1.0.6), so it may be worth installing the whole of XFree86 4.2...
  • A bug in the Terminal application in OS X 10.0.x means that the Interleave/Uninterleave scripts cannot be executed by Terminal if the OroborOSX-Folder has a parent directory (anywhere above it) which contains a space in its name (or some other 'strange' character, such as a slash etc). If this is the case (eg, you have put it in a folder called "My Downloads", or something) then move the OroborOSX-Folder somewhere else.
  • There are issues running a multi-screen setup. Now that XDarwin supports (generally) Xinerama, there are some slightly strange effects that can occur. Development versions starting with v0.75a2 now support Xinerama, so this should hopefully overcome some of the limitations imposed on X11 under a multi-screen setup.
  • Window interleaving is not 100% reliable. Occasionally clicking on one X11 window will bring them all in front. This is because XDarwin still occasionally manages to "steal" the mouse click before OroborOSX gets to it, and it then reacts by "activating" itself into the foreground (if it is not already) before OroborOSX has had a chance to bring it forwards itself. This will tend to happen more often if you click very quickly. If you, instead, just slow down a little so that you hold the mouse button down for a fraction of a second, you will probably find it improves the interleaving reliability quite siginificantly.
  • There are also some who had difficulty pulling down OroborOSX menus. This is an issue which affected older versions (up to and including v0.71). Versions after this should not have this problem.

When I launch OroborOSX it does absolutely nothing!

The first thing to be sure of is that you have a working version of XFree86 for OSX. If you have not already installed it, go and download it. Once you can run the XDarwin application in rootless mode, you have everything you need to use OroborOSX, so read on if you still have problems...

There are problems expanding some versions of the OroborOSX archive using Stuffit Expander. I suggest you check out the Help forum, in particular looking at the topic "startup crash" to see if it matches what you see from the console log. If so, there are suggestions in that topic for dealing with the problem (either by using the latest version of Stuffit Expander, using the command-line, or using a program called OpenUp [see versiontracker.com to find this]).

There is also a potential problem that may occur if the archive that is downloaded is expanded using a Classic Mac OS version of Stuffit Expander. It is possible that it has not set the correct executable permission on the OroborOSX executable that is buried deep in the OroborOSX application bundle. I suggest you download the OroborOSX archive file to a specific place on your disk, and then expand it yourself by dragging it into the OS X version of Stuffit Expander.

When I launch OroborOSX it tries to start XDarwin, but fails after a few seconds.

There are numerous reasons why OroborOSX might fail to launch XDarwin correctly -and nearly all of them point towards some problem with the installation of either XFree86 or XDarwin.app.

The first thing to do is to open up the Console application (which is in the Utilities folder in the Applications folder) and watch the output as you launch OroborOSX. This should at least give an indication as to how far XDarwin got before it failed.

Here are some error messages that have fairly simple solutions:

  1. Failed to connect to the HID System as the window server!

    This error will occur when trying to start XDarwin using the "startx" command with the "-rootless" (or "-quartz") option (which is basically what earlier versions of OroborOSX did) when you have a ".xserverrc" file in your home directory which specifies its own arguments for the X server.

    Start up a Terminal window and type:

    ls -l .xserverrc
    (Make sure you are typing the letter "l" in the above command, not the number "1"!)

    If you find that you have such a file, then get rid of it, or rename it:

    mv .xserverrc xserverrc-old
    If this does not work (or if you do not have a .xserverrc file) then check out the links in /usr/X11R6/bin, as outlined in the next section...

  2. Unrecognized option: -rootless
    or Could not start XDarwin Quartz X server

    This might occur if, since installing a "rootless-capable" XDarwin.app, you have reinstalled a version of XFree86 which has an older version of XDarwin.app. Or it may occur if you have not correctly installed the rootless/quartz XDarwin.app.

    You should go into the /usr/X11R6/bin directory and make sure all of the links are pointing to the right places and that XDarwinStartup is new enough to know about the rootless option. So open up a Terminal window and type the following:

    cd /usr/X11R6/bin
    ls -l X*
    (Make sure you are typing the letter "l" in the above commands, not the number "1"!)

    First of all, check the date of the XDarwinStartup file -it should be newer than June 2001. If not, you will have to reinstall the XDarwin application (correctly! -follow the XDarwin.app install instructions.)

    You should also find that the right hand side of the output looks something like this:

    X -> XDarwinStartup
    XDarwinQuartz -> /Applications/XDarwin.app/Contents/MacOS/XDarwin
    If it does not (in particular, if file X does not point to XDarwinStartup, or if file XDarwinQuartz does not point into the XDarwin.app application bundle), then you may need to reset some of the links using the 'ln' command.
    (If you do not enjoy using the command line, reinstalling XDarwin.app will probably also do the trick. If you do not actually have a file called XDarwinStartup then you may have little choice but to install XDarwin.app... check out the XDarwin.app install instructions.)

    To reset the links, open up a Terminal window and type the following:

    cd /usr/X11R6/bin
    sudo rm X
    sudo ln -s XDarwinStartup X
    sudo rm XDarwinQuartz
    sudo ln -s /Applications/XDarwin.app/Contents/MacOS/XDarwin XDarwinQuartz
    The first 'rm' and 'ln' commands remove and relink file 'X', the second set of 'rm' and 'ln' remove and relink the 'XDarwinQuartz' file.
    (Note: the above commands assume that your XDarwin application is located in your Applications folder. Also, you will have to provide your password on the first 'sudo' command.)

  3. Xlib: connection to ":0.0" refused by server
    Xlib: client is not authorized to connect to server

    This is related to the authorisation file called .Xauthority in your home directory. I do not quite know how it gets into this state, but simply changing the name of this file (or removing it entirely - but it's possible it may store info for other X11 connections if you connect to X servers on other machines from your Mac) seems to sort out the problem.

    Note that since it starts with a dot, you cannot see this file in the Finder -you will have to go to the Terminal application and type something like:

    mv .Xauthority Xauthority-bad

    - - - = = = A special note if you run a VNC server on your Mac = = = - - -

    I have been informed that running a VNC server on the Mac automatically recreates the .Xauthority file. This will mean, of course, that you have to keep renaming it every time you restart XDarwin after having started a VNC server!

    One straightforward workaround for this is to add an extra option when you start up your VNC server which tells it to use a different authorisation file. So, add an option "-auth .Xauth-vnc" to the end of the command you use to start up your VNC server. This should create the file .Xauth-vnc instead of .Xauthority.

  4. xinit: Command not found

    This indicates that your PATH variable is not set correctly. It does not usually happen when launching XDarwin via OroborOSX, because the script it uses to start XDarwin sets your PATH appropriately (in theory, at least - if anyone does find XDarwin fails to launch with this message, please let me know).

    To fix this you should look to see if you have a file in your home directory called ".cshrc". Since it begins with a dot (a recurring theme here...), you cannot see this from the Finder. So go open up a Terminal window and type the following:

    echo $PATH
    ls -l .cshrc
    The 'echo' command will show the value of your PATH variable - this will be a list of directories that it searches through when looking for a command (such as xinit). If /usr/X11R6/bin is not in this list, then it explains why it cannot find xinit.

    The 'ls' command will let you know if you already have a .cshrc file. (If you do not have one called ".cshrc", you may have one called ".tcshrc", so check that, too.) If you do not have such a file (i.e. the 'ls' command gave an error saying "ls: .cshrc: No such file or directory"), then the following commands will actually create that file. However, if you do already have such a file, then the following commands will append an extra line to the end of it:
    (Note that there are two greater than signs on the first line!! And that you will not get a prompt on the second line because it is writing out to the .cshrc file.)

    cat >> .cshrc
    set path=( $path /usr/X11R6/bin )
    Now type control-D to get your prompt back. You will find you now have a .cshrc file which has a line at the end of it that will add /usr/X11R6/bin to your path -this is where the 'xinit' command is located, so there should now be no problems finding it.

    If you type "more .cshrc" you will be able to see the contents of your .cshrc file, and verify that it has the extra line at the end which adds to the path.
    (Note: it is possible, though somewhat unlikely, that if you already have a .cshrc file it may be constructed in such a way that it does not reach this final line. If the above error message persists after the extra line has been added to your .cshrc file, let me know and I can take a look at your .cshrc and try to fix it...)

  5. assert failed on line 454 of darwinKeyboard.c! (or something similar)

    This is an error message that occurs when using XDarwin 1.0a1 with Mac OS X 10.1. Upgrade to the latest version of XDarwin (1.0.6, as of writing - see the XonX page to get the latest version).

    Follow the XDarwin installation instructions to make sure you perform this correctly.

  6. _XSERVTransSocketUNIXCreateListener: ...SocketCreateListener() failed
    _XSERVTransMakeAllCOTSServerListeners: server already running

    This error message, followed by a message "Cannot establish any listening sockets - Make sure an X server isn't already running", usually indicates that there are stray processes or files left over from a previous run of XDarwin (it may have crashed badly, and been unable to clean up correctly, for example).

    Open up a Terminal window and type the following:

    ps auxww | grep ' xinit ' | grep -v grep
    ps auxww | grep -i xdarwin | grep -v grep
    For each of the above commands, you may get a line of data that starts with a user name (yours, hopefully!), and has the word 'xinit' (from the first command) or 'XDarwin' (from the second command) somewhere over to the right. If so, then read off the number that follows the user name from each line of output from each of the above commands, and repeat the following command, putting the number you read in place of the letters NNNN (if you did not get any lines of data then skip this):
    kill -9 NNNN

    For example, if the first 'ps' command above gave a line of output that starts like this:

    adrian  21474   ...more numbers here etc...
    then you should use this command:
    kill -9 21474
    Once you have killed off any stray processes, you should also check to see if there are leftover files:
    cd /tmp
    ls -lda .X*
    If there are files listed by the above (called .X11-unix and/or .X0-lock, for example) then you should remove them as follows:
    rm -rf .X*

    Hopefully, all will now be well...!

If you have other error messages, it may be worth going to the XDarwin forums and asking a question about them. Alternatively, you can e-mail me and see if I have any idea how to sort it out...

After launching OroborOSX I want my normal X11 programs to appear. Why don't they?

If by 'normal X11 programs' you are referring to the ones that automatically appear when you launch XDarwin, then you can manually run your xinitrc file (which is where these programs are launched) by choosing "Run xinitrc" from the Launch menu.

You should make sure that your xinitrc does not try to start up a window manager, since OroborOSX is already the window manager. -You will have to comment out (by putting a hash character at the beginning) the line in your xinitrc file that runs your current window manager (whether that is twm, vtwm, icewm, enlightenment, oroborus etc).

Note that the development versions (v0.75a1/2/3/4 and the 0.8 versions) do allow you to configure your Launch menu, and also choose items from it to start up when OroborOSX is launched. If you want to run your xinitrc on launch, you can edit the StartupItems file (in the Launch Menu Items folder) and just add the line "Run xinitrc". OroborOSX will then run the item "Run xinitrc" from the Launch menu, which executes your xinitrc file!

When I try to use X11 commands (like 'xhost', 'xedit', 'xterm') in an xterm window opened from the Launch menu, or in a Terminal.app window, it says the command is not known.

This is probably because you have not included /usr/X11R6/bin in your PATH defined in your shell initialisation file (.cshrc or .tcshrc, most likely).

Follow the instructions under the error "xinit: command not found" in the question "When I launch OroborOSX it tries to start XDarwin, but fails after a few seconds".

For a fuller discussion of why this happens under OroborOSX (but not under XDarwin), check out the relevant thread in the Help forum.

When I try to use X11 commands (like 'xhost', 'xedit', 'xterm') in an xterm window opened from the Launch menu, or in a Terminal.app window, it says it can't open the display.

This is probably because your DISPLAY environment variable is not set (or is set incorrectly) in your shell initialisation file (.cshrc or .tcshrc, most likely).

The standard value for DISPLAY is ":0.0", or even just ":0" (you can find out what value yours is set to by typing "echo $DISPLAY" into your terminal window). If you have changed the display number in XDarwin's preferences then your DISPLAY variable will need to reflect that change (XDarwin's display number is normally zero - if you have no need for it to be non-zero then I suggest you set it back to zero).

The instructions to fix this are very similar to those under the error "xinit: command not found" in the question "When I launch OroborOSX it tries to start XDarwin, but fails after a few seconds". The only difference is that you need to add lines to change the DISPLAY variable instead of the PATH variable. You can do this by adding the following lines (rather then the "set path=..." line from the above example):

if( ! $?DISPLAY ) then
   setenv DISPLAY :0.0

I cannot get at the OroborOSX menus - XDarwin keeps coming in front when I click on the OroborOSX dock icon, so I only get XDarwin's menus.

You have probably not run the Interleaving script.

XDarwin, by default, brings all X11 windows in front whenever it is the frontmost application. However, in order to make the windows behave more like OS X, the interleaving script makes a small change to XDarwin. Since XDarwin must be in front in order for it to receive events (such as key presses, mouse clicks etc.), OroborOSX will still send XDarwin in front whenever it is brought in front. However, once the interleaving script has made its change, it also removes XDarwin's menu bar, thus allowing access to the OroborOSX menu bar.

To run this script, double-click on the file named "InterleaveX11.command", which should open a small terminal window and make the changes.

Since the changes to XDarwin require Administrator access, it will ask you for your password. (Note: it is your password, not the root password.) If you do not have administrator access you will have to ask someone who does to log in and run the script for you.

OroborOSX seems to use a lot of CPU -up to 15%, even when idle. Why is this?

OroborOSX certainly appears to be a bit of a CPU hog. However, there are a few points to bear in mind:

  • Different machines seem to give different values -for example, my G4 Cube rarely goes up to 10%, usually around 4% to 7%. i.e. it may not be a problem for you...
  • OroborOSX v0.7 and 0.71 are not so bad as v0.75 alpha 1. This is because the alpha 1 version is a development version -that's what the alpha means! Also, the alpha 3/4 and 0.8 versions have hopefully improved somewhat over alpha 1 -Please let me know!
  • OroborOSX does have to do more checking when there is least going on. This is to do with the way it interacts with XDarwin and some situations that can occur. So, it actually tends to use more CPU when it appears to be idle!
  • The most important factor is not how much CPU it takes when there is nothing else going on, but how much CPU it drains away from other processes! OroborOSX is certainly not great in this regard, but it does tend to drain away less when the machine is busy than it does if the machine is not busy -and if the machine is not busy doing anything else, then it does not actually matter how much CPU OroborOSX uses itself!

Having said all that, since OroborOSX is a "work in progress", and since I am aware of the situation, it is an issue that will improve over time...

My cursor sometimes disappears, or does not appear as I expect, when using MacGIMP. Is this a problem with OroborOSX?

This is a problem with XDarwin in rootless mode for certain apps that make use of oversized cursors (Gimp being one such app).

The newer versions of XDarwin have a workaround which default the cursor back to the standard Mac cursor under these circumstances. -This may be why the cursor does not appear as expected.

For older versions of XDarwin, there is a semi-workaround for MacGIMP which involves adding the following line to your gimprc file (which can be found in the .gimp.1-2 directory which is in your home directory):

(cursor-updating false)

Since this directory name starts with a dot, you cannot see it from the Finder -you will have to open a Terminal window and type:

cd .gimp.1-2
open -a TextEdit gimprc
This will open your gimprc file in TextEdit, so you can make the appropriate change.

The keyboard shortcuts (eg, command-Q for Quit) do not work.

The keyboard shortcuts only work while the cursor is in the menubar.

This is basically because OroborOSX only becomes the frontmost application when the cursor is in the menubar -it is XDarwin that is in front otherwise.

It would be possible for OroborOSX to capture shortcuts through the X11 window manager side of things. However, if you used XDarwin without OroborOSX, you may have noticed that it also only allows shortcuts with the cursor in the menubar. There is a reason for this, and it makes the issue somewhat more complex...

There are some X11 apps (eg, xemacs) that actually make use of various hyper/ meta-key shortcuts. Since XDarwin maps the command key to what would be the hyper or meta key on unix workstations, it would be a bad move for XDarwin (and also OroborOSX) to capture certain shortcuts since it would prevent the X11 app from making use of them.

I hope to come up with certain options to work around this (eg, adding extra modifier keys for when you want to send the shortcut to the X11 app, or when you want to send it to OroborOSX), so watch this space...

My delete key (backspace) does not work in xterms - I just get a twiddle (~)!

Your first problem may be that you don't have your keyboard file set up correctly in XDarwin. Try starting up XDarwin by itself and choosing the appropriate keyboard from the preferences. It's possible, even if you do have the correct keyboard set up, that you have a .Xmodmap file that is still not correct. Check the instructions later on concerning this.

Perhaps you do have a .Xmodmap file that you know works fine with XDarwin by itself. If so, and you have an earlier version of OroborOSX (before v0.75 alpha 2) then the problem may well be due to the fact that it does not read your .Xmodmap file when it is first launched. If your .Xmodmap file has a line which fixes "the BackSpace issue" then you may find that your delete key does not work correctly with OroborOSX (even though it is fine if you launch XDarwin in another way).

This problem was fixed with v0.75 alpha 2 (and v0.8.5 is available now!), but can easily be fixed by following these instructions (if, for some reason, you cannot download the latest version)...

First of all, control-click on the OroborOSX application and choose "Show Package Contents" from the menu that appears. Then open up the Contents folder, then the Resources folder. you should see a file called "xinitrc", which you can drag onto TextEdit to insert the following lines (after the lines which set up the PATH variable):

if( -f ~/.Xmodmap ) then
  xmodmap ~/.Xmodmap
Once you have added these lines, save the file.

If you know that your .Xmodmap file is fine (i.e. it your delete works when you launch XDarwin without OroborOSX) then you can go ahead and restart X11, ignoring the rest of these instructions.

However, if you do not know about your .Xmodmap settings, then read on...

Note that I am not sure if the following instruction will work with all 'nationalities' of keyboards -it should be fine for UK and US, but others I don't know... Please let me know if you find it helps on different keyboards.

First of all, open up a Terminal window and check to see if you already have a file called .Xmodmap:

ls -l .Xmodmap
If you do not then type the following to create one and edit it:
xmodmap -pke > .Xmodmap
xmodmap -pme >> .Xmodmap
open -a TextEdit .Xmodmap
Note that there are two greater than signs on the second line!
You should find that you now have your .Xmodmap file opened in TextEdit and you should look for a line that says "keycode 59 = Delete". (If it says something other than "Delete" then try the following anyway, but remember what it said so you can change it back!) Change it to say "keycode 59 = BackSpace" instead (note that you need a capital "B" and a capital "S"). Save the file and then restart X11...

However, if you already have a .Xmodmap file, then you can just open it by typing:

open -a TextEdit .Xmodmap
Then look for the "keycode 59 = Delete" line and edit it as in the instructions above. If there is no line that starts with "keycode 59" then just add the whole line to the file ("keycode 59 = BackSpace" -and remember to use a capital "B" and a capital "S") and then save it and restart X11...

Why can't I use "auto-focus" (or "focus-follows-mouse") with OroborOSX?

You can! - This is available, even with interleaving, from version 0.8 preview onwards...

However, if you are using an earlier version, there are currently some technical problems with XDarwin which mean this cannot work correctly with window interleaving enabled. There's an item in the Window menu which is just waiting for this to be sorted out -then it will be possible to use auto-focus, not only on a global basis, but on a per-window basis. :-)

I have added an item to the "Launch Menu Items" folder, but it does not launch when I select it from the Launch menu -why not?

It is difficult to know exactly what the problem may be since there are numerous possibilities.

However, here are a few to consider:

  • Make sure your file has an extension of ".x11app" -you should see it turn into the correct icon if it has.
  • If you opened the "template" file in TextEdit, and then saved it with a different name, you should make sure it has 'execute' permissions (this was fixed starting with v0.75 alpha 2). You can check this by opening a terminal window, then type "chmod +x " (with a space after the "x", and don't press return yet...) and then drag the item in question from the Launch Menu Items folder onto your Terminal window -you should find that it fills in the name automatically. Now press return. It should now have the correct permission to execute.
  • If the program you want to run (that you wrote into the template file on the "set appname=..." line) is not in one of the directories that is searched by the launcher script, then you will have to add it by hand -copy one of the lines that starts 'if( ! -x "$x11exec" )...' and edit the path to point to the correct location.
If none of the above apply then open up the Console (in the Utilities folder in the Applications folder) and watch the output that appears when you try to launch the item. This may give a clue as to the problem. If you cannot sort it out, then let me know the messages that appear and I may be able to help.

The Launch menu has items called NEdit and MacGimp. I don't have NEdit and/or MacGimp -where can I get them for Mac OS X?

MacGimp is available from the MacGimp website. :-)

NEdit for Mac OS X is available for download from me, since I have managed to compile it under OS X. Download the binary package, NEdit-5.1.1-MacOSX.tar.gz. When it is expanded it only contains two items, 'nedit' and 'nc'. These should both be placed into your /usr/local/bin directory. If you do not have Administrator access to put them into /usr/local/bin, you can put them into a directory called 'bin' which is in your home directory (you may have to create this directory). OroborOSX will find the 'nedit' executable in either of these two locations.

I believe you can also get a slightly newer version of NEdit via fink.

NEdit fails to launch, giving a strange error: "XmManager ClassInitialize: XmeTraitSet failed"

This is actually due to a bug in XFree86 4.2. You can correct this by replacing a file called "libXt.6.0.dylib" with the one from XFree86 4.1.

The file is located in the directory /usr/X11R6/lib, so you can replace it using the following commands (this assumes you have downloaded the above file into your home directory, and that it has been expanded already, either automatically by Stuffit Expander when you downloaded it, or by yourself after downloading it):

cd /usr/X11R6/lib
sudo mv libXt.6.0.dylib libXt.6.0.dylib-v4.2
sudo mv libXt.6.0.dylib /usr/X11R6/lib

This will also sort out similar problems with other Motif-based applications, as well as correcting the keyboard focus in xterm windows.

And just what is NEdit, anyway?

NEdit is probably one of the nicest text editors available for use with the X11 Windows system.

It has many features that I'm not going to try and list here. Just go to the NEdit website and find out...

Contact Info:

I can be contacted as follows: adrian@ic.ac.uk

Web page: http://amcg.ese.ic.ac.uk/~adrian/

I hope somebody somewhere finds this useful!

Adrian Umpleby