{"id":16494536,"url":"https://github.com/portellam/auto-xorg","last_synced_at":"2025-07-27T16:09:04.523Z","repository":{"id":53920405,"uuid":"479233402","full_name":"portellam/auto-xorg","owner":"portellam","description":"Automatically set the primary video output at boot-time given a video device (VGA) is unavailable due to hardware-passthrough (VFIO) or any other reason, in the X11 (X.Org) display server for a Linux machine.","archived":false,"fork":false,"pushed_at":"2025-06-04T08:11:36.000Z","size":294,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-04T09:16:37.783Z","etag":null,"topics":["bash","passthrough","pci","script","systemd","systemd-service","vfio","vga","x11","xorg"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/portellam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-04-08T03:40:07.000Z","updated_at":"2025-06-04T03:52:01.000Z","dependencies_parsed_at":"2024-03-25T08:46:13.854Z","dependency_job_id":"0f518a02-d01b-45cd-a2a5-ae138aab1dd2","html_url":"https://github.com/portellam/auto-xorg","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/portellam/auto-xorg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portellam%2Fauto-xorg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portellam%2Fauto-xorg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portellam%2Fauto-xorg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portellam%2Fauto-xorg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/portellam","download_url":"https://codeload.github.com/portellam/auto-xorg/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portellam%2Fauto-xorg/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267384041,"owners_count":24078573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","passthrough","pci","script","systemd","systemd-service","vfio","vga","x11","xorg"],"created_at":"2024-10-11T14:14:17.291Z","updated_at":"2025-07-27T16:09:04.516Z","avatar_url":"https://github.com/portellam.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auto X.Org\n\n### v1.1.3\n\nAutomatically set the primary video output at boot-time given a video device\nis unavailable due to hardware pass-through (VFIO), or any other reason,\nin the **X11 (X.Org)** display server for a Linux machine.\n\n## [💾 Download](#-5-download)\n\n#### View this repository on [Codeberg][01], [GitHub][02].\n\n[01]: https://codeberg.org/portellam/auto-xorg\n[02]: https://github.com/portellam/auto-xorg\n\n##\n\n## Table of Contents\n\n- [❓ 1. Why?](#-1-why)\n- [🛠️ 2. Related Projects](#️-2-related-projects)\n- [📝 3. Documentation](#-3-documentation)\n\n- [✅ 4. Host Requirements](#-4-host-requirements)\n  - [4.1. Operating System](#41-operating-system)\n  - [4.2. Software](#42-software)\n  - [4.3. Hardware](#43-hardware)\n\n- [💾 5. Download](#-5-download)\n\n- [❓ 6. Usage](#-6-usage)\n  - [6.1. The Command Interface (CLI) or Terminal](#61-the-command-interface-cli-or-terminal)\n  - [6.2. Verify Installer is Executable](#62-verify-script-is-executable)\n  - [6.3. Installer/Executable](#63-installerexecutable)\n  - [6.4. Examples](#64-examples)\n  - [6.5. Troubleshooting](#65-troubleshooting)\n\n- [💪 7. How *Auto X.Org* Works](#-7-how-auto-xorg-works)\n\n- [❗ 8. Filenames and Pathnames Modified by *Auto X.Org*](#-8-filenames-and-pathnames-modified-by-auto-xorg)\n  - [8.1. System Files](#81-system-files)\n  - [8.2. Binaries and Files](#82-binaries-and-files)\n\n- [☎️ 9. Contact](#️-9-contact)\n- [🌐 10. References](#-10-references)\n\n## Contents\n\n### ❓ 1. Why?\n\nBy default, the **X11 (X.Org)** display server can detect one (1) or more\nGPUs, and use any or all for video output. However, should the default or\nfirst-detected (primary) GPU be unavailable or invalid, video output may\nbreak.\n\n**Reasons for breakage include:**\n\n- **[*Hardware/PCI pass-through* or *VFIO*](#3-documentation).** This can\n  affect all GPUs which share the same driver\n  (of the same family or manufacturer).\n- ***Reservation by a running Virtual Machine (VM).*** This can affect all\n  devices which share the same [IOMMU group](#3-documentation). To mitigate\n  this, a user may patch the Host kernel with\n  [*ACS override* \u003csup\u003e\\[1\\]\u003c/sup\u003e](#1), however this is a possible security\n  risk and *is not recommended for most users.*\n\n**Given this issue - sometimes, consecutive GPUs may only output to a Command**\n**Line Interface (CLI) or terminal.**\n\n**What can *Auto X.Org do*?** This script may automatically set a valid GPU\nat Host boot-time. The user may manually set a preferred GPU, as matched by\nthe GPU manufacturer, should any one GPU be valid. This flexibility is very\nuseful for a new or changing VFIO setup.\n\n⚠️ **Warning:** To use *Auto X.Org* at Host run-time, one must safely exit the\ndesktop (save and exit all applications), as the display manager (the entire\ndesktop) will be restarted.\n\n⚠️ **Note:** to hot-swap (hot-plug) or bind/unbind of GPUs, combine *Auto X.Org*\nwith any of the following methods:\n\n- [Optimus\u003csup\u003e\\[2\\]\u003c/sup\u003e](#2)\n\n### 🛠️ 2. Related Projects\n\nTo view other relevant projects, visit [Codeberg][21]\nor [GitHub][22].\n\n[21]: https://codeberg.org/portellam/vfio-collection\n[22]: https://github.com/portellam/vfio-collection\n\n### 📝 3. Documentation\n\n- What is IOMMU? [\u003csup\u003e\\[3\\]\u003c/sup\u003e](#3)\n- What is VFIO? [\u003csup\u003e\\[4\\]\u003c/sup\u003e](#4)\n- VFIO Discussion and Support [\u003csup\u003e\\[5\\]\u003c/sup\u003e](#5)\n- Hardware/PCI Pass-through Guide [\u003csup\u003e\\[6\\]\u003c/sup\u003e](#6)\n- Virtual Machine XML Format Guide [\u003csup\u003e\\[7\\]\u003c/sup\u003e](#7)\n\n### ✅ 4. Host Requirements\n\n#### 4.1. Operating System\n\nLinux.\n\n#### 4.2. Software\n\n- `systemd` for system services.\n- `xorg` as the display server.\n\n- Other display servers are not supported:\n  - `wayland`: The author has experienced problems with Wayland and an NVIDIA\n    GPU, on Debian Linux (as of writing in 2024).\n\n#### 4.3. Hardware\n\n- **A host with two (2) or more GPUs.** This includes onboard graphics or an\nintegrated GPU (iGPU) and one (1) or more dedicated GPU (dGPU).\n\n- **A host with one (1) GPU**. *Auto X.Org is not recommended for this setup.*\n*By default, X.Org will use this GPU every time.*\n\n### 💾 5. Download\n\n- Download the Latest Release: [Codeberg][51], [GitHub][52]\n\n- Download the `.zip` file:\n\n  - From the webpage\n\n    1. Viewing from the top of the repository's (current) webpage, click the\n       drop-down icon:\n\n       - `···` on Codeberg.\n       - `\u003c\u003e Code ` on GitHub.\n\n    2. Click `Download ZIP` and save.\n    3. Open the `.zip` file, then extract its contents.\n\n  - From the CLI:\n\n    1. [Open the CLI](#61-the-command-interface-cli-or-terminal).\n    2. Download the Latest:\n\n    ```bash\n    GH_USER=portellam; \\\n    GH_REPO=auto-xorg; \\\n    GH_BRANCH=master; \\\n    wget \\\n      https://github.com/${GH_USER}/${GH_REPO}/archive/refs/heads/${GH_BRANCH}.zip \\\n      -O \"${GH_REPO}-${GH_BRANCH}.zip\" \\\n    \u0026\u0026 unzip ./\"${GH_REPO}-${GH_BRANCH}.zip\" \\\n    \u0026\u0026 rm ./\"${GH_REPO}-${GH_BRANCH}.zip\"\n    ```\n\n- Clone the repository:\n\n  1. [Open the CLI](#61-the-command-interface-cli-or-terminal).\n\n  2. Change your directory to your home folder or anywhere safe:\n     - `cd ~`\n\n  3. Clone the repository:\n     - `git clone https://www.codeberg.org/portellam/auto-xorg`\n     - `git clone https://www.github.com/portellam/auto-xorg`\n\n[51]: https://codeberg.org/portellam/auto-xorg/releases/latest\n[52]: https://github.com/portellam/auto-xorg/releases/latest\n\n### ❓ 6. Usage\n\n#### 6.1. The Command Interface (CLI) or Terminal\n\nTo open a CLI or Terminal:\n\n- Open a console emulator (for Debian systems: Konsole).\n- **Linux only:** Open an existing console: press `CTRL` + `ALT` + `F2`,\n  `F3`, `F4`, `F5`, or `F6`.\n\n  - **To return to the desktop,** press `CTRL` + `ALT` + `F7`.\n  - `F1` is reserved for debug output of the Linux kernel.\n  - `F7` is reserved for video output of the desktop environment.\n  - `F8` and above are unused.\n\n#### 6.2. Verify Installer is Executable\n\n1. Go to the directory where the cloned/extracted repository folder is:\n   `cd name_of_parent_folder/auto-xorg/`\n\n2. Make the installer script file executable: `chmod +x installer.bash`\n\n   - Do **not** make any other script files executable. The installer will\n    perform this action.\n   - Do **not** make any non-script file executable. This is not necessary and\n     potentially dangerous.\n\n#### 6.3. Installer/Executable\n\n- From within the project folder, execute: `sudo bash installer.bash`\n- Or after installation, from any folder execute: `sudo auto-xorg`\n\n  - The CLI's shell (bash) should recognize that the script file is located in\n    `/usr/local/bin`.\n\n  ```\n    -h, --help              Print this help and exit.\n\n  Update X.Org:\n    -r, --restart-display   Restart the display server immediately.\n\n  Set device order:\n    -f, --first             Find the first valid VGA device.\n    -l, --last              Find the last valid VGA device.\n\n  Prefer a vendor:\n    -a, --amd               AMD or ATI\n    -i, --intel             Intel\n    -n, --nvidia            NVIDIA\n    -o, --other             Any other manufacturer (past or future).\n  ```\n\n#### 6.4. Examples\n- Set options to **find the first valid AMD/ATI GPU,** then install:\n\n  ```bash\n  sudo bash installer.bash \\\n    --first \\\n    --amd\n  ```\n\n- **Find the last valid NVIDIA GPU,** then restart the display server immediately:\n\n  ```bash\n  sudo auto-xorg \\\n    --last \\\n    -nvidia \\\n    --restart-display\n  ```\n\n#### 6.5. Troubleshooting\n\nIf the `auto-xorg` service fails, to diagnose review the log, execute:\n\n```bash\nsudo journalctl -u auto-xorg\n```\n\nFailure may be the result of absent GPU(s), or an exception. Review the log to\ndebug.\n\n### 💪 7. How *Auto X.Org* Works\n\n1. Runs once at boot (as a service) or run at user discretion.\n\n2. Parses a list of GPUs:\n\n  ```bash\n  lspci -m \\\n    | grep \\\n      --extended-regexp \\\n      --ignore-case \\\n      'vga|graphics'\n  ```\n\n3. Saves valid and available GPU:\n\n  **Valid example,** a driver which is *not blacklisted*:\n\n  ```bash\n    lspci \\\n        -k \\\n        -s 04:00.0 \\\n      | grep \\\n        --extended-regexp \\\n        --ignore-case \\\n        'driver|VGA'\n  ```\n\n  ```\n    04:00.0 VGA compatible controller: ...\n    Kernel driver in use: nvidia\n  ```\n\n  **Invalid example,** a driver which *is blacklisted*:\n\n  ```bash\n    lspci \\\n        -k \\\n        -s 01:00.0 \\\n      | grep \\\n        --extended-regexp \\\n        --ignore-case \\\n        'driver|VGA'\n  ```\n\n  ```\n    01:00.0 VGA compatible controller: ...\n    Kernel driver in use: vfio-pci\n  ```\n\n4. Appends to X.Org file: `/etc/X11/xorg.conf.d/10-auto-xorg.conf`\n\n### ❗ 8. Filenames and Pathnames Modified by *Auto X.Org*\n\n#### 8.1. System Files\n\n- `/etc/X11/xorg.conf.d/`\n\n#### 8.2. Binaries and Files\n\n- `/usr/local/bin/`\n- `/etc/systemd/system/`\n\n### ☎️ 9. Contact\n\nDo you need help? Please visit the [Issues][91] page.\n\n[91]: https://github.com/portellam/auto-xorg/issues\n\n### 🌐 10. References\n\n#### 1.\n\n\u0026nbsp;\u0026nbsp;**Bypassing the IOMMU groups (ACS override patch)**. ArchWiki.\nAccessed June 4, 2025.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#Bypassing_the_IOMMU_groups_%28ACS_override_patch%29.\u003c/sup\u003e\n\n#### 2.\n\n\u0026nbsp;\u0026nbsp;**Misairu-G/[GUIDE] Optimus laptop dGPU passthrough.md**. GitHub.\nAccessed June 3, 2025.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://gist.github.com/Misairu-G/616f7b2756c488148b7309addc940b28.\u003c/sup\u003e\n\n\u0026nbsp;\u0026nbsp;**You can now passthrough your dGPU as you wish with an Optimus**\n**laptop**. Reddit. Accessed June 3, 2025.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://old.reddit.com/r/VFIO/comments/7d27sz/you_can_now_passthrough_your_dgpu_as_you_wish/.\u003c/sup\u003e\n\n#### 3.\n\n\u0026nbsp;\u0026nbsp;**Input-output memory management unit**. Wikipedia. Accessed\nJune 4, 2025.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit.\u003c/sup\u003e\n\n#### 4.\n\n\u0026nbsp;\u0026nbsp;**VFIO - ‘Virtual Function I/O’ - The Linux Kernel Documentation**.\nThe linux kernel. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://www.kernel.org/doc/html/latest/driver-api/vfio.html.\u003c/sup\u003e\n\n#### 5.\n\n\u0026nbsp;\u0026nbsp;**VFIO Discussion and Support**. Reddit. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://old.reddit.com/r/VFIO/.\u003c/sup\u003e\n\n#### 6.\n\u0026nbsp;\u0026nbsp;**PCI passthrough via OVMF**. ArchWiki. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://wiki.archlinux.org/title/PCI_passthrough_via_OVMF.\u003c/sup\u003e\n\n#### 7.\n\n\u0026nbsp;\u0026nbsp;**XML Design Format**. GitHub - libvirt/libvirt. Accessed June 18, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://github.com/libvirt/libvirt/blob/master/docs/formatdomain.rst.\u003c/sup\u003e\n\n##\n\n#### Click [here](#auto-xorg) to return to the top of this document.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fportellam%2Fauto-xorg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fportellam%2Fauto-xorg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fportellam%2Fauto-xorg/lists"}