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