From ArchWiki
Jump to navigation Jump to search

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.

Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어

External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary wiki Template:Article summary end Xorg is the public, open-source implementation of the X window system version 11. Since Xorg is the most popular choice among Linux users, its ubiquity has led to making it an ever-present requisite for GUI applications, resulting in massive adoption from most distributions. See the Xorg Wikipedia article or visit the Xorg website for more details.


Before beginning, make sure you do the following:

  1. pacman is configured and refreshed ( pacman -Sy )
  2. Your system is up-to-date ( pacman -Su )
  3. Take note about third-party drivers (e.g., NVIDIA or ATI drivers)

First install the complete 'xorg' group:

# pacman -S xorg

If you have a laptop you may also want the synaptics driver

# pacman -S xf86-input-synaptics

The default 'vesa' driver, though widely compatible with nearly all available chip sets, is merely a fall-back (not accelerated and does not support many resolutions). Therefore, a proper video driver should be installed if possible. This command will list all open source video drivers available:

# pacman -Ss xf86-video

Look for the appropriate driver for your card and install it with

# pacman -S xf86-video-yourCard 

To discover which card is in your system:

$ lspci | grep "VGA"


Before you can run Xorg, you may need to configure it so that it knows about your graphics card, monitor, mouse and keyboard. Current versions of Xorg effectively auto-detects most hardware without previous configuration. Because of these improvements, it is recommended that you start without a Template:Filename and add sections only as required.
Xorg 1.7 = X server uses HAL for input device detection
Xorg 1.8 = X server uses udev instead of HAL for input device detection and xorg.conf InputClass configuration

Follow the directions in #Running Xorg to determine if configuring Xorg is a necessary. If X works as expected and you would like to have a Template:Filename file see creating an xorg.conf from Xorg's log file. If none of the automatic configurations work keep one and tweak it. For help, look at the #Troubleshooting section and try to google. Remember log files are there to help you figure out what is wrong.

Manual Configuration: Sometimes the automatic configuration is not enough or may be incorrect. It is recommended to put user configurations in Template:Filename and not in Template:Filename

Xorg 1.7: Refer to HAL and Template:Codeline to familiarize yourself with Xorg's manual configuration syntax.
Xorg 1.8: Generally, users should not (need to) configure udev or add udev rules to enable device detection in X. While supported, users are discouraged of putting X.org-specific configuration into udev rules files. Refer to Template:Codeline

Automatic Configuration

Xorg -configure

The use of this command will cause the Xorg server to loads all the video driver modules, probes for available hardware, and write an initial xorg.conf file based on what was detected.

As root run:

# Xorg -configure

The command automatically generates Template:Filename.
To change the location of the file, append the file location as an argument. Example:

# Xorg -configure /home/user/xorg.conf.new

and copy it to Template:Filename.

Note: If you are using the binary nvidia or ati drivers you may need to modify xorg.conf and change Template:Codeline to the appropriate driver. For example: nvidia or fglrx
Note: X and Xorg are the same command. There is a symlink linking X -> Xorg


NVIDIA users can also use

# nvidia-xconfig

when they have official nvidia drivers installed.

Note: This currently does not work with Xorg 1.8

From the Xorg.0.log file

If you managed to start X without any xorg.conf file, you can find the default Xorg configuration in Template:Filename. Just copy the text between lines like

(==) --- Start of built-in configuration ---


(==) --- End of built-in configuration ---

to your new Template:Filename file.

Input Hot-plugging

Xorg 1.7 uses hal for device detection. The following will disable hal.
Xorg 1.8 uses udev for device detection. The following will disable udev.

Section "ServerFlags"
    Option "AutoAddDevices" "False"
Note: This will disable Xorg hot-plugging for all input devices and revert to the same behavior as xorg-server 1.4. It is much more convenient to configure devices through HAL (1.7) or udev (1.8) instead of xorg.conf. This is not recommended! See: Xorg Input Hotplugging

xorg.conf.d (Xorg 1.8)

The X server now supports a configuration directory /etc/xorg.conf.d. Files with the suffix .conf in this directory are parsed by the X server on startup and treated like a part of the traditional xorg.conf configuration file. Files in this directory may contain one or more sections; for a description of the options in a section and the general layout please refer to xorg.conf(5). Files in the /etc/xorg.conf.d directory are parsed in-order before the xorg.conf has been parsed fully and precedence is given to the xorg.conf, then to the last configuration entry where applicable. The X server essentially treats the collection of configuration files as one big file with entries from xorg.conf at the end. Users are encouraged to put custom configuration into /etc/xorg.conf and leave the directory for configuration snippets provided by the distribution.

InputClasses (Xorg 1.8)

Taken from: https://fedoraproject.org/wiki/Input_device_configuration

InputClasses are a new type of configuration section that does not apply to a single device but rather to a class of devices, including hotplugged devices. An InputClass section's scope is limited by the matches specified – to apply to an input device, all matches must apply to a device. An example InputClass section is provided below:

Section "InputClass"
   Identifier      "touchpad catchall"
   MatchIsTouchpad "on"
   Driver           "synaptics"

If this snippet is present in the Template:Filename or xorg.conf.d, any touchpad present in the system is assigned the synaptics driver. Note that due to precedence order (alphanumeric sorting of xorg.conf.d snippets) the Driver setting overwrites previously set driver options – the more generic the class, the earlier it should be listed. The default snippet shipped with the xorg-x11-drv-Xorg package is Template:Filename and applies the evdev driver to all input devices.

The match options specify which devices a section may apply to. To match a device, all match lines must apply. The following match lines are supported (with examples):

An example section for user-specific configuration is:

Section "InputClass"
   Identifier     "lasermouse slowdown"
   MatchIsPointer "on"
   MatchProduct   "Lasermouse"
   MatchVendor    "LaserMouse Inc."
   Option         "ConstantDeceleration" 20

This section would match a pointer device containing "Lasermouse" from "Lasermouse Inc." and apply a constant deceleration of 20 on this device – slowing it down by factor 20.

Some devices may get picked up by the X server when they really shouldn't be. These devices can be configured to be ignored:

Section "InputClass"
   Identifier     "no need for accelerometers in X"
   MatchProduct   "accelerometer"
   Option         "Ignore" "on"

Example configurations

The following subsections describe example configurations for commonly used configuration options. Note that if you use a desktop environment such as GNOME or KDE, options you set in the xorg.conf may get overwritten with user-specific options upon login.

Example: Wheel Emulation (for a Trackpoint)

If you own a Computer with a Trackpoint (a Thinkpad for example) you can add the following to the Template:Filename to use the middle Button to emulate a mouse wheel:

Section "InputClass"
   Identifier     "Wheel Emulation"
   MatchIsPointer "on"
   MatchProduct   "TrackPoint"
   Option         "EmulateWheelButton" "2"
   Option "EmulateWheel" "on"
Example: Tap-to-click

Tap-to-click can be enabled in the mouse configuration dialog (in the touchpad tab) but if you need tapping enabled at gdm already, the following snippet does it for you:

Section "InputClass"
       Identifier "tap-by-default"
       MatchIsTouchpad "on"
       Option "TapButton1" "1"

Monitor settings

Nearly all LCD monitors and some CRTs provide extended display identification data (EDID). The EDID the includes manufacturer name and serial number, product type, display size, sync rates, and other information. This allows Xorg to detect the correct values to use for your monitor. If Xorg correctly auto-detects you monitor's settings no additional configuration is going to be needed. This will be the case for most users.

However, if Xorg fails at detecting the correct values or does not detect anything at you will likely have to set the Horizontal Sync and the Refresh Rate. Look these values up in your monitor's manual before setting them. Failure to do so, may cause irreversible damage!

Example Configuration:

Section "Monitor"
   Identifier     "Monitor0"
   VendorName     "Unknown"
   HorizSync 28-64  #Horizontal Sync Rate
   VertRefresh 60   #Refresh Rate
Section "Screen"
   Identifier     "Screen0"
   Device         "Device0"
   Monitor        "Monitor0"
   DefaultDepth    24
   SubSection     "Display"
       Depth       24      #Color Depth
       Modes      "1280x1024" "1024x768" "800x600"  #Resolution

Display Size and DPI

Q: How does the Xorg servers calculate DPI?
A: The DPI of the X server is determined in the following manner:

  1. The -dpi command line option has highest priority.
  2. If this is not used, the DisplaySize setting in the X config file is used to derive the DPI, given the screen resolution.
  3. If no DisplaySize is given, the monitor size values from DDC are used to derive the DPI, given the screen resolution.
  4. If DDC does not specify a size, 75 DPI is used by default.

In order to get correct dots per inch (DPI) set, the display size must recognized or set. Having the correct DPI is especially necessary where fine detail is required (like font rendering). Previously manufacturers tried to create a standard for 96 DPI (an 10.3" diagonal monitor would be 800x600, a 13.2" monitor 1024x768). Now days screens can be of any number of DPI and this may not match horizontal and vertically. To be able to set the DPI the Xorg server attempts to auto-detect your monitor's physical screen size through the graphic card with DDC. When the Xorg server knows the physical screen size, it will be able to set the correct DPI depending on resolution size.

To see if your display size and DPI are detected/calculated correctly:

$ xdpyinfo | grep dimensions
$ xdpyinfo | grep "dots per inch"

Check that the dimensions match your display size. If the Xorg server is not able to correctly calculate the screen size, it will default to 75x75 DPI and you will have to calculate it yourself.

If you have specifications on the physical size of the screen, they can be entered in the Xorg configuration file so that the proper DPI is calculated:

Section "Monitor"
    Identifier "Monitor0"
    DisplaySize 286 179    # In millimeters

If you do not have specifications for horizontal and physical screen width and height (most specifications these days only list by diagonal size), you can use the monitors native resolution (or aspect ratio) and diagonal length to calculate the horizontal and vertical physical dimensions. Using the Pythagorean theorem on a 13.3" diagonal length screen with a 1280x800 native resolution (or 16:10 aspect ratio):

echo 'scale=5;sqrt(1280^2+800^2)' | bc  # 1509.43698

This will give the pixel diagonal length and with this value you can discover the physical horizontal and vertical lengths (and convert it to millimeters):

echo 'scale=5;(13.3/1509)*1280*25.4' | bc  # 286.43072
echo 'scale=5;(13.3/1509)*800*25.4' | bc   # 179.01920
Note: This calculation works for most monitor sizes, however there is the seldom cheaper monitor that may compress aspect ratio (e.g 16:10 aspect resolution to a 16:9 monitor) if this is the case you should measure you screen size manually.

DPI can be set too if you only plan to use one resolution:

Section "Monitor"
    Identifier "Monitor0"
    Option   "DPI" "96 x 96"

If for some odd reason that the nvidia drivers don't set the correct DPI, you can turn off auto-detection:

  Option   "UseEdidDpi" "false"

For RandR compliant drivers, you can set it by:

xrandr --dpi 96

You can add that command to your Template:Filename to have the DPI settings applied when you start X manually.

Multi-monitor setups

The easiest way to achieve a working multi-monitor setup is using xrandr after X starts. First, run (from any account):

xrandr -q

This will list all your available video outputs, with some information about them. Assume your output names are VGA-0, DVI-0 and S-video. Then, to merge screens connected to DVI-0 and VGA-0 outputs, you just need to run:

xrandr --output DVI-0 --right-of VGA-0

If this command works for you, just add it to your ~/.xinitrc file.

It sometimes helps to add the virtual size to your Screen options summing the two monitors resolution:

Section "Screen"
	Identifier	"Screen0"
	Device	"ATI"
	Monitor "One"
	DefaultDepth	24
	SubSection "Display"
		Depth	24
		Modes "1680x1050"
		Virtual 3360 2100  

See HowToRandR12 for more information on multi-monitor setup.

Keyboard settings

Xorg may fail to detect your keyboard correctly. This might give problems with your keyboard layout or keyboard model not being set correctly.

To see a full list of keyboard models, layouts, variants and options, open:


Normally, Xorg tries to configure your keyboard using the xf86-input-evdev driver (which in turn uses dbus and HAL) instead of using your configuration settings in xorg.conf. This may result in an undesired auto-configured keyboard layout. The fastest workaround is to disable the hot-plugging mechanism. (See Above)

Keyboard layout (Xorg 1.7)

# cp /usr/share/hal/fdi/policy/10osvendor/10-keymap.fdi /etc/hal/fdi/policy/

Then open Template:Filename and edit "us" in input.xkb.layout to what you want and, if necessary, edit input.xkb.variant too.

For the changes in /etc/hal/fdi/policy/10-keymap.fdi to take effect, you should restart HAL:

# /etc/rc.d/hal restart

and restart Xorg

If this is not working for you, the following command (with your keyboard layout instead of pl), executed in X, should switch to your keyboard layout.

# setxkbmap pl 

To make it permanent you can e.g. add this command to Template:Filename file (before starting the window manager).

Through xorg.conf (deprecated)
Note: Changing the keyboard layout through xorg.conf requires disabling input hot-plugging.

To change the keyboard layout, use the XkbLayout option in the keyboard InputDevice section. For example, if you have a keyboard with English layout:

Option "XkbLayout" "gb"

To be able to easily switch keyboard layouts, for example between a US and a Swedish layout use this instead:

Option "XkbLayout" "us, se"
Option "XkbOptions" "grp:caps_toggle"

This makes your Caps Lock key switch between the different layouts. This is mainly useful if you do not run a Desktop Environment which takes care of keyboard layouts for you.

To change the keyboard model, use the XkbModel option in the keyboard InputDevice section. For example, if you have a Microsoft Wireless Multimedia Keyboard:

Option "XkbModel" "microsoftmult"

Disable mousekeys permanently

To disable the mousekeys permanenly and prevent Shift+NumLock or Shift+Alt+NumLock to enable, edit:


and comment out:

augment "mousekeys"
augment "accessx(full)"

Keyboard Settings (Xorg 1.8)

To see a full list of keyboard models, layouts, variants and options, open:


To set the keymap for the current Xorg session:

# setxkbmap dvorak

To make the change permanent add the following to xorg.conf

Section "InputClass"
    Identifier             "Keyboard Defaults"
    MatchIsKeyboard	   "yes"
    Option	           "XkbLayout" "dvorak"

To be able to easily switch keyboard layouts, for example between a US and a Swedish layout use this instead:

Option "XkbLayout"  "us, se"
Option "XkbOptions" "grp:caps_toggle"

This makes your Caps Lock key switch between the different layouts. This is mainly useful if you do not run a Desktop Environment which takes care of keyboard layouts for you.


DPMS (Display Power Management Signaling) is a technology that allows power saving behaviour of monitors when the computer is not in use. This will allow you to have you monitors automatically go into standby after a predefined period of time. See: DPMS

Proprietary drivers

If you wish to use third-party graphics drivers, do check that the X server runs OK first. Xorg should run smoothly without official drivers, which are typically needed only for advanced features such as 3D-accelerated rendering for games, dual-screen setups, and TV-out. Refer to the NVIDIA and ATI for help with driver installation.


There some tips for setting up fonts in Font Configuration.

Sample xorg.conf Files

Anyone who has an Xorg.conf file written up that works, go ahead and post a link to it here for others to look at. Please do not in-line the entire configuration file; upload it somewhere else and link.
Please post input hotplugging configurations only, otherwise note that your config is not using input hotplugging. (Xorg 1.8 = udev; Xorg 1.7 = hal)

Running Xorg

Warning: Unless you have disabled input hot-plugging (not recommended), the HAL daemon needs to be started before running Xorg.
Note: If you are using Xorg 1.8 you do not need to add HAL to DAEMONS array or start hal.

Add hal to the DAEMONS array of Template:Filename:

DAEMONS=(syslogng hal network netfs crond)

Start hal:

# /etc/rc.d/hal start

Finally, start Xorg:

$ startx


$ xinit
Note: If you just installed Xorg, there is an empty .xinitrc file in your $HOME that you need to either delete or edit in order for X to start properly. If you do not do this X will show a blank screen with what appears to be no errors in your Xorg.0.log. Simply deleting it will get it running with a default X environment.

The default X environment is rather bare, and you will typically seek to install window managers or desktop environments to supplement X. A list of suitable options is present in Common Applications#Window Managers (WM).

If a problem occurs, then view the log at Template:Filename. Be on the lookout for any lines beginning with Template:Codeline which represent errors, and also Template:Codeline which are warnings that could indicate other issues.

Tips and tricks

X startup (/usr/bin/startx) tweaking

For X's option reference see:

$ man Xserver

The following options have to be appended to the variable Template:Codeline in the Template:Filename file:

  • Enable deferred glyph loading for 16 bit fonts:
-deferglyphs 16

Note: If you start X with kdm, the startx script does not seem to be executed. X options must be appended to the variable Template:Codeline or Template:Codeline in the Template:Filename file. By default kdm options are:

  ServerArgsLocal=-nolisten tcp

Virtual X session

To start another X session in for example CTRL + ALT + F8 you need to type this on a console:

xinit /path/to/wm -- :1

Change "/path/to/wm" to your window manager start file or to your login manager like gdm, kdm and slim.

Nested X session

To run a nested session of another desktop environment:

$ /usr/bin/Xnest :1 -geometry 1024x768+0+0 -ac -name Windowmaker & wmaker -display :1

This will launch a Window Maker session in a 1024 by 768 window within your current X session.


Common problems

If Xorg will not start, or the screen is completely black, the keyboard and mouse is not working, etc., first take these simple steps:

  • Check the log file: Template:Codeline
  • Make sure that HAL has been started prior to running Xorg:
 # /etc/rc.d/hal start
  • Install input driver (keyboard, mouse, joystick, tablet, etc...):
 # pacman -S xf86-input-evdev
  • Finally, search for common problems in ATI, Intel and NVIDIA articles.

Ctrl-Alt-Backspace doesn't work

There are two ways of restoring Template:Keypress+Template:Keypress+Template:Keypress; with and without input-hotplugging. Using hot-plugging is recommended.

With input hot-plugging

In most situations, using user-specific configuration might be preferred over system-wide.

Note: On GNOME, this system-wide setting has no effect. Every user must go to System -> Preferences -> Keyboard -> Layouts -> Layouts options -> Key sequence to shutdown X server and checked Ctrl-Alt-Backspace checkbox
Xorg 1.8


Option  "XkbOptions" "terminate:ctrl_alt_bksp"

to InputClass as so:

Section "InputClass"
   Identifier            "Keyboard Defaults"
   MatchIsKeyboard	 "yes"
   Option	         "XkbLayout"  "dvorak"
   Option                "XkbOptions" "terminate:ctrl_alt_bksp"
Xorg 1.7

If you are using HAL to manage your keyboard, you must add the following to Template:Filename to enable this behavior. If that file does not exist, copy it from the template at Template:Filename:

# cp /usr/share/hal/fdi/policy/10osvendor/10-keymap.fdi /etc/hal/fdi/policy/10-keymap.fdi

Check for a line resembling this:

<merge key="input.xkb.options" type="string">terminate:ctrl_alt_bksp</merge>

If the Template:Codeline line already exists, add Template:Codeline to the existing line:

<merge key="input.xkb.options" type="string">grp:alt_shift_toggle,terminate:ctrl_alt_bksp</merge>

Afterwards, Restart HAL and Xorg.


Another way is to add the following line to Template:Filename

