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" ];
123services.xserver.useGlamor = true;
124```
125
126If you experience screen tearing no matter what, this configuration was
127reported to resolve the issue:
128
129```nix
130services.xserver.videoDrivers = [ "intel" ];
131services.xserver.deviceSection = ''
132 Option "DRI" "2"
133 Option "TearFree" "true"
134'';
135```
136
137Note that this will likely downgrade the performance compared to
138`modesetting` or `intel` with DRI 3 (default).
139
140## Proprietary NVIDIA drivers {#sec-x11-graphics-cards-nvidia .unnumbered}
141
142NVIDIA provides a proprietary driver for its graphics cards that has
143better 3D performance than the X.org drivers. It is not enabled by
144default because it's not free software. You can enable it as follows:
145
146```nix
147services.xserver.videoDrivers = [ "nvidia" ];
148```
149
150Or if you have an older card, you may have to use one of the legacy
151drivers:
152
153```nix
154services.xserver.videoDrivers = [ "nvidiaLegacy390" ];
155services.xserver.videoDrivers = [ "nvidiaLegacy340" ];
156services.xserver.videoDrivers = [ "nvidiaLegacy304" ];
157```
158
159You may need to reboot after enabling this driver to prevent a clash
160with other kernel modules.
161
162## Proprietary AMD drivers {#sec-x11--graphics-cards-amd .unnumbered}
163
164AMD provides a proprietary driver for its graphics cards that is not
165enabled by default because it's not Free Software, is often broken in
166nixpkgs and as of this writing doesn\'t offer more features or
167performance. If you still want to use it anyway, you need to explicitly
168set:
169
170```nix
171services.xserver.videoDrivers = [ "amdgpu-pro" ];
172```
173
174You will need to reboot after enabling this driver to prevent a clash
175with other kernel modules.
176
177## Touchpads {#sec-x11-touchpads .unnumbered}
178
179Support for Synaptics touchpads (found in many laptops such as the Dell
180Latitude series) can be enabled as follows:
181
182```nix
183services.xserver.libinput.enable = true;
184```
185
186The driver has many options (see [](#ch-options)).
187For instance, the following disables tap-to-click behavior:
188
189```nix
190services.xserver.libinput.touchpad.tapping = false;
191```
192
193Note: the use of `services.xserver.synaptics` is deprecated since NixOS
19417.09.
195
196## GTK/Qt themes {#sec-x11-gtk-and-qt-themes .unnumbered}
197
198GTK themes can be installed either to user profile or system-wide (via
199`environment.systemPackages`). To make Qt 5 applications look similar to
200GTK ones, you can use the following configuration:
201
202```nix
203qt5.enable = true;
204qt5.platformTheme = "gtk2";
205qt5.style = "gtk2";
206```
207
208## Custom XKB layouts {#custom-xkb-layouts .unnumbered}
209
210It is possible to install custom [ XKB
211](https://en.wikipedia.org/wiki/X_keyboard_extension) keyboard layouts
212using the option `services.xserver.extraLayouts`.
213
214As a first example, we are going to create a layout based on the basic
215US layout, with an additional layer to type some greek symbols by
216pressing the right-alt key.
217
218Create a file called `us-greek` with the following content (under a
219directory called `symbols`; it\'s an XKB peculiarity that will help with
220testing):
221
222```nix
223xkb_symbols "us-greek"
224{
225 include "us(basic)" // includes the base US keys
226 include "level3(ralt_switch)" // configures right alt as a third level switch
227
228 key <LatA> { [ a, A, Greek_alpha ] };
229 key <LatB> { [ b, B, Greek_beta ] };
230 key <LatG> { [ g, G, Greek_gamma ] };
231 key <LatD> { [ d, D, Greek_delta ] };
232 key <LatZ> { [ z, Z, Greek_zeta ] };
233};
234```
235
236A minimal layout specification must include the following:
237
238```nix
239services.xserver.extraLayouts.us-greek = {
240 description = "US layout with alt-gr greek";
241 languages = [ "eng" ];
242 symbolsFile = /yourpath/symbols/us-greek;
243};
244```
245
246::: {.note}
247The name (after `extraLayouts.`) should match the one given to the
248`xkb_symbols` block.
249:::
250
251Applying this customization requires rebuilding several packages, and a
252broken XKB file can lead to the X session crashing at login. Therefore,
253you\'re strongly advised to **test your layout before applying it**:
254
255```ShellSession
256$ nix-shell -p xorg.xkbcomp
257$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
258```
259
260You can inspect the predefined XKB files for examples:
261
262```ShellSession
263$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"
264```
265
266Once the configuration is applied, and you did a logout/login cycle, the
267layout should be ready to use. You can try it by e.g. running
268`setxkbmap us-greek` and then type `<alt>+a` (it may not get applied in
269your terminal straight away). To change the default, the usual
270`services.xserver.layout` option can still be used.
271
272A layout can have several other components besides `xkb_symbols`, for
273example we will define new keycodes for some multimedia key and bind
274these to some symbol.
275
276Use the *xev* utility from `pkgs.xorg.xev` to find the codes of the keys
277of interest, then create a `media-key` file to hold the keycodes
278definitions
279
280```nix
281xkb_keycodes "media"
282{
283 <volUp> = 123;
284 <volDown> = 456;
285}
286```
287
288Now use the newly define keycodes in `media-sym`:
289
290```nix
291xkb_symbols "media"
292{
293 key.type = "ONE_LEVEL";
294 key <volUp> { [ XF86AudioLowerVolume ] };
295 key <volDown> { [ XF86AudioRaiseVolume ] };
296}
297```
298
299As before, to install the layout do
300
301```nix
302services.xserver.extraLayouts.media = {
303 description = "Multimedia keys remapping";
304 languages = [ "eng" ];
305 symbolsFile = /path/to/media-key;
306 keycodesFile = /path/to/media-sym;
307};
308```
309
310::: {.note}
311The function `pkgs.writeText <filename> <content>` can be useful if you
312prefer to keep the layout definitions inside the NixOS configuration.
313:::
314
315Unfortunately, the Xorg server does not (currently) support setting a
316keymap directly but relies instead on XKB rules to select the matching
317components (keycodes, types, \...) of a layout. This means that
318components other than symbols won\'t be loaded by default. As a
319workaround, you can set the keymap using `setxkbmap` at the start of the
320session with:
321
322```nix
323services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";
324```
325
326If you are manually starting the X server, you should set the argument
327`-xkbdir /etc/X11/xkb`, otherwise X won\'t find your layout files. For
328example with `xinit` run
329
330```ShellSession
331$ xinit -- -xkbdir /etc/X11/xkb
332```
333
334To learn how to write layouts take a look at the XKB [documentation
335](https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts).
336More example layouts can also be found [here
337](https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples).