nvidia-xconfig(1)

📦
version 615.78.08 · 27 versions
, in arch rolling

🌸 NAME 🌸

okay so bestie, this is the General Commands Manual page for nvidia-xconfig(1) — and she is here to manipulate X configuration files for the NVIDIA driver. 💅

nvidia-xconfig — manipulate X configuration files for the NVIDIA driver.

🦋 SYNOPSIS 🦋

nvidia-xconfig [ options ]

💖 DESCRIPTION 💖

nvidia-xconfig is a tool meant to give you basic control over configuration options available in the NVIDIA X driver. She does her thing in several steps, and yes, we are going through every single one:

  1. The system X configuration file is found and read into memory. If no configuration file can be found, nvidia-xconfig generates one from scratch using default settings; in this case, nvidia-xconfig will write the configuration to /etc/X11/xorg.conf.
  2. The configuration in memory is modified to support the NVIDIA driver. This consists of changing the display driver to "nvidia", removing the commands to load the "GLcore" and "dri" modules, and adding the command to load the "glx" module.
  3. The configuration in memory is modified according to the options specified on the command line. Please see the NVIDIA README for a description of the NVIDIA X configuration file options. Note that nvidia-xconfig does not perform any validation of the X configuration file options requested on the command line; X configuration file option validation is left for the NVIDIA X driver. 👑 no cap, she is not the validator here.
  4. The configuration is written back to the file from which it was read. A backup of the original configuration is created with ".backup" appended. For example, if your X configuration is /etc/X11/xorg.conf then nvidia-xconfig will copy it to /etc/X11/xorg.conf.backup before writing the new configuration. The --post-tree (-T) option can be used to print the new configuration to standard out in tree form instead. This option is useful to see what nvidia-xconfig will do while leaving the original configuration intact.

The source code to nvidia-xconfig is released under the GPL and available here:

⟨https://download.nvidia.com/XFree86/nvidia-xconfig/⟩

Patches are welcome. 🫶

✨ OPTIONS ✨

  • -c XCONFIG, --xconfig=XCONFIG — use XCONFIG as the input X config file; if this option is not specified, then the same search path used by the X server will be used to find the X configuration file.
  • -o OUTPUT-XCONFIG, --output-xconfig=OUTPUT-XCONFIG — use OUTPUT-XCONFIG as the output X configuration file; if this option is not specified, then the input X configuration filename will also be used as the output X configuration filename.
  • -s, --silent — run silently; no messages will be printed to stdout, except for warning and error messages to stderr. 🤫
  • -t, --tree — read the X configuration file, print to stdout the X configuration data in a tree format, and exit. cute little peek, no writes.
  • -v, --version — print the nvidia-xconfig version and exit.
  • -h, --help — print usage information for the common commandline options and exit.
  • -A, --advanced-help — print usage information for the common commandline options as well as the advanced options, and then exit.

🔥 ADVANCED OPTIONS 🔥

  • --acpid-socket-path=ACPID-SOCKET-PATH, --no-acpid-socket-path — set this option to specify an alternate path to the Linux ACPI daemon (acpid)'s socket, which the NVIDIA X driver will use to connect to acpid.
  • --add-argb-glx-visuals, --no-add-argb-glx-visuals — enables or disables support for OpenGL rendering into 32-bit ARGB windows and pixmaps.
  • --allow-glx-with-composite, --no-allow-glx-with-composite — enable or disable the "AllowGLXWithComposite" X configuration option.
  • --busid=BUSID, --no-busid — this option writes the specified BusID to the device section of the X configuration file. If there are multiple device sections, then it adds the BusID field to each of them. To add the BusID to only a specific device or screen section, use the '--device' or '--screen' options.
  • --preserve-busid, --no-preserve-busid — by default, nvidia-xconfig preserves the existing BusID in the X configuration file only if there are multiple X screens configured for the X server. Use '--preserve-busid' or '--no-preserve-busid' to force the BusID to be preserved or not preserved, overriding the default behavior.
  • --cool-bits=COOL-BITS, --no-cool-bits — enable or disable the "Coolbits" X configuration option. Setting this option will enable support in the NV-CONTROL X extension for manipulating GPU clock and GPU fan control settings. Default value is 0. For fan control set it to 4. WARNING: this may cause system damage and void warranties. 💀Like, fr fr be careful.
  • --composite, --no-composite — enable or disable the "Composite" X extension.
  • --connected-monitor=CONNECTED-MONITOR, --no-connected-monitor — enable or disable the "ConnectedMonitor" X configuration option; setting this option forces the X driver to behave as if the specified display devices are connected to the GPU.
  • --connect-to-acpid, --no-connect-to-acpid — enable or disable the "ConnectToAcpid" X configuration option. If this option is set, the NVIDIA X driver will attempt to connect to the Linux ACPI daemon (acpid). Set this option to off to prevent the X driver from attempting to connect to acpid.
  • --constant-dpi, --no-constant-dpi — enable or disable the "ConstantDPI" X configuration option, which controls whether the NVIDIA X driver maintains a constant dots per inch (DPI) value by recomputing the reported size in millimeters of the X screen when XRandR changes the size in pixels of the X screen.
  • --custom-edid=CUSTOM-EDID, --no-custom-edid — enable or disable the "CustomEDID" X configuration option; setting this option forces the X driver to use the EDID specified. This option is a semicolon-separated list of pairs of display device names and filename pairs; e.g "CRT-0:mp\did.bin". Note that a display device name must always be specified even if only one EDID is specified.
  • --dac-8bit, --no-dac-8bit — most Quadro parts by default use a 10 bit color look up table (LUT) by default; setting this option to TRUE forces these graphics chips to use an 8 bit (LUT).
  • -d DEPTH, --depth=DEPTH — set the default depth to DEPTH; valid values for DEPTH are 8, 15, 16, 24, and 30.
  • --device=DEVICE — the nvidia-xconfig utility operates on one or more devices in the X configuration file. If this option is specified, the device named DEVICE in the X configuration file will be used. If this option is not specified, all the devices within the X configuration file will be used.
  • --disable-glx-root-clipping, --no-disable-glx-root-clipping — disable or enable clipping OpenGL rendering to the root window via the "DisableGLXRootClipping" X configuration option.
  • --damage-events, --no-damage-events — use OS-level events to notify the X server when a direct-rendering client has performed rendering that needs to be composited to the screen. Improves performance when using GLX with the composite extension.
  • --preserve-driver-name — by default nvidia-xconfig changes the display driver to "nvidia" for all configured X screens; this option preserves the existing driver name of each X screen.
  • --egpu, --no-egpu — enable or disable the "AllowExternalGpus" X configuration option.
  • -a, --enable-all-gpus — delete all existing X screens in the current configuration, then configure an X screen on every GPU in your system. main character energy for your GPUs, honestly.
  • --exact-mode-timings-dvi, --no-exact-mode-timings-dvi — forces the initialization of the X server with the exact timings specified in the ModeLine.
  • -E FILE, --extract-edids-from-file=FILE — extract any raw EDID byte blocks contained in the specified X log file LOG; raw EDID bytes are printed by the NVIDIA X driver to the X log as hexadecimal when verbose logging is enabled with the "-logverbose 6" X server commandline option. Any extracted EDIDs are then written as binary data to individual files. These files can later be used by the NVIDIA X driver through the "CustomEDID" X configuration option.
  • --extract-edids-output-file=FILENAME — when the '--extract-edids-from-file' option is used, nvidia-xconfig writes any extracted EDID to a file, typically "edid.bin" in the current directory. Use this option to specify an alternate filename. Note that nvidia-xconfig, if necessary, will append a unique number to the EDID filename, to avoid overwriting existing files (e.g., "edid.bin.1" if "edid.bin" already exists).
  • --flatpanel-properties=FLATPANEL-PROPERTIES, --no-flatpanel-properties — set the flat panel properties. The supported properties are 'dithering' and 'ditheringmode'. Please see the NVIDIA README 'Appendix B. X Config Options' for more details on the possible values and syntax.
  • --flip, --no-flip — enable or disable OpenGL flipping.
  • --force-generate — force generation of a new X config file, ignoring any existing system X config file. This is not typically recommended, as things like the mouse protocol, keyboard layout, font paths, etc, are setup by your Unix distribution. While nvidia-xconfig can attempt to infer these values, it is best to use your Unix distribution's X config file for the basis of anything that nvidia-xconfig creates.
  • --force-stereo-flipping, --no-force-stereo-flipping — normally, stereo flipping is only performed when a stereo drawable is visible. This option forces stereo flipping even when no stereo drawables are visible.
  • --handle-special-keys=WHEN, --no-handle-special-keys — specify when the X server should use the builtin keyboard handler to process special key combinations (such as Ctrl+Alt+Backspace); see the X configuration man page for details. The value of WHEN can be 'Always', 'Never', or 'WhenNeeded'.
  • --include-implicit-metamodes, --no-include-implicit-metamodes — enable or disable the "IncludeImplicitMetaModes" X configuration option.
  • --keyboard=KEYBOARD — so when nvidia-xconfig is out here generating a brand new X config file (which, to be clear, only happens when it literally cannot find a system X config file, or when you passed --force-generate), this tells it "bestie, use KEYBOARD as the keyboard type" instead of poking around the system trying to guess it. Want the full menu of keyboard types? That's the --keyboard-list option's whole thing 💅
  • --keyboard-driver=DRIVER — ngl, in most cases nvidia-xconfig figures out the right keyboard driver all on its own (it's either kbd or keyboard). This option is your override button for when you know better. Typical tea: if you're running an X.Org X server, use kdb; if you're on an XFree86 X server, use keyboard. ✨
  • --keyboard-list — prints all the available keyboard types that --keyboard actually recognizes to stdout, then dips out (exits). A little menu, no cap 🎀
  • --layout=LAYOUT — okay so the way nvidia-xconfig works, it operates on a Server Layout inside the X config file. Pass this and it'll use the layout named LAYOUT in that file. Don't pass it? It just grabs the first Server Layout in the file. Simple as that 🦋
  • --mode=MODE — adds the mode you specified to the mode list. That's it, that's the whole vibe ✨
  • --mode-debug, --no-mode-debug — turns the "ModeDebug" X configuration option on or off. When it's enabled, the X driver gets super chatty and prints verbose details about mode validation into the X log file. Very "tell me everything" energy 🔍
  • --mode-list=MODELIST — removes all existing modes from the X configuration's modelist and drops in the one(s) you specified in the MODELIST string instead. Clean slate, main character energy 💅
  • --remove-mode=MODE — yeets the specified mode out of the mode list 🙈
  • --metamodes=METAMODES — adds the MetaMode X configuration option with the value METAMODES, and it will replace any MetaMode option that was already chilling in the X configuration file. Out with the old, in with the new ✨
  • --mouse=MOUSE — same deal as the keyboard one, but for mice 🐭 When generating a new X config file (which happens when no system X config file can be found, or when --force-generate is specified), use MOUSE as the mouse type instead of probing the system for it. Possible mouse types live in the --mouse-list option.
  • --mouse-list — prints the available mouse types that --mouse recognizes to stdout, then exits. Menu time 🍓
  • --multisample-compatibility, --no-multisample-compatibility — enables or disables the use of separate front and back multisample buffers. Buffers, but make it two 💖
  • --nvidia-cfg-path=PATH — so the nvidia-cfg library is what talks to the NVIDIA kernel module to query basic properties of every GPU in the system. Normally nvidia-xconfig only touches this library when it's configuring multiple X screens. This option tells nvidia-xconfig where to look for the library, just in case it can't find it on its own. Honestly? You should normally not need this one at all 🫶
  • --only-one-x-screen — disables all but one X screen. One screen only. Solo era 💅
  • --overlay, --no-overlay — enable or disable the "Overlay" X configuration option.
  • --cioverlay, --no-cioverlay — enable or disable the color index overlay 🌈
  • --overlay-default-visual, --no-overlay-default-visual — enable or disable the "OverlayDefaultVisual" X configuration option.
  • --transparent-index=INDEX, --no-transparent-index — the pixel to use as transparent when you're using color index overlays. Valid values for TRANSPARENT-INDEX are 0-255. Like, the whole range, bestie ✨
  • -T, --post-tree — okay so this is like the --tree option, but it goes through the full process of applying any updates you requested to the X configuration first, and then prints the final config to stdout in a tree format. Effectively it just means the config gets printed to stdout as a tree instead of the results being written to a file. Same result, different delivery method 🌸
  • --power-connector-check, --no-power-connector-check — disables or enables the "NoPowerConnectorCheck" X configuration option. (Yes, the wording is flipped like that — that's just how it is, iykyk 💀)
  • --probe-all-gpus, --no-probe-all-gpus — disables or enables the "ProbeAllGpus" X configuration option. Also flipped wording. We keep it moving ✨
  • --query-gpu-info — prints information about every NVIDIA GPU it recognizes in the system. GPU roll call, everybody say hi 👑 🔥
  • --registry-dwords=REGISTRY-DWORDS, --no-registry-dwords — enable or disable the "RegistryDwords" X configuration option.
  • --render-accel, --no-render-accel — enable or disable the "RenderAccel" X configuration option. Accelerate, bestie 🦋
  • --render-extension, --no-render-extension — disable or enable the "NoRenderExtension" X configuration option. (Flipped again — the option is literally called NoRenderExtension, so enabling it disables the thing. Iconic confusion, no notes 😭)
  • --screen=SCREEN — nvidia-xconfig operates on one or more screens within a Server Layout in the X config file. Pass this and it uses the screen named SCREEN in that file. Skip it and it uses all the screens within the selected Server Layout in the X config file. All of them, periodt 💅
  • --separate-x-screens, --no-separate-x-screens — a GPU that supports multiple simultaneous display devices can either drive those displays in a single X screen, or as separate X screens. With --separate-x-screens, every GPU that currently has an X screen configured gets updated to have two or more X screens configured (the exact number depends on what that GPU can actually do). And --no-separate-x-screens removes any extra configured X screens on each GPU. Full details live in the NVIDIA README description of "Separate X Screens on One GPU" — go read it, it's giving lore ✨
  • --x-screens-per-gpu=X-SCREENS-PER-GPU — same situation: a GPU that supports multiple simultaneous display devices can drive them all in a single X screen, or as separate X screens. When you pass --x-screens-per-gpu=<quantity>, every GPU that currently has an X screen configured gets updated to have <quantity> X screens. Important: <quantity> has to be greater than 0. Setting <quantity> to 1 is equivalent to specifying --no-separate-x-screens. And again, check the NVIDIA README description of "Separate X Screens on One GPU" for the deep dive 🧚
  • --sli=SLI, --no-sli — enable or disable SLI. Valid values for SLI are 'Off' and 'Mosaic'. That's the whole list, don't come at me 💀
  • --stereo=STEREO, --no-stereo — enable or disable the stereo mode. Valid values for STEREO are: 0 (Disabled), 1 (DDC glasses), 2 (Blueline glasses), 3 (Onboard stereo), 4 (multi-display clone mode stereo), 5 (SeeReal digital flat panel), 6 (Sharp3D digital flat panel), 7 (Arisawa/Hyundai/Zalman/Pavione/Miracube), 8 (3D DLP), 9 (3D DLP INV), 10 (NVIDIA 3D VISION), 11 (NVIDIA 3D VISION PRO), 12 (HDMI 3D), 13 (Tridelity SL). Whew. Thirteen whole flavors of 3D, we're so back 🕶️
  • --thermal-configuration-check, --no-thermal-configuration-check — disables or enables the "ThermalConfigurationCheck" X configuration option. Keep it cool, literally 🌬️
  • --metamode-orientation=ORIENTATION, --no-metamode-orientation — specifies the MetaModeOrientation. Valid values for ORIENTATION are: "RightOf" (the default), "LeftOf", "Above", "Below", or "Clone". Positional queen energy 👑
  • --nvidia-xinerama-info, --no-nvidia-xinerama-info — enable or disable providing Xinerama information from the NVIDIA X driver.
  • --nvidia-xinerama-info-order=NVIDIA-XINERAMA-INFO-ORDER, --no-nvidia-xinerama-info-order — enable or disable the "nvidiaXineramaInfoOrder" X configuration option. NVIDIA-XINERAMA-INFO-ORDER is a comma-separated list of display device names that describes the order in which nvidiaXineramaInfo should be reported. Example: "CRT, DFP, TV". Order matters, always 🌈
  • --ubb, --no-ubb — enable or disable the "UBB" X configuration option.
  • --use-edid, --no-use-edid — enable or disable use of the EDID (Extended Display Identification Data) from your display device(s). The EDID gets used for driver stuff like building lists of available modes, figuring out valid frequency ranges, and computing the DPI (Dots Per Inch). This option defaults to TRUE (the NVIDIA X driver will use the EDID, when available).
🚨 Real talk: it is NOT recommended that you use this option to globally disable use of the EDID. Instead, use --no-use-edid-freqs or --no-use-edid-dpi to disable the specific uses you actually want gone. Global off is not the move, bestie 💀
  • --use-edid-dpi, --no-use-edid-dpi — enable or disable use of the physical size information in the display device's EDID (if there is any) to compute the DPI (Dots Per Inch) of the X screen. Defaults to TRUE — the NVIDIA X driver uses the EDID's physical size, when available, to compute the DPI ✨
  • --use-edid-freqs, --no-use-edid-freqs — enable or disable use of the HorizSync and VertRefresh ranges given in a display device's EDID (if any). Heads up: EDID-provided range info will override the HorizSync and VertRefresh ranges specified in the Monitor section. Defaults to TRUE — the NVIDIA X driver will use frequency information from the EDID, when available 🌸
  • --use-display-device=DISPLAY-DEVICE, --no-use-display-device — forces the X driver to use the display device you specified. No negotiating, it's that one 💅
  • --use-events, --no-use-events — enable or disable the "UseEvents" X configuration option. Setting this enables the X driver to use system events in some cases when it's waiting on the hardware. With this option, the X driver sets an event handler and waits for the hardware through the poll() system call. This option defaults to FALSE ⏳
  • --virtual=WIDTHxHEIGHT, --no-virtual — specifies the virtual screen resolution. It's giving WIDTHxHEIGHT, keep the x 🦋
  • --x-prefix=X-PREFIX — the X installation prefix; the default is /usr/X11R6/. Only under rare circumstances should you need this option, so like... don't touch it unless you have to 🎀
  • --color-space=COLORSPACE, --no-color-space — enable or disable the "ColorSpace" X configuration option. Valid values for "COLORSPACE" are: "RGB" and "YCbCr444" 🌈
  • --color-range=COLORRANGE, --no-color-range — sets the "ColorRange" X configuration option. Valid values for "COLORRANGE" are: "Full" and "Limited". Full range or limited range, pick your fighter ⭐
  • --3dvision-usb-path=3DVISION-USB-PATH — set this option to specify the sysfs path of the connected USB dongle. Dongle located 🎀
  • --3dvisionpro-config-file=3DVISIONPRO-CONFIG-FILE — tells nvidia-xconfig where the NVIDIA 3DVisionPro config file lives. bestie, make sure the X server can read AND write that file, ok? the NVIDIA X driver stashes the hub + pairing config in there so it survives X restarts 🔁. if you don't pass this option, your 3D VisionPro config just... won't be stored. gone. poof. 💀
  • --3dvision-display-type=3DVISION-DISPLAY-TYPE, --no-3dvision-display-type — for when NVIDIA 3D Vision is on but your display isn't 3D Vision ready (rude of it tbh) — use this to spell out the display type. valid values are: 0 (assume it's a CRT), 1 (assume it's a DLP) and 2 (assume it's a DLP TV and turn on the checkerboard output) ✨
  • --base-mosaic, --no-base-mosaic — turns the "BaseMosaic" X configuration option on or off 🎀
  • --restore-original-backup — restores a backup of your X config that was made before nvidia-xconfig did literally anything to it — but only if that backup exists. this special backup happens when nvidia-xconfig edits an X config file it's never touched before (which we assume is a file that predates the NVIDIA X driver ever showing up 👶). for example: nvidia-xconfig will copy /etc/X11/xorg.conf to /etc/X11/xorg.conf.nvidia-xconfig-original the very first time it makes changes to that file. cute, right? 🫶
  • --allow-empty-initial-configuration, --no-allow-empty-initial-configuration — lets the X server start even when it detected zero connected display devices 😭 (yes, truly. not a single one.)
  • --inband-stereo-signaling, --no-inband-stereo-signaling — turns the "InbandStereoSignaling" X configuration option on or off ✨
  • --force-yuv-420, --no-force-yuv-420 — turns the "ForceYUV420" X configuration option on or off. so here's the vibe: if your current display and GPU both support uncompressed RGB 4:4:4 output and YUV 4:2:0 compressed output with the current mode, then RGB 4:4:4 wins by default. this option forces YUV 4:2:0 output instead (where it's supported). main character choice of you 💅
  • --force-composition-pipeline=FORCE-COMPOSITION-PIPELINE, --no-force-composition-pipeline — turns the "ForceCompositionPipeline" X configuration option on or off 🌸
  • --force-full-composition-pipeline=FORCE-FULL-COMPOSITION-PIPELINE, --no-force-full-composition-pipeline — turns the "ForceFullCompositionPipeline" X configuration option on or off 🌸
  • --allow-hmd=ALLOW-HMD, --no-allow-hmd — turns the "AllowHMD" X configuration option on or off 🦋
  • --prime, --no-prime — enables PRIME for the generated X config file. ⚠️ cannot be run with --no-busid or --no-allow-empty-initial-configuration. on a system with more than 1 GPU, tell it which GPU to use for PRIME with --busid, otherwise the first available one gets picked (no thoughts, head empty). and heads up: to actually enable PRIME you gotta run these after it's done:
