Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
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 di-
	      rect  an assignment to something other than an X screen.	A tar-
	      get 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 specifi-
	      cation  can  be  used  in	 {DISPLAY} wherever an X screen	can be
	      used, following the syntax  {host}:{display}[{target_type}:{tar-
	      get_id}].	 See the output	of

		nvidia-settings	-q all

	      for information on which target types can	be used	with which at-
	      tributes.	 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  de-

	      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  at-

       -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'  op-
	      tion, 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.

       -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.  No-
       table 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  op-

       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  at-
       tributes	matches	that of	the .nvidia-settings-rc	configuration file.

       The  --query  option  can  be  used  to	query the current value	of at-
       tributes.  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 in-
       dicates 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 ex-
       ample, 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  "to-
       ken=value"  pairs.  Each	set of performance mode	tokens is separated by
       a ";".  The "perf" token	indicates the performance  level.   The	 "*ed-
       itable"	tokens indicate	which domains within the performance level can
       have an offset applied.	The "GPUGraphicsClockOffset"  and  "GPUMemory-
       TransferRateOffset"  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 ad-
       ditional	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 de-
       pendencies, 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 af-
       ter  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-set-
       tings-rc	configuration file be automatically updated to reflect	attri-
       bute 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

       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 re-
       quests.	These two X connections	do not	need  to  be  to  the  same  X
       server.	 For  example,	you  might run nvidia-settings on the computer,  export  the  display  to	 the   computer	  bar-, but be configuring the X	server on the computer schoen-

	       nvidia-settings \

       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  (  to	 the  computer
       where  you  are displaying the GUI ( and the computer
       whose X Display you are configuring (

       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

	       (issued from

       This will allow all X clients run on  to  connect
       and  display  on's  X	 server	 and configure schoen-'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 us-
       ing 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

   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 ab-
	      stracted 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 de-
	      signed; presumably this would make it easier for people  to  be-
	      come 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


	      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-set-
	      tings-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	440.100		  2018-03-20		    nvidia-settings(1)


Want to link to this manual page? Use this URL:

home | help