Inspect and Safely Change Desktop Settings with gsettings

Digging through a GUI settings panel for one obscure toggle wastes ten minutes you don't have, and gsettings gets you there from the terminal instead. You will finish with a repeatable way to discover a GSettings key, inspect its current value and valid range, make a reversible change, and watch for updates. The examples use gsettings 2.86.4 from Ubuntu package libglib2.0-bin 2.80.0-6ubuntu3.9.

Allow about fifteen minutes. You need a graphical desktop session or another session with a D-Bus session bus, plus an ordinary shell. Most commands are read-only and do not need sudo. The setting change itself is user-scoped, not a system administration task, and asking for elevated privileges will usually make the session mismatch worse.

1. Confirm the session and command

Start by checking the installed command. This is an ordinary read-only check:

$ command -v gsettings
/usr/bin/gsettings
$ gsettings --version
2.86.4

gsettings needs a D-Bus session bus when it writes to the dconf database. A command run from a text-only root shell, a scheduled job, or a different login session may therefore fail even though the same command works in your desktop terminal.

2. Find a schema and its keys

A schema groups related settings. List installed non-relocatable schemas, then list the keys in one schema:

$ gsettings list-schemas | head
org.gnome.desktop.a11y
org.gnome.desktop.a11y.applications
org.gnome.desktop.a11y.interface
org.gnome.desktop.a11y.keyboard
org.gnome.desktop.a11y.magnifier
$ gsettings list-keys org.gnome.desktop.interface | head
avatar-directories
can-change-accels
clock-format
clock-show-date
clock-show-seconds

The list depends on the installed desktop software, so do not copy a schema from another machine without checking it exists here. If a schema is relocatable, it needs a path as well as its ID: gsettings list-relocatable-schemas shows those schema IDs, and gsettings list-schemas --print-paths shows paths for fixed schemas.

For a larger discovery pass, gsettings list-recursively org.gnome.desktop.interface prints keys and values below the schema. Without a schema, list-recursively walks all schemas, which can produce a distracting amount of output. Add a schema first when you know the area you are investigating.

3. Inspect one key before changing it

Use the interface schema's colour-scheme key as a harmless inspection example:

$ gsettings get org.gnome.desktop.interface color-scheme
'default'
$ gsettings range org.gnome.desktop.interface color-scheme
enum
'default'
'prefer-dark'
'prefer-light'
$ gsettings writable org.gnome.desktop.interface color-scheme
true
$ gsettings describe org.gnome.desktop.interface color-scheme
The preferred color scheme for the user interface. Valid values are "default", "prefer-dark", "prefer-light".

The value printed by get is a serialised GVariant, not shell syntax, so a string comes back with its quotes intact. Boolean values print as true or false; lists and other types have their own GVariant notation. Read the range and description before constructing a value, rather than guessing from a key name.

4. Make one reversible user-level change

For a temporary dark theme preference, use a quoted GVariant string:

$ gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark'
$ gsettings get org.gnome.desktop.interface color-scheme
'prefer-dark'

The quotes around prefer-dark are part of the GVariant value; the outer shell quotes keep the value as one argument. Do not use an unquoted word for a string setting and do not add JSON syntax.

Undo this particular example by resetting the key to its schema default:

$ gsettings reset org.gnome.desktop.interface color-scheme
$ gsettings get org.gnome.desktop.interface color-scheme
'default'

Reset is not a general backup mechanism. If the original value was a deliberate non-default, use gsettings set with the exact value you recorded instead. If the setting belongs to a relocatable schema, include its path in the schema argument, for example org.example.Schema:/some/path, after confirming that path is valid.

5. Check writeability and errors in scripts

A key can exist but be locked by policy or otherwise unwritable. Test it before a script attempts a change:

schema='org.gnome.desktop.interface'
key='color-scheme'
if [ "$(gsettings writable "$schema" "$key")" != true ]; then
    printf 'Not writable: %s %s
' "$schema" "$key" >&2
    exit 1
fi
gsettings set "$schema" "$key" "'prefer-dark'"
gsettings get "$schema" "$key"

Keep the schema and key as separate shell arguments. Quote values twice where needed: the shell must pass one argument, while the argument itself must contain the GVariant quotes required for a string. For production scripts, validate the exact value with range first and check the command's exit status: a non-zero result is a failure, not a signal to retry indefinitely.

No sudo belongs in this user-setting example. If a write fails because there is no session bus, repair the session context or run the command from the correct desktop login. Running it as root would target a different user's settings and may still have no usable session bus.

6. Watch a key while troubleshooting

Use monitor when another application may be changing the setting:

$ gsettings monitor org.gnome.desktop.interface color-scheme
'prefer-dark'

The process stays attached and prints changed values until you stop it with Ctrl-C. Omit the key to monitor every key in the schema. Start the monitor before reproducing the problem, then make one change at a time so the output has a clear cause. Monitoring does not modify the setting.

If the value keeps changing, check for a desktop extension, synchronisation tool, login script, or second settings application. The monitor tells you that a change happened; it does not identify the process that made it.

Common traps

• Unknown schema or key. Usually a spelling error or a package that is not installed. Re-run list-schemas and list-keys on the same machine.
• Invalid value rejected. Usually fixed by reading range; do not force a value outside the listed type or enum.
• Desktop looks wrong after a change. Restore the recorded value with set, or use reset only when the schema default is the intended state.
• Application still shows the old behaviour. Restart that application after confirming get reports the desired value.
• Editing dconf directly. Avoid deleting dconf databases or editing their files directly: those actions are broader, harder to recover, and bypass the schema's type checks.