xrandr --setprovideroutputsource modesetting NVIDIA-0
xrandr --auto

🌈 EXAMPLES 🌈

  • nvidia-xconfig — reads an existing X config file and adapts it to use the NVIDIA driver. if no X config file can be found, it makes a brand new one at /etc/X11/xorg.conf with default settings ✨
  • nvidia-xconfig --post-tree --metamode-orientation=clone — reads the existing X configuration file, adds the MetaModeOrientation option, and then prints the resulting config file to standard out in tree form 🌳. the configuration file itself is not modified, king behavior honestly 👑
  • nvidia-xconfig --enable-all-gpus — examines the system and configures an X screen for each display device it finds 👀
  • nvidia-xconfig --mode=1600x1200 — adds a 1600x1200 mode to an existing X configuration 🎀
  • nvidia-xconfig --mode-list=1600x1200 1280x1024 — removes any existing modes from the X configuration file and replaces them with "1600x1200" and "1280x1024" ✨
  • nvidia-xconfig --metamodes=1024x768 +0+0, 1024x768 +1024+0 — adds the MetaMode "1024x768 +0+0, 1024x768 +1024+0" to the existing X configuration file, replacing any existing MetaModes X configuration option 💅
  • nvidia-xconfig --only-one-x-screen --sli=Auto — configures the X server to have just one X screen that will use SLI when it's available ⚡

👑 AUTHOR 👑

Aaron Plattner NVIDIA Corporation

🦋 SEE ALSO 🦋

nvidia-settings(1), /usr/share/doc/NVIDIA_GLX-1.0/README.txt

Copyright © 2005-2010 NVIDIA Corporation.

okay bestie that's the whole thing, you're officially an nvidia-xconfig scholar 🎓✨ this masterpiece is from nvidia-xconfig 615.78.08, dated 2026-10-06, and it lives at nvidia-xconfig(1) — go forth and configure responsibly, ily, bye 🫶💜

📦 where this page comes from
  • arch rolling: nvidia-utils 615.78.08-1 · LicenseRef-NVIDIA-Driver-License-Agreement
  • Copyright (C) 2005-2010 NVIDIA Corporation
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms