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