pyrox.dev
1# X Window System {#sec-x11}
2
3The X Window System (X11) provides the basis of NixOS' graphical user
4interface. It can be enabled as follows:
5
6```nix
7{ services.xserver.enable = true; }
8```
9
10The X server will automatically detect and use the appropriate video
11driver from a set of X.org drivers (such as `vesa` and `intel`). You can
12also specify a driver manually, e.g.
13
14```nix
15{ services.xserver.videoDrivers = [ "r128" ]; }
16```
17
18to enable X.org's `xf86-video-r128` driver.
19
20You also need to enable at least one desktop or window manager.
21Otherwise, you can only log into a plain undecorated `xterm` window.
22Thus you should pick one or more of the following lines:
23
24```nix
25{
26 services.desktopManager.plasma6.enable = true;
27 services.xserver.desktopManager.xfce.enable = true;
28 services.desktopManager.gnome.enable = true;
29 services.xserver.desktopManager.mate.enable = true;
30 services.xserver.windowManager.xmonad.enable = true;
31 services.xserver.windowManager.twm.enable = true;
32 services.xserver.windowManager.icewm.enable = true;
33 services.xserver.windowManager.i3.enable = true;
34 services.xserver.windowManager.herbstluftwm.enable = true;
35}
36```
37
38NixOS's default *display manager* (the program that provides a graphical
39login prompt and manages the X server) is LightDM. You can select an
40alternative one by picking one of the following lines:
41
42```nix
43{
44 services.displayManager.sddm.enable = true;
45 services.displayManager.gdm.enable = true;
46}
47```
48
49You can set the keyboard layout (and optionally the layout variant):
50
51```nix
52{
53 services.xserver.xkb.layout = "de";
54 services.xserver.xkb.variant = "neo";
55}
56```
57
58The X server is started automatically at boot time. If you don't want
59this to happen, you can set:
60
61```nix
62{ services.xserver.autorun = false; }
63```
64
65The X server can then be started manually:
66
67```ShellSession
68# systemctl start display-manager.service
69```
70
71On 64-bit systems, if you want OpenGL for 32-bit programs such as in
72Wine, you should also set the following:
73
74```nix
75{ hardware.graphics.enable32Bit = true; }
76```
77
78## Auto-login {#sec-x11-auto-login}
79
80The x11 login screen can be skipped entirely, automatically logging you
81into your window manager and desktop environment when you boot your
82computer.
83
84This is especially helpful if you have disk encryption enabled. Since
85you already have to provide a password to decrypt your disk, entering a
86second password to login can be redundant.
87
88To enable auto-login, you need to define your default window manager and
89desktop environment. If you wanted no desktop environment and i3 as your
90your window manager, you'd define:
91
92```nix
93{ services.displayManager.defaultSession = "none+i3"; }
94```
95
96Every display manager in NixOS supports auto-login, here is an example
97using lightdm for a user `alice`:
98
99```nix
100{
101 services.xserver.displayManager.lightdm.enable = true;
102 services.displayManager.autoLogin.enable = true;
103 services.displayManager.autoLogin.user = "alice";
104}
105```
106
107## Running X without a display manager {#sec-x11-startx}
108
109It is possible to avoid a display manager entirely and starting the X server
110manually from a virtual terminal. Add to your configuration:
111```nix
112{
113 services.xserver.displayManager.startx = {
114 enable = true;
115 generateScript = true;
116 };
117}
118```
119then you can start the X server with the `startx` command.
120
121The second option will generate a base `xinitrc` script that will run your
122window manager and set up the systemd user session.
123You can extend the script using the
124[extraCommands](#opt-services.xserver.displayManager.startx.extraCommands)
125option, for example:
126```nix
127{
128 services.xserver.displayManager.startx = {
129 generateScript = true;
130 extraCommands = ''
131 xrdb -load .Xresources
132 xsetroot -solid '#666661'
133 xsetroot -cursor_name left_ptr
134 '';
135 };
136}
137```
138or, alternatively, you can write your own from scratch in `~/.xinitrc`.
139
140In this case, remember you're responsible for starting the window manager, for
141example:
142```shell
143sxhkd &
144bspwm &
145```
146and if you have enabled some systemd user service, you will probably want to
147also add these lines too:
148```shell
149# import required env variables from the current shell
150systemctl --user import-environment DISPLAY XDG_SESSION_ID
151# start all graphical user services
152systemctl --user start nixos-fake-graphical-session.target
153# start the user dbus daemon
154dbus-daemon --session --address="unix:path=/run/user/$(id -u)/bus" &
155```
156
157## Intel Graphics drivers {#sec-x11--graphics-cards-intel}
158
159The default and recommended driver for Intel Graphics in X.org is `modesetting`
160(included in the xorg-server package itself).
161This is a generic driver which uses the kernel [mode
162setting](https://en.wikipedia.org/wiki/Mode_setting) (KMS) mechanism, it
163supports Glamor (2D graphics acceleration via OpenGL) and is actively
164maintained, it may perform worse in some cases (like in old chipsets).
165
166There is a second driver, `intel` (provided by the xf86-video-intel package),
167specific to older Intel iGPUs from generation 2 to 9. It is not recommended by
168most distributions: it lacks several modern features (for example, it doesn't
169support Glamor) and the package hasn't been officially updated since 2015.
170
171Third generation and older iGPUs (15-20+ years old) are not supported by the
172`modesetting` driver (X will crash upon startup). Thus, the `intel` driver is
173required for these chipsets.
174Otherwise, the results vary depending on the hardware, so you may have to try
175both drivers. Use the option
176[](#opt-services.xserver.videoDrivers)
177to set one. The recommended configuration for modern systems is:
178
179```nix
180{ services.xserver.videoDrivers = [ "modesetting" ]; }
181```
182::: {.note}
183The `modesetting` driver doesn't currently provide a `TearFree` option (this
184will become available in an upcoming X.org release), So, without using a
185compositor (for example, see [](#opt-services.picom.enable)) you will
186experience screen tearing.
187:::
188
189If you experience screen tearing no matter what, this configuration was
190reported to resolve the issue:
191
192```nix
193{
194 services.xserver.videoDrivers = [ "intel" ];
195 services.xserver.deviceSection = ''
196 Option "DRI" "2"
197 Option "TearFree" "true"
198 '';
199}
200```
201
202Note that this will likely downgrade the performance compared to
203`modesetting` or `intel` with DRI 3 (default).
204
205## Proprietary NVIDIA drivers {#sec-x11-graphics-cards-nvidia}
206
207NVIDIA provides a proprietary driver for its graphics cards that has
208better 3D performance than the X.org drivers. It is not enabled by
209default because it's not free software. You can enable it as follows:
210
211```nix
212{ services.xserver.videoDrivers = [ "nvidia" ]; }
213```
214
215If you have an older card, you may have to use one of the legacy drivers:
216
217```nix
218{
219 hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_470;
220 hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_390;
221 hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_340;
222}
223```
224
225You may need to reboot after enabling this driver to prevent a clash
226with other kernel modules.
227
228## Touchpads {#sec-x11-touchpads}
229
230Support for Synaptics touchpads (found in many laptops such as the Dell
231Latitude series) can be enabled as follows:
232
233```nix
234{ services.libinput.enable = true; }
235```
236
237The driver has many options (see [](#ch-options)).
238For instance, the following disables tap-to-click behavior:
239
240```nix
241{ services.libinput.touchpad.tapping = false; }
242```
243
244Note: the use of `services.xserver.synaptics` is deprecated since NixOS
24517.09.
246
247## GTK/Qt themes {#sec-x11-gtk-and-qt-themes}
248
249GTK themes can be installed either to user profile or system-wide (via
250`environment.systemPackages`). To make Qt 5 applications look similar to
251GTK ones, you can use the following configuration:
252
253```nix
254{
255 qt.enable = true;
256 qt.platformTheme = "gtk2";
257 qt.style = "gtk2";
258}
259```
260
261## Custom XKB layouts {#custom-xkb-layouts}
262
263It is possible to install custom [ XKB
264](https://en.wikipedia.org/wiki/X_keyboard_extension) keyboard layouts
265using the option `services.xserver.xkb.extraLayouts`.
266
267As a first example, we are going to create a layout based on the basic
268US layout, with an additional layer to type some greek symbols by
269pressing the right-alt key.
270
271Create a file called `us-greek` with the following content (under a
272directory called `symbols`; it's an XKB peculiarity that will help with
273testing):
274
275```
276xkb_symbols "us-greek"
277{
278 include "us(basic)" // includes the base US keys
279 include "level3(ralt_switch)" // configures right alt as a third level switch
280
281 key <LatA> { [ a, A, Greek_alpha ] };
282 key <LatB> { [ b, B, Greek_beta ] };
283 key <LatG> { [ g, G, Greek_gamma ] };
284 key <LatD> { [ d, D, Greek_delta ] };
285 key <LatZ> { [ z, Z, Greek_zeta ] };
286};
287```
288
289A minimal layout specification must include the following:
290
291```nix
292{
293 services.xserver.xkb.extraLayouts.us-greek = {
294 description = "US layout with alt-gr greek";
295 languages = [ "eng" ];
296 symbolsFile = /yourpath/symbols/us-greek;
297 };
298}
299```
300
301::: {.note}
302The name (after `extraLayouts.`) should match the one given to the
303`xkb_symbols` block.
304:::
305
306Applying this customization requires rebuilding several packages, and a
307broken XKB file can lead to the X session crashing at login. Therefore,
308you're strongly advised to **test your layout before applying it**:
309
310```ShellSession
311$ nix-shell -p xorg.xkbcomp
312$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
313```
314
315You can inspect the predefined XKB files for examples:
316
317```ShellSession
318$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"
319```
320
321Once the configuration is applied, and you did a logout/login cycle, the
322layout should be ready to use. You can try it by e.g. running
323`setxkbmap us-greek` and then type `<alt>+a` (it may not get applied in
324your terminal straight away). To change the default, the usual
325`services.xserver.xkb.layout` option can still be used.
326
327A layout can have several other components besides `xkb_symbols`, for
328example we will define new keycodes for some multimedia key and bind
329these to some symbol.
330
331Use the *xev* utility from `pkgs.xorg.xev` to find the codes of the keys
332of interest, then create a `media-key` file to hold the keycodes
333definitions
334
335```
336xkb_keycodes "media"
337{
338 <volUp> = 123;
339 <volDown> = 456;
340}
341```
342
343Now use the newly define keycodes in `media-sym`:
344
345```
346xkb_symbols "media"
347{
348 key.type = "ONE_LEVEL";
349 key <volUp> { [ XF86AudioLowerVolume ] };
350 key <volDown> { [ XF86AudioRaiseVolume ] };
351}
352```
353
354As before, to install the layout do
355
356```nix
357{
358 services.xserver.xkb.extraLayouts.media = {
359 description = "Multimedia keys remapping";
360 languages = [ "eng" ];
361 symbolsFile = /path/to/media-key;
362 keycodesFile = /path/to/media-sym;
363 };
364}
365```
366
367::: {.note}
368The function `pkgs.writeText <filename> <content>` can be useful if you
369prefer to keep the layout definitions inside the NixOS configuration.
370:::
371
372Unfortunately, the Xorg server does not (currently) support setting a
373keymap directly but relies instead on XKB rules to select the matching
374components (keycodes, types, ...) of a layout. This means that
375components other than symbols won't be loaded by default. As a
376workaround, you can set the keymap using `setxkbmap` at the start of the
377session with:
378
379```nix
380{
381 services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";
382}
383```
384
385If you are manually starting the X server, you should set the argument
386`-xkbdir /etc/X11/xkb`, otherwise X won't find your layout files. For
387example with `xinit` run
388
389```ShellSession
390$ xinit -- -xkbdir /etc/X11/xkb
391```
392
393To learn how to write layouts take a look at the XKB [documentation
394](https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts).
395More example layouts can also be found [here
396](https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples).