Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

356 Commits
LICENSE.md
LICENSE.md
 
 
README.md
README.md
 
 
auto-xorg
auto-xorg
 
 
auto-xorg.service
auto-xorg.service
 
 
installer.bash
installer.bash
 
 

Repository files navigation

Auto X.Org

v1.1.3

Automatically set the primary video output at boot-time given a video device is unavailable due to hardware pass-through (VFIO), or any other reason, in the X11 (X.Org) display server for a Linux machine.

💾 Download

View this repository on Codeberg, GitHub.

Table of Contents

Contents

❓ 1. Why?

By default, the X11 (X.Org) display server can detect one (1) or more GPUs, and use any or all for video output. However, should the default or first-detected (primary) GPU be unavailable or invalid, video output may break.

Reasons for breakage include:

  • Hardware/PCI pass-through or VFIO. This can affect all GPUs which share the same driver (of the same family or manufacturer).
  • Reservation by a running Virtual Machine (VM). This can affect all devices which share the same IOMMU group. To mitigate this, a user may patch the Host kernel with ACS override [1], however this is a possible security risk and is not recommended for most users.

Given this issue - sometimes, consecutive GPUs may only output to a Command Line Interface (CLI) or terminal.

What can Auto X.Org do? This script may automatically set a valid GPU at Host boot-time. The user may manually set a preferred GPU, as matched by the GPU manufacturer, should any one GPU be valid. This flexibility is very useful for a new or changing VFIO setup.

⚠️ Warning: To use Auto X.Org at Host run-time, one must safely exit the desktop (save and exit all applications), as the display manager (the entire desktop) will be restarted.

⚠️ Note: to hot-swap (hot-plug) or bind/unbind of GPUs, combine Auto X.Org with any of the following methods:

🛠️ 2. Related Projects

To view other relevant projects, visit Codeberg or GitHub.

📝 3. Documentation

  • What is IOMMU? [3]
  • What is VFIO? [4]
  • VFIO Discussion and Support [5]
  • Hardware/PCI Pass-through Guide [6]
  • Virtual Machine XML Format Guide [7]

✅ 4. Host Requirements

4.1. Operating System

Linux.

4.2. Software

  • systemd for system services.

  • xorg as the display server.

  • Other display servers are not supported:

    • wayland: The author has experienced problems with Wayland and an NVIDIA GPU, on Debian Linux (as of writing in 2024).

4.3. Hardware

  • A host with two (2) or more GPUs. This includes onboard graphics or an integrated GPU (iGPU) and one (1) or more dedicated GPU (dGPU).

  • A host with one (1) GPU. Auto X.Org is not recommended for this setup. By default, X.Org will use this GPU every time.

💾 5. Download

  • Download the Latest Release: Codeberg, GitHub

  • Download the .zip file:

    • From the webpage

      1. Viewing from the top of the repository's (current) webpage, click the drop-down icon:

        • ··· on Codeberg.
        • <> Code on GitHub.

      2. Click Download ZIP and save.

      3. Open the .zip file, then extract its contents.

    • From the CLI:

      1. Open the CLI.
      2. Download the Latest:
      GH_USER=portellam; \
GH_REPO=auto-xorg; \
GH_BRANCH=master; \
wget \
  https://github.com/${GH_USER}/${GH_REPO}/archive/refs/heads/${GH_BRANCH}.zip \
  -O "${GH_REPO}-${GH_BRANCH}.zip" \
&& unzip ./"${GH_REPO}-${GH_BRANCH}.zip" \
&& rm ./"${GH_REPO}-${GH_BRANCH}.zip"

  • Clone the repository:

    1. Open the CLI.

    2. Change your directory to your home folder or anywhere safe:

      • cd ~

    3. Clone the repository:

      • git clone https://www.codeberg.org/portellam/auto-xorg
      • git clone https://www.github.com/portellam/auto-xorg

❓ 6. Usage

6.1. The Command Interface (CLI) or Terminal

To open a CLI or Terminal:

  • Open a console emulator (for Debian systems: Konsole).

  • Linux only: Open an existing console: press CTRL + ALT + F2, F3, F4, F5, or F6.

    • To return to the desktop, press CTRL + ALT + F7.
    • F1 is reserved for debug output of the Linux kernel.
    • F7 is reserved for video output of the desktop environment.
    • F8 and above are unused.

6.2. Verify Installer is Executable

  1. Go to the directory where the cloned/extracted repository folder is: cd name_of_parent_folder/auto-xorg/

  2. Make the installer script file executable: chmod +x installer.bash

    • Do not make any other script files executable. The installer will perform this action.
    • Do not make any non-script file executable. This is not necessary and potentially dangerous.

6.3. Installer/Executable

  • From within the project folder, execute: sudo bash installer.bash

  • Or after installation, from any folder execute: sudo auto-xorg

    • The CLI's shell (bash) should recognize that the script file is located in /usr/local/bin.
      -h, --help              Print this help and exit.

Update X.Org:
  -r, --restart-display   Restart the display server immediately.

Set device order:
  -f, --first             Find the first valid VGA device.
  -l, --last              Find the last valid VGA device.

Prefer a vendor:
  -a, --amd               AMD or ATI
  -i, --intel             Intel
  -n, --nvidia            NVIDIA
  -o, --other             Any other manufacturer (past or future).

6.4. Examples

  • Set options to find the first valid AMD/ATI GPU, then install:

    sudo bash installer.bash \
  --first \
  --amd

  • Find the last valid NVIDIA GPU, then restart the display server immediately:

    sudo auto-xorg \
  --last \
  -nvidia \
  --restart-display

6.5. Troubleshooting

If the auto-xorg service fails, to diagnose review the log, execute:

sudo journalctl -u auto-xorg

Failure may be the result of absent GPU(s), or an exception. Review the log to debug.

💪 7. How Auto X.Org Works

  1. Runs once at boot (as a service) or run at user discretion.

  2. Parses a list of GPUs:

lspci -m \
  | grep \
    --extended-regexp \
    --ignore-case \
    'vga|graphics'
  1. Saves valid and available GPU:

Valid example, a driver which is not blacklisted:

  lspci \
      -k \
      -s 04:00.0 \
    | grep \
      --extended-regexp \
      --ignore-case \
      'driver|VGA'
  04:00.0 VGA compatible controller: ...
  Kernel driver in use: nvidia

Invalid example, a driver which is blacklisted:

  lspci \
      -k \
      -s 01:00.0 \
    | grep \
      --extended-regexp \
      --ignore-case \
      'driver|VGA'
  01:00.0 VGA compatible controller: ...
  Kernel driver in use: vfio-pci
  1. Appends to X.Org file: /etc/X11/xorg.conf.d/10-auto-xorg.conf

❗ 8. Filenames and Pathnames Modified by Auto X.Org

8.1. System Files

  • /etc/X11/xorg.conf.d/

8.2. Binaries and Files

  • /usr/local/bin/
  • /etc/systemd/system/

☎️ 9. Contact

Do you need help? Please visit the Issues page.

🌐 10. References

1.

  Bypassing the IOMMU groups (ACS override patch). ArchWiki. Accessed June 4, 2025.

    https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#Bypassing_the_IOMMU_groups_%28ACS_override_patch%29.

2.

  Misairu-G/[GUIDE] Optimus laptop dGPU passthrough.md. GitHub. Accessed June 3, 2025.

    https://gist.github.com/Misairu-G/616f7b2756c488148b7309addc940b28.

  You can now passthrough your dGPU as you wish with an Optimus laptop. Reddit. Accessed June 3, 2025.

    https://old.reddit.com/r/VFIO/comments/7d27sz/you_can_now_passthrough_your_dgpu_as_you_wish/.

3.

  Input-output memory management unit. Wikipedia. Accessed June 4, 2025.

    https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit.

4.

  VFIO - ‘Virtual Function I/O’ - The Linux Kernel Documentation. The linux kernel. Accessed June 14, 2024.

    https://www.kernel.org/doc/html/latest/driver-api/vfio.html.

5.

  VFIO Discussion and Support. Reddit. Accessed June 14, 2024.

    https://old.reddit.com/r/VFIO/.

6.

  PCI passthrough via OVMF. ArchWiki. Accessed June 14, 2024.

    https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF.

7.

  XML Design Format. GitHub - libvirt/libvirt. Accessed June 18, 2024.

    https://github.com/libvirt/libvirt/blob/master/docs/formatdomain.rst.

Click here to return to the top of this document.

About

Automatically set the primary video output at boot-time given a video device is unavailable due to hardware-passthrough (VFIO), or any other reason, in the X11 (X.Org) display server for a Linux machine.

Topics

bashpassthroughpciscriptsystemdsystemd-servicevfiovgax11xorg

Resources

Readme
GPL-3.0 license
Activity

Stars

13 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages