Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, February 9, 2022

nvidia-settings (1)


nvidia-settings - configure the NVIDIA graphics driver


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:


nvidia-settings(1)          General Commands Manual         nvidia-settings(1)

       nvidia-settings - configure the NVIDIA graphics driver

       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:

       The nvidia-settings utility is a tool for configuring the NVIDIA graph-
       ics driver.  It operates by communicating with  the  NVIDIA  X  driver,
       querying and updating state as appropriate.  This communication is done
       via the NV-CONTROL, GLX, XVideo, and RandR X extensions.

       Values such as brightness and gamma,  XVideo  attributes,  temperature,
       and OpenGL settings can 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.

       -v, --version
              Print the nvidia-settings version and exit.

       -h, --help
              Print usage information and exit.

              Use  the  configuration  file  CONFIG  rather  than  the default

       -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  environ-
              ment 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 prob-
              lems 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  EXAM-
              PLES 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 mes-
              sages), 'warnings' (print error, deprecation, and  warning  mes-
              sages),  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 {DIS-
              PLAY} 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 , vcs ,  gvi  ,
              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}[{tar-
              get_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  vcs  -q
              gvis -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

              Some examples:

                -a FSAA=5
                -a localhost:0.0/DigitalVibrance[CRT-0]=0
                -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 vcs', '-q gvis', '-q
              fans' , '-q thermalsensors', '-q svps', or '-q dpys' to query  a
              list  of  X  screens, GPUs, Frame Lock devices, Visual Computing
              Systems, SDI Input 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

       -t, --terse
              When  querying  attribute values with the '--query' command line
              option, only print the current value, rather than the more  ver-
              bose  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 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 a 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, fol-
              lowed 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 "X Server 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  graphi-
              cal  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.

       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 cate-
       gories 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.

       The category list is organized in a tree: each X  screen  contains  the
       relevant subcategories beneath it.  Similarly, the Display Devices cat-
       egory 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 appli-
       cation 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
       When an OpenGL application starts, it downloads the current values from
       the  X  driver,  and then reads the environment (see APPENDIX E: OPENGL
       ENVIRONMENT VARIABLE SETTINGS in the  README).   Settings  from  the  X
       server override OpenGL's default values, and settings from the environ-
       ment override values from the X server.

       For example, by default OpenGL uses the FSAA setting requested  by  the
       application  (normally, applications do not request any FSAA).  An FSAA
       setting specified in nvidia-settings would override the OpenGL applica-
       tion's  request.   Similarly,  the  __GL_FSAA_MODE environment variable
       will override the application's FSAA setting, as well as any FSAA  set-
       ting specified in nvidia-settings.

       Note  that  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.

   3. Loading Settings Automatically
       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 ).   This  is  intentional,  because
       different users may have different preferences, thus 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

       After you have run nvidia-settings once and have generated a configura-
       tion 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.  For example, you might place the above command in your ~/.xini-
       trc 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

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


            nvidia-settings --load-config-only &

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


       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 com-
       mand directly in the system xinitrc script.

       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: 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.

       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 avail-
       able 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.  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).   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).

       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, SDI Input  Devices,
       fans, thermal sensors, 3D Vision Pro Transceivers and display devices.

       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.

       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, vcs, gvi, 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  specifica-
       tion  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.

       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.

       For exmple, 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 qualitfer 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

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

       for lists of targets for each target type.

       To enable support for the "GPUGraphicsClockOffset" and "GPUMemoryTrans-
       ferRateOffset" 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 "GPUMemo-
       ryTransferRateOffset"  attributes map respectively to the "nvclock" and
       "memtransferrate" tokens of performance levels  in  the  "GPUPerfModes"

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

            nvidia-settings --query GPUGraphicsClockOffset[2]

       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 assign-
       ments are made to the same attribute or  to  multiple  attributes  with
       dependencies, then the later assignments will have priority.

       If  either  the  --query  or --assign options are passed to nvidia-set-
       tings, the GUI will not be presented,  and  nvidia-settings  will  exit
       after  processing  the  assignments and/or queries.  In this case, set-
       tings 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.

   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 stravinsky.nvidia.com:0/FSAA

       In the first two cases, the default X Display will be used, in the sec-
       ond case, the screen from the default X Display can be overridden,  and
       in the third case, the entire default X Display can be overridden.

       The  same possibilities are available in the ~/.nvidia-settings-rc con-
       figuration file.

       For example, in a computer lab environment, you might log into  any  of
       multiple  workstations,  and your home directory is NFS mounted to each
       workstation.  In such a situation, you might want  your  ~/.nvidia-set-
       tings-rc file to be applicable to all the workstations.  Therefore, 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 (this is the

       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  config  file  attributes to be qualified with an X Display, 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 are only configuring one  X  Display,  then  it
       does  not  matter whether each attribute setting is qualified with an X
       Display Name.

   6. Connecting to Remote X Servers
       nvidia-settings is an X client, but uses two  separate  X  connections:
       one  to  display  the  GUI,  and  another to communicate the NV-CONTROL
       requests.  These two X connections do not need to  be  to  the  same  X
       server.   For  example,  you  might run nvidia-settings on the computer
       stravinsky.nvidia.com,  export  the  display  to  the   computer   bar-
       tok.nvidia.com, but be configuring the X server on the computer schoen-

               nvidia-settings --display=bartok.nvidia.com: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  (stravinsky.nvidia.com)  to  the  computer
       where  you  are displaying the GUI (bartok.nvidia.com) and the computer
       whose X Display you are configuring (schoenberg.nvidia.com).

       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

               (issued from bartok.nvidia.com)
               xhost +stravinsky.nvidia.com

               (issued from schoenberg.nvidia.com)
               xhost +stravinsky.nvidia.com

       This will allow all X clients run on stravinsky.nvidia.com  to  connect
       and  display  on  bartok.nvidia.com's  X  server  and configure schoen-
       berg.nvidia.com's X server.

       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:

            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:

            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.

       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.


              Starts the nvidia-settings graphical interface.

       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
              Set the gamma of the screen to 2.0.

       Aaron Plattner
       NVIDIA Corporation


       Copyright (C) 2010 NVIDIA Corporation.

nvidia-settings 390.116           2019-01-27                nvidia-settings(1)