nvidia-settings(1)

📦
version 615.78.08 · 4 versions
, in arch rolling

💅 NAME 💅

nvidia-settings — configure the NVIDIA graphics driver. That's the whole main-character mission, bestie. This is the nvidia-settings(1) page from the General Commands Manual, and we're about to get into every detail. 🫶

✨ SYNOPSIS ✨

Okay so here are all the shapes this command can take:

nvidia-settings [options]
nvidia-settings [options] --no-config
nvidia-settings [options] --load-config-only
nvidia-settings [options] {--query=attr | --assign=attr=value} ...
nvidia-settings [options] --glxinfo

Options: [-vh] [--config=configfile] [-c ctrl-display]
         [--verbose={none | errors | deprecations | warnings | all}]
         [--describe={all | list | attribute_name}]

attr has the form:
     DISPLAY/attribute_name[display_devices]

🦋 DESCRIPTION 🦋

The nvidia-settings utility is literally a tool for configuring the NVIDIA graphics driver. It works by talking to the NVIDIA X driver, querying and updating state as appropriate. That communication happens via the NV-CONTROL, GLX, XVideo, and RandR X extensions. 👑

Things like brightness and gamma, XVideo attributes, temperature, and OpenGL settings can all be queried and configured via nvidia-settings.

When nvidia-settings starts, it reads the current settings from its configuration file and sends those settings to the X server. Then it displays a graphical user interface (GUI) for configuring the current settings. When nvidia-settings exits, it queries the current settings from the X server and saves them to the configuration file. The full little lifecycle, no cap. 🌈

🎀 OPTIONS 🎀

  • -v, --version — print the nvidia-settings version and exit.
  • -h, --help — print usage information and exit.
  • --config=CONFIG — use the configuration file CONFIG rather than the default ~/.nvidia-settings-rc.
  • -c CTRL-DISPLAY, --ctrl-display=CTRL-DISPLAY — control the specified X display. If this option is not given, then nvidia-settings will control the display specified by '--display'; if that is not given, then the $DISPLAY environment variable is used.
  • -l, --load-config-only — load the configuration file, send the values specified therein to the X server, and exit. This mode of operation is useful to place in your xinitrc file, for example.
  • -n, --no-config — do not load the configuration file. This mode of operation is useful if nvidia-settings has difficulties starting due to problems with applying settings in the configuration file.
  • -r, --rewrite-config-file — write the X server configuration to the configuration file, and exit, without starting the graphical user interface. See the EXAMPLES section.
  • -V VERBOSE, --verbose=VERBOSE — controls how much information is printed. Valid values are 'none' (do not print status messages), 'errors' (print error messages), 'deprecations' (print error and deprecation messages), 'warnings' (print error, deprecation, and warning messages), and 'all' (print error, deprecation, warning and other informational messages). By default, 'deprecations' is set.
  • -a ASSIGN, --assign=ASSIGN — the ASSIGN argument to the '--assign' command line option is of the form:
{DISPLAY}/{attribute name}[{display devices}]={value}

This assigns the attribute {attribute name} to the value {value} on the X Display {DISPLAY}. {DISPLAY} follows the usual {host}:{display}.{screen} syntax of the DISPLAY environment variable and is optional; when it is not specified, then it is implied following the same rule as the --ctrl-display option. If the X screen is not specified, then the assignment is made to all X screens. Note that the '/' is only required when {DISPLAY} is present.

{DISPLAY} can additionally include a target specification to direct an assignment to something other than an X screen. A target specification is contained within brackets and consists of a target type name, a colon, and the target id. The target type name can be one of screen, gpu, framelock, fan, thermalsensor, svp, or dpy; the target id is the index into the list of targets (for that target type). The target specification can be used in {DISPLAY} wherever an X screen can be used, following the syntax {host}:{display}[{target_type}:{target_id}]. See the output of

nvidia-settings -q all

for information on which target types can be used with which attributes. See the output of

nvidia-settings -q screens -q gpus -q framelocks -q fans -q thermalsensors -q svps -q dpys

for lists of targets for each target type.

The [{display devices}] portion is also optional; if it is not specified, then the attribute is assigned to all display devices.

Some examples:

-a FSAA=5
-a localhost:0.0/DigitalVibrance[CRT-0]=0
--assign="SyncToVBlank=1"
-a [gpu:0]/DigitalVibrance[DFP-1]=63
  • -q QUERY, --query=QUERY — the QUERY argument to the '--query' command line option is of the form:
{DISPLAY}/{attribute name}[{display devices}]

This queries the current value of the attribute {attribute name} on the X Display {DISPLAY}. The syntax is the same as that for the '--assign' option, without '= {value}'; specify -q screens, -q gpus, -q framelocks, -q fans, -q thermalsensors, -q svps, or -q dpys to query a list of X screens, GPUs, Frame Lock devices, Visual Computing Systems, Devices, Fans, Thermal Sensors, 3D Vision Pro Transceivers, or Display Devices, respectively, that are present on the X Display {DISPLAY}. Specify -q all to query all attributes.

  • -t, --terse — when querying attribute values with the '--query' command line option, only print the current value, rather than the more verbose description of the attribute, its valid values, and its current value.
  • -d, --display-device-string — when printing attribute values in response to the '--query' option, if the attribute value is a display device mask, print the value as a list of display devices (e.g., "CRT-0, DFP-0"), rather than a hexadecimal bit mask (e.g., 0x00010001).
  • -g, --glxinfo — print GLX Information for the X display and exit.
  • -E, --eglinfo — print EGL Information for the X display and exit.
  • -k, --vulkaninfo — print Vulkan Information for the X display and exit.
  • -e DESCRIBE, --describe=DESCRIBE — prints information about a particular attribute. Specify 'all' to list the descriptions of all attributes. Specify 'list' to list the attribute names without descriptions.
  • -p PAGE, --page=PAGE — the PAGE argument to the '--page' commandline option selects a particular page in the nvidia-settings user interface to display upon starting nvidia-settings. Valid values are the page names in the tree view on the left side of the nvidia-settings user interface; e.g.,
--page="X Screen 0"

Because some page names are not unique (e.g., a "PowerMizer" page is present under each GPU), the page name can optionally be prepended with the name of the parent X Screen or GPU page, followed by a comma. E.g.,

--page="GPU 0 - (Quadro 6000), PowerMizer"

The first page with a name matching the PAGE argument will be used. By default, the "System Information" page is displayed.

  • -L, --list-targets-only — when performing an attribute query (from the '--query' command line option) or an attribute assignment (from the '--assign' command line option or when loading an ~/.nvidia-settings-rc file), nvidia-settings identifies one or more targets on which to query/assign the attribute.

The '--list-targets-only' option will cause nvidia-settings to list the targets on which the query/assign operation would have been performed, without actually performing the operation(s), and exit.

  • -w, --write-config, --no-write-config — save the configuration file on exit (enabled by default).
  • -i, --use-gtk2 — force nvidia-settings to use the GTK+ 2 library for the graphical user interface if a user interface is required. This option is only available on systems where nvidia-settings supports both the GTK+ 2 and GTK+ 3 user interfaces.
  • -I GTK-LIBRARY, --gtk-library=GTK-LIBRARY — specify the graphical user interface library to use if a nvidia-settings user interface is required. This value may be the exact location of the library or it may be the directory containing the appropriately named library. If this is the exact location, the 'use-gtk2' option is ignored.

🌸 USER GUIDE 🌸

📚 Contents

  1. Layout of the nvidia-settings GUI
  2. How OpenGL Interacts with nvidia-settings
  3. Loading Settings Automatically
  4. Command Line Interface
  5. X Display Names in the Config File
  6. Connecting to Remote X Servers
  7. Licensing
  8. TODO

🖥️ 1. Layout of the nvidia-settings GUI

The nvidia-settings GUI is organized with a list of different categories on the left side. Only one entry in the list can be selected at once, and the selected category controls which "page" is displayed on the right side of the nvidia-settings GUI. It's giving very much "choose your own adventure" energy. 💖