setxkbmap -option terminate:ctrl_alt_bksp
Note: If you use a login/display manager like (K/G/X)DM or Slim, you will need to run the above setxkbmap command around your WM/DE's login time. ~/.config/autostart is usually respected for such (using .desktop files). It also works in ~/.bashrc.

Without input hot-plugging

New Xorg disables zapping with Template:Keypress+Template:Keypress+Template:Keypress by default. You can enable it by adding the following line to Template:Filename,

Option  "XkbOptions" "terminate:ctrl_alt_bksp" 

to Template:Codeline section for keyboard.

Translating xorg.conf rules to HAL format

The syntax for HAL Template:Filename files is similar to xorg.conf. For instance:

Option "RightEdge" "5300"


<merge key="input.x11_options.RightEdge" type="string">5300</merge>

Apple keyboard issues

See: Apple Keyboard

Touchpad tap-click issues

See Synaptics

Extra mouse buttons not recognized

See also: Get All Mouse Buttons Working

X clients started with "su" fail

If you are getting "Client is not authorized to connect to server", try adding the line:

session        optional        pam_xauth.so

to Template:Filename. Template:Codeline will then properly set environment variables and handle Template:Codeline keys.

Missing libraries

  • Error message: "libX... does not exist"

In most cases, all you need to do is take the name of the library (e.g., Template:Filename), convert it all to lowercase, remove the extension, and install it:

# pacman -S libxau

Packages fail to build; missing X11 includes

Reinstall the packages xproto and libx11:

# pacman -S xproto libx11

Program requests "font '(null)'"

  • Error message: "unable to load font `(null)'."

Some programs only work with bitmap fonts. Two major packages with bitmap fonts are available, xorg-fonts-75dpi and xorg-fonts-100dpi. You do not need both; one should be enough. To find out which one would be better in your case, try this:

$ xdpyinfo | grep resolution

and use what is closer to you (75 or 100 instead of XX)

# pacman -S xorg-fonts-XXdpi

Frame-buffer mode problems

If X fails to start with the following log messages,

(WW) Falling back to old probe method for fbdev
(II) Loading sub module "fbdevhw"
(II) LoadModule: "fbdevhw"
(II) Loading /usr/lib/xorg/modules/linux//libfbdevhw.so
(II) Module fbdevhw: vendor="X.Org Foundation"
       compiled for 1.6.1, module version=0.0.2
       ABI class: X.Org Video Driver, version 5.0
(II) FBDEV(1): using default device

Fatal server error:
Cannot run in framebuffer mode. Please specify busIDs for all framebuffer devices

uninstall fbdev:

# pacman -R xf86-video-fbdev

DRI with Matrox cards stops working

If you use a Matrox card and DRI stops working after upgrading to Xorg, try adding the line:

Option "OldDmaInit" "On"

to the Device section that references the video card in xorg.conf.

Recovery: disabling Xorg before GUI login

If Xorg is set to boot up automatically and for some reason you need to prevent it from starting up before the login/display manager appears (if Template:Filename is wrongly configured and Xorg does not recognize your mouse or keyboard input, for instance), you can accomplish this task with two methods.

  • From the grub menu, you can specify the runlevel in the kernel line by adding a number to the end of the kernel line specifying the run level you want. The following example sets the run level to 3:
 kernel /boot/vmlinuz26 root=/dev/disk/by-uuid/..ro 3
  • If you have not only a faulty Template:Filename to make Xorg unusable, but you have also set the grub menu wait time to zero, or cannot otherwise use grub to prevent Xorg from booting, you can use the Arch live CD. Boot up the live CD and login as root. You need a mount point, such as Template:Filename, and you need to know the name of the partition you want to mount.
You can use the command,
 # fdisk -l
to see your partitions. Usually, the one you want will be resembling Template:Filename. Then, to mount this to Template:Filename, use
 # mount /dev/sda1 /mnt
Then your file-system will show up under Template:Filename. So your Template:Filename file, for example, would be in Template:Filename. From here you can delete the Template:Codeline module to prevent Xorg from booting up normally, or make any other necessary changes.

See also