Introduction
In Unix‑based operating systems, the graphical environment does not start automatically in all configurations; it often depends on the session manager or display manager that has been installed. When working in minimal environments, remote servers, or when you want to test custom X server configurations, the xinit tool becomes an indispensable ally. This small program lets you launch the X server and an initial client, usually a window manager or a desktop session, without needing a full display manager. In this article we will explore what xinit is, how it works internally, what options it offers, and how to adapt it to your needs via the .xinitrc file.
What is xinit?
Xinit is a client of the X Window System that initializes the X server (usually Xorg) and then runs a user‑specified program, which is typically a window manager, a desktop environment, or an isolated graphical application. Unlike display managers such as GDM, LightDM, or SDDM, xinit does not provide a login screen nor manage multiple users; its purpose is to be simple, scriptable, and useful for testing, automatic start‑ups, or single‑user sessions. It is included in practically every Linux distribution that ships Xorg, and invoking it from a text console lets you start the graphical environment with a single command.
How xinit works
When you run xinit, the program follows a well‑defined sequence. First, it looks for an available X server on the system; if none is explicitly given, it assumes Xorg is in the PATH and launches it with the default parameters. Then it sets the DISPLAY environment variable to point to the screen number it just created (for example :0). Next, it looks for the user’s initialization file, called .xinitrc, located in the home directory; if it finds it, it interprets it as a shell script and executes the commands it contains. If .xinitrc does not exist, xinit falls back to the system file /etc/X11/xinit/xinitrc, which normally launches a default window manager such as twm. Finally, it waits for the initial client to terminate; when that happens, it shuts down the X server and returns control to the terminal.
Most used options
- -e : Executes the specified program as the initial client, bypassing .xinitrc.
- -display : Forces the use of a specific screen number (e.g. :1).
- — : Everything placed after the double dash is passed directly to the X server (for example, -auth /var/run/xauth/A:0 -nolisten tcp).
- -? or -help: Shows xinit’s brief help.
Practical examples
To start a simple session with the twm window manager just run:
xinit
This will start Xorg and, since it does not find .xinitrc, it will run the system script that starts twm. If you prefer a more complete environment like XFCE, you can create a custom .xinitrc:
#!/bin/sh exec startxfce4
Then, from the console:
xinit
Or, explicitly specify the client with the -e option:
xinit -e startxfce4
If you want to use a secondary screen for testing, for example :1, you can combine:
xinit -- :1
This launches the X server on screen :1 and, if no client is specified, uses .xinitrc or the system default. Another useful variant is to pass options to the server, such as disabling TCP access:
xinit -- -nolisten tcp
Customizing .xinitrc
The .xinitrc file is a shell script that is executed each time xinit starts a session. Its format is free, but it usually contains:
- Environment variables (for example, export GTK_THEME=Adwaita).
- Programs you want to launch in the background, such as a panel or a note‑taking utility (e.g. tint2 &).
- The window manager or desktop environment that will run in the foreground, generally using exec to replace the xinit process (e.g. exec i3).
A typical example for a user who prefers i3 with a status bar:
#!/bin/sh # Load X resources xrdb -merge ~/.Xresources # Start the compositor picom & # Launch the status bar polybar top & # Run the window manager exec i3
Remember to make the file executable (chmod +x ~/.xinitrc) or simply let sh interpret it; xinit runs it with sh by default.
Common troubleshooting
- The X server fails to start and shows “cannot open display”. Verify that the user has permission to access /dev/tty and that no other X server is using the same screen number.
- The session exits immediately after starting. This usually means the client specified in .xinitrc terminates quickly; ensure the last command uses exec so it replaces the shell and keeps the process alive.
- Font or theme errors appear. Check that the paths specified in xrdb or in the window manager exist and that the font packages are installed.
- The keyboard or mouse does not respond. You may need to pass options to the server such as -audit 0 or use the correct driver in /etc/X11/xorg.conf.
- Using -display :1 gives “Server is already active for display 0”. Choose a free screen number or remove the temporary file /tmp/.X11-unix/X1.
Conclusion
Xinit is a lightweight yet powerful tool that gives you full control over the graphical environment start‑up in Linux. Its simplicity makes it ideal for debugging scenarios, embedded systems, customized workstations, or any situation where you want to avoid the overhead of a full display manager. By understanding how it works, its options, and how to customize .xinitrc, you can adapt the X server to almost any workflow—from a single graphical application to a full desktop with multiple helper programs. The next time you need to start X without intermediaries, remember that xinit is ready to serve you with a single command.