The category list is organized in a tree: each X screen contains the relevant subcategories beneath it. Similarly, the Display Devices category for a screen contains all the enabled display devices beneath it. Besides each X screen, the other top level category is "nvidia-settings Configuration", which configures behavior of the nvidia-settings application itself.

Along the bottom of the nvidia-settings GUI, from left to right, is:

  1. a status bar which indicates the most recently altered option;
  2. a Help button that toggles the display of a help window which provides a detailed explanation of the available options in the current page; and
  3. a Quit button to exit nvidia-settings.

Most options throughout nvidia-settings are applied immediately. Notable exceptions are OpenGL options which are only read by OpenGL when an OpenGL application starts.

Details about the options on each page of nvidia-settings are available in the help window.

🌈 2. How OpenGL Interacts with nvidia-settings 🌈

Okay bestie, so here's the tea on OpenGL ☕ — when an OpenGL application starts up, it downloads the current values from the X driver, and then it reads the environment (peep APPENDIX E: OPENGL ENVIRONMENT VARIABLE SETTINGS in the README if you wanna go deeper 💖).

The hierarchy is giving very much main-character energy: settings from the X server override OpenGL's default values, and settings from the environment override values from the X server. Slay, the environment always wins 😌

Example time, because iykyk ✨ — by default OpenGL uses the FSAA setting requested by the application (and normally, applications do not request any FSAA, bless them). An FSAA setting specified in nvidia-settings would override the OpenGL application's request. Similarly, the __GL_FSAA_MODE environment variable will override the application's FSAA setting, as well as any FSAA setting specified in nvidia-settings. Layers on layers, fr fr 🧅

💀 Heads up babes: an OpenGL application only retrieves settings from the X server when it starts, so if you make a change to an OpenGL value in nvidia-settings, it will only apply to OpenGL applications which are started after that point in time. No time travel, sorry 😭

🎀 3. Loading Settings Automatically 🎀

Bad news first: the NVIDIA X driver does not preserve values set with nvidia-settings between runs of the X server (or even between logging in and logging out of X, with xdm(1), gdm, or kdm). And before you come for it — this is intentional 💅 because different users may have different preferences, so these settings are stored on a per-user basis in a configuration file stored in the user's home directory.

The configuration file is named ~/.nvidia-settings-rc. You can specify a different configuration file name with the --config command line option. Your file, your rules 🫶

So after you've run nvidia-settings once and have generated a configuration file, you can then run:

nvidia-settings --load-config-only

at any time in the future to upload these settings to the X server again. Iconic behaviour, honestly 🌟 For example, you might place the above command in your ~/.xinitrc file so that your settings are applied automatically when you log in to X.

Your .xinitrc file, which controls what X applications should be started when you log into X (or startx), might look something like this:

nvidia-settings --load-config-only &
xterm &
evilwm

or:

nvidia-settings --load-config-only &
gnome-session

If you do not already have an ~/.xinitrc file, then chances are that xinit(1) is using a system-wide xinitrc file. That system wide file is typically here:

/etc/X11/xinit/xinitrc

To use it, but also have nvidia-settings upload your settings, you could create an ~/.xinitrc with the contents:

nvidia-settings --load-config-only &
. /etc/X11/xinit/xinitrc

System administrators may choose to place the nvidia-settings load command directly in the system xinitrc script. Admins doing admin things, we love to see it 👑

Please see the xinit(1) man page for further details of configuring your ~/.xinitrc file 💜

💅 4. Command Line Interface 💅

nvidia-settings has a rich command line interface — literally all attributes that can be manipulated with the GUI can also be queried and set from the command line 🌈 The command line syntax for querying and assigning attributes matches that of the .nvidia-settings-rc configuration file. Same energy, different font 💖

🔍 Querying stuff

The --query option can be used to query the current value of attributes. This will also report the valid values for the attribute. You can run nvidia-settings --query all for a complete list of available attributes, what the current value is, what values are valid for the attribute, and through which target types (e.g., X screens, GPUs) the attributes can be addressed — a whole vibe check on your entire setup, no cap. Additionally, individual attributes may be specified like this:

nvidia-settings --query Overlay

An attribute name may be prepended with an X Display name and a forward slash to indicate a different X Display; e.g.:

nvidia-settings --query localhost:0.0/Overlay

An attribute name may also just be prepended with the screen number and a forward slash:

nvidia-settings --query 0/Overlay

in which case the default X Display will be used, but you can indicate to which X screen to direct the query (if your X server has multiple X screens — fancy 🌸). If no X screen is specified, then the attribute value will be queried for all valid targets of the attribute (eg GPUs, Displays X screens, etc).

🎯 Target types (the real MVPs)

Attributes can be addressed through "target types". A target type indicates the object that is queried when you query an attribute. The default target type is an X screen, but other possible target types are GPUs, Frame Lock devices, Visual Computing Systems, fans, thermal sensors, 3D Vision Pro Transceivers and display devices. So many little guys to talk to 😭🫶

Target types give you different granularities with which to perform queries and assignments. Since X screens can span multiple GPUs (in the case of Xinerama, or SLI), and multiple X screens can exist on the same GPU, it is sometimes useful to address attributes by GPU rather than X screen. Slay, precision ✨

A target specification is contained within brackets and may consist of a target type name, a colon, and the target id. The target type name can be one of screen, gpu, framelock, fan, thermalsensor, svp, or dpy; the target id is the index into the list of targets (for that target type). Target specifications can be used wherever an X screen is used in query and assignment commands; the target specification can be used either by itself on the left side of the forward slash, or as part of an X Display name.

For example, the following queries address X screen 0 on the localhost:

nvidia-settings --query 0/VideoRam
nvidia-settings --query localhost:0.0/VideoRam
nvidia-settings --query [screen:0]/VideoRam
nvidia-settings --query localhost:0[screen:0]/VideoRam

To address GPU 0 instead, you can use either of:

nvidia-settings --query [gpu:0]/VideoRam
nvidia-settings --query localhost:0[gpu:0]/VideoRam
🚨 Note that if a target specification is present, it will override any X screen specified in the display name as the target to process. For example, the following query would address GPU 0, and not X screen 1:
nvidia-settings --query localhost:0.1[gpu:0]/VideoRam

A target name may be used instead of a target id, in which case all targets with matching names are processed. Very "if it matches, it matches" of it 💅

For example, querying the DigitalVibrance of display device DVI-I-1 may be done like so:

nvidia-settings --query [dpy:DVI-I-1]/DigitalVibrance

When a target name is specified, the target type name may be omitted, though this should be used with caution since the name will be matched across all target types. The above example could be written as:

nvidia-settings --query [DVI-I-1]/DigitalVibrance

The target name may also simply be a target type name, in which case all targets of that type will be queried. Give me everything in that category, periodt 💯

For example, querying the BusRate of all GPUs may be done like so:

nvidia-settings --query [gpu]/BusRate

The target specification may also include a target qualifier. This is useful to limit processing to a subset of targets, based on an existing relationship(s) to other targets. The target qualifier is specified by prepending a target type name, a colon, the target id, and a period to the existing specification. Only one qualifier may be specified.

For example, querying the RefreshRate of all DFP devices on GPU 1 may be done like so:

nvidia-settings --query [GPU:1.DPY:DFP]/RefreshRate

Likewise, a simple target name (or target type name) may be used as the qualifier. For example, to query the BusType of all GPUs that have DFPs can be done like so:

nvidia-settings --query [DFP.GPU]/BusType

See the output of

nvidia-settings --query all

for what targets types can be used with each attribute. See the output of

nvidia-settings --query screens --query gpus --query framelocks --query fans --query thermalsensors --query svps --query dpys

for lists of targets for each target type. It's giving inventory management and honestly we love a full roster 📋✨

🔥 Clock offsets & performance modes

To enable support for the "GPUGraphicsClockOffset" and "GPUMemoryTransferRateOffset" attributes, ensure that the "Coolbits" X configuration option includes the value "8" in the bitmask. For more details, refer to the documentation of the "Coolbits" option in the NVIDIA driver README. Query the "GPUPerfModes" string attribute to see a list of the available performance modes:

nvidia-settings --query GPUPerfModes

Each performance mode is presented as a comma-separated list of "token=value" pairs. Each set of performance mode tokens is separated by a ";". The "perf" token indicates the performance level. The "*editable" tokens indicate which domains within the performance level can have an offset applied. The "GPUGraphicsClockOffset" and "GPUMemoryTransferRateOffset" attributes map respectively to the "nvclock" and "memtransferrate" tokens of performance levels in the "GPUPerfModes" string. Token lore, honestly 🧚

🍓 Note that the clock manipulation attributes "GPUGraphicsClockOffset" and "GPUMemoryTransferRateOffset" apply to the offsets of specific performance levels. The performance level is specified in square brackets after the attribute name. For example, to query the "GPUGraphicsClockOffset" for performance level 2:
nvidia-settings --query GPUGraphicsClockOffset[2]

✍️ Assigning stuff

The --assign option can be used to assign a new value to an attribute. The valid values for an attribute are reported when the attribute is queried. The syntax for --assign is the same as --query, with the additional requirement that assignments also have an equal sign and the new value. For example:

nvidia-settings --assign FSAA=2
nvidia-settings --assign [CRT-1]/DigitalVibrance=9
nvidia-settings --assign [gpu:0]/DigitalVibrance=0
nvidia-settings --assign [gpu:0]/GPUGraphicsClockOffset[2]=10

Multiple queries and assignments may be specified on the command line for a single invocation of nvidia-settings. Assignments are processed in the order they are entered on the command line. If multiple assignments are made to the same attribute or to multiple attributes with dependencies, then the later assignments will have priority. Last one wins, that's the rule 😌

⭐ Big one, bestie: if either the --query or --assign options are passed to nvidia-settings, the GUI will not be presented, and nvidia-settings will exit after processing the assignments and/or queries. In this case, settings contained within the ~/.nvidia-settings-rc configuration file will not be automatically uploaded to the X server, nor will the ~/.nvidia-settings-rc configuration file be automatically updated to reflect attribute assignments made via the --assign option. Heads up so you're not confused later 💀

🦋 5. X Display Names in the Config File 🦋

In the Command Line Interface section above, it was noted that you can specify an attribute without any X Display qualifiers, with only an X screen qualifier, or with a full X Display name. For example:

nvidia-settings --query FSAA
nvidia-settings --query 0/FSAA
nvidia-settings --query alpha.example.org:0/FSAA

so like, quick vibe check on those three 🫶 — in the first two cases, the default X Display is what gets used. In the second case, you can override the screen from the default X Display. And in the third case, you're overriding the entire default X Display. literally the whole thing.

The same possibilities are available in the ~/.nvidia-settings-rc configuration file. ✨

Say you're in a computer lab kind of sitch 💻 — you log into any of multiple workstations, and your home directory is NFS mounted to each workstation. In that situation you'd lowkey want your ~/.nvidia-settings-rc file to be applicable to all the workstations. So you would not want your config file to qualify each attribute with an X Display Name. Leave the "Include X Display Names in the Config File" option unchecked on the nvidia-settings Configuration page (that's the default, bestie 💅).

But there may be cases when you do want attributes in the config file to be qualified with the X Display name. If you know what you are doing and want that, check the "Include X Display Names in the Config File" option on the nvidia-settings Configuration page. 👑

In the typical home user environment where your home directory is local to one computer and you're only configuring one X Display, then honestly it does not matter whether each attribute setting is qualified with an X Display Name. either way, we slay 🌸

6. Connecting to Remote X Servers 🌐✨

Okay so this is the part that's giving main character energy. nvidia-settings is an X client, but it uses two separate X connections: one to display the GUI, and another to communicate the NV-CONTROL requests. And no cap — these two X connections do not need to be to the same X server. 😭 iconic.

So for example, you might run nvidia-settings on the computer alpha.example.org, export the display to the computer beta.example.org, but be configuring the X server on the computer gamma.example.org:

nvidia-settings --display=beta.example.org:0 \
    --ctrl-display=gamma.example.org:0

If --ctrl-display is not specified, then the X Display to control is what --display indicates. If --display is also not specified, then the $DISPLAY environment variable is used. 🎀

Note, however, that you will need to have X permissions configured such that you can establish an X connection from the computer on which you are running nvidia-settings (alpha.example.org) to the computer where you are displaying the GUI (beta.example.org) and the computer whose X Display you are configuring (gamma.example.org). 🙈

The simplest, most common, and least secure mechanism to do this is to use xhost to allow access from the computer on which you are running nvidia-settings. 💀

(issued from beta.example.org)
xhost +alpha.example.org

(issued from gamma.example.org)
xhost +alpha.example.org

This will allow all X clients run on alpha.example.org to connect and display on beta.example.org's X server and configure gamma.example.org's X server. (yes, all of them. hence the "least secure" thing. be normal about it 💅)

Please see the xauth(1) and xhost(1) man pages, or refer to your system documentation on remote X applications and security. You might also Google for terms such as "remote X security" or "remote X Windows", and see documents such as the Remote X Apps mini-HOWTO:

⟨http://www.tldp.org/HOWTO/Remote-X-Apps.html⟩

Please also note that the remote X server to be controlled must be using the NVIDIA X driver. ⭐

7. Licensing 📜🦋

The source code to nvidia-settings is released as GPL. The most recent official version of the source code is available here:

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

Note that nvidia-settings is simply an NV-CONTROL client. It uses the NV-CONTROL X extension to communicate with the NVIDIA X server to query current settings and make changes to settings. 🧚

You can make additions directly to nvidia-settings, or write your own NV-CONTROL client, using nvidia-settings as an example. honestly? very "be the change you want to see" of them 💖

Documentation on the NV-CONTROL extension and additional sample clients are available in the nvidia-settings source tarball. Patches can be submitted to linux-bugs@nvidia.com. 📬

8. TODO 💀📝

There are many things still to be added to nvidia-settings, some of which include:

  • different toolkits? The GUI for nvidia-settings is cleanly abstracted from the back-end of nvidia-settings that parses the configuration file and command line, communicates with the X server, etc. If someone were so inclined, a different front-end GUI could be implemented. 👀
  • write a design document explaining how nvidia-settings is designed; presumably this would make it easier for people to become familiar with the code base.

If there are other things you would like to see added (or better yet, would like to add yourself), please contact linux-bugs@nvidia.com. 🫶

📁 FILES 📁

  • ~/.nvidia-settings-rc

🌈 EXAMPLES 🌈

  • nvidia-settings — Starts the nvidia-settings graphical interface. the classic. the og. 🎀
  • nvidia-settings --load-config-only — Loads the settings stored in ~/.nvidia-settings-rc and exits.
  • nvidia-settings --rewrite-config-file — Writes the current X server configuration to ~/.nvidia-settings-rc file and exits.
  • nvidia-settings --query FSAA — Query the value of the full-screen antialiasing setting.
  • nvidia-settings --assign RedGamma=2.0 --assign BlueGamma=2.0 --assign GreenGamma=2.0 — Set the gamma of the screen to 2.0. (three whole assigns, one very colourful screen ✨)

👑 AUTHOR 👑

Aaron Plattner NVIDIA Corporation

🔗 SEE ALSO 🔗

Copyright © 2010 NVIDIA Corporation.

okay bestie that's the whole page, you made it to the end 🥳💖 this was written by the fine folks over at NVIDIA — nvidia-settings version 615.78.08, dated 2018-03-20, and yes she's still iconic. go forth and configure your X server, slay, periodt. 💅✨🎀

📦 where this page comes from