How to automatically set a matching display refresh rate on Gnome (Linux, Wayland)?

[user-1-2-3-4-5]

The display refresh rate can be changed from the command-line at least with the gnome-monitor-config program (deprecated, see the upstream gdctl (GNOME Display Control):

After inspecting your current configuration, the major Gnome display settings can be changed with a command:

gnome-monitor-config set --logical-monitor --primary --monitor=HDMI-1 --scale=2 --mode=3840x2160@23.976 # Disables the monitor altogether to avoid issues with video playback (such as windows launching to a wrong screen), switches to the TV.

To return to the computer display:

gnome-monitor-config set --logical-monitor --primary --monitor=DP-1 --scale=1

---

How can the process be efficiently automated?

Currently I set the display refresh rate manually — mostly by viewing the video information in mpv, then running an appropriate command and resuming playback:

       gnome-monitor-config set --logical-monitor --primary --monitor=HDMI-1 --scale=2 --mode=3840x2160@23.976
       gnome-monitor-config set --logical-monitor --primary --monitor=HDMI-1 --scale=2 --mode=3840x2160@24.000
       gnome-monitor-config set --logical-monitor --primary --monitor=HDMI-1 --scale=2 --mode=3840x2160@25.000
       gnome-monitor-config set --logical-monitor --primary --monitor=HDMI-1 --scale=2 --mode=3840x2160@29.970
       gnome-monitor-config set --logical-monitor --primary --monitor=HDMI-1 --scale=2 --mode=3840x2160@30.000
       gnome-monitor-config set --logical-monitor --primary --monitor=HDMI-1 --scale=2 --mode=3840x2160@59.940
       gnome-monitor-config set --logical-monitor --primary --monitor=HDMI-1 --scale=2 --mode=3840x2160@60.000

note: Above all, running your display at the analogous refresh rate (i.e. 23.976 Hz for 24p content) is optimal, isn't it?

EDIT 11/2026: updated the question, gnome-monitor-config is no longer relevant to users on a more recent Gnome desktop release

[user-1-2-3-4-5]

Gnome 50 sees further refined VRR support — there may not be a need for any script provided you have a compatible display.

Improved Variable Refresh Rate (VRR) and Fractional Scaling Support: VRR and fractional scaling have both been improved for GNOME 50, with bug fixes, stability, and user experience improvements. Some distributions enabled these features in previous releases, so many users will have used them already. However, for other distros, these features are now enabled by default in GNOME 50.

see: https://mpv.io/manual/stable/#video-output-drivers-drm-vrr-enabled

[Valenerus]

Yup exatly, X11 worked, this isnt for wayland

[guidocella]

Oh sorry. Then it's a just matter of checking how to change refresh rate programmatically on your compositor and adapting that script. In wlroots compositors you just use wlr-randr.

[Dudemanguy]

Gnome has its own tool for setting monitor modes gnome-monitor-config. The difference with wayland is that different compositors will have different cli programs for this purpose.

[user-1-2-3-4-5]

Note that the (third-party) gnome-monitor-config has been deprecated since the Gnome 47 release).

[user-1-2-3-4-5]

@Valenerus Sorry for the inconsiderate VRR suggestion and prematurely closing this discussion. See my answer for the full script (I'm sharing the code in its own reply to avoid confusion).

preface

I "created" a script some months ago, using AI-assisted coding. The script was generated using the paid assistant.kagi.com service (I can't recall the AI model used) and I haven't evaluated the code any further than glancing through and determining that the LUA script doesn't call any external domains and appears to be only using the mpv built-in functions, outside of the Gnome's gdctl of course.

I wanted to thoroughly test first in my personal media playback use, which I've more or less achieved by now — I've only discovered that the frame rate can't be determined for some of my WMV files, and the functionality could be automated much further. To avoid overhead, the script only runs when launching a video file, but the r key has been mapped for manual execution manually when needed.

Requires Gnome 47 or above (the script has only been tested on Fedora Workstation (44), mpv from the official Fedora repository). Presumably can't work with the Flatpak build of mpv. I don't have any LUA experience and thus haven't considered creating a standalone repo (please do so if you're able to audit the code and develop further.

Note that you have to edit the configuration to match your personal setup (run $ gdctl show), lines 4-16 in the script.

I now informally publish the script under the permissive MIT license (save e.g. as ~/.config/mpv/scripts/gdctl-refresh.lua )

[user-1-2-3-4-5]

local mp = require 'mp'
local options = require 'mp.options'

local supported_rates = {
    120.000, 119.944, 119.880, 100.000, 89.984,
    60.000, 59.981, 59.968, 59.940, 50.000,
    30.000, 29.970, 25.000, 24.000, 23.976
}

local opts = {
    monitor = "HDMI-1",
    resolution = "3840x2160",
    gdctl = "gdctl",
    default_rate = "60.000",
    hotkey = "r",
}
options.read_options(opts, "gdctl_refresh")

local last_rate = nil

local function video_enabled()
    local vid = mp.get_property_native("vid")
    local video = mp.get_property_native("video")

    -- --vid=no / --video=no disable video; treat "no", false, nil, or -1 as disabled
    if vid == "no" or vid == false or vid == nil or vid == -1 then
        return false
    end
    if video == "no" or video == false then
        return false
    end

    return true
end

local function closest_rate(fps)
    if not fps or fps <= 0 then return nil end
    local best = supported_rates[1]
    local best_diff = math.abs(fps - best)
    for _, rate in ipairs(supported_rates) do
        local diff = math.abs(fps - rate)
        if diff < best_diff then
            best_diff = diff
            best = rate
        end
    end
    return best
end

local function run_gdctl(args)
    local res = mp.command_native({
        name = "subprocess",
        args = args,
        capture_stdout = "yes",
        capture_stderr = "yes",
    })
    if not res or res.error or res.status ~= 0 then
        local err = res and (res.stderr or res.error) or "unknown error"
        mp.msg.error("gdctl failed: " .. tostring(err))
        return nil
    end
    return res.stdout or ""
end

local function is_monitor_active()
    local output = run_gdctl({opts.gdctl, "show"})
    if not output then return false end

    -- Match only within the Logical monitors section
    local logical = output:match("Logical monitors:.*")
    if not logical then return false end

    return logical:find(opts.monitor, 1, true) ~= nil
end

local function set_refresh_rate(rate, force)
    if not rate then return end
    if not force and rate == last_rate then return end
    last_rate = rate

    local mode = string.format("%s@%.3f", opts.resolution, rate)
    local args = {
        opts.gdctl, "set",
        "--logical-monitor",
        "--primary",
        "--monitor", opts.monitor,
        "--mode", mode,
    }

    mp.osd_message(string.format("Switching display to %.3f Hz", rate), 3)

    local output = run_gdctl(args)
    if not output then
        mp.osd_message("gdctl set failed", 5)
    end
end

local function apply_rate(force)
    if not video_enabled() then
        mp.msg.info("Video disabled; skipping refresh rate adjustment")
        return
    end

    local fps = mp.get_property_native("container-fps")
    local rate = closest_rate(fps)
    if not rate then
        mp.osd_message("Could not determine video FPS", 3)
        return
    end

    if is_monitor_active() then
        set_refresh_rate(rate, force)
    else
        mp.osd_message(string.format("%s is not active; skipping refresh switch", opts.monitor), 3)
    end
end

mp.observe_property("container-fps", "number", function(_, fps)
    if not video_enabled() then return end

    local rate = closest_rate(fps)
    if rate and is_monitor_active() then
        set_refresh_rate(rate, false)
    end
end)

mp.add_key_binding(opts.hotkey, "adjust-refresh", function() apply_rate(true) end)

mp.register_event("shutdown", function()
    if not video_enabled() then return end

    if opts.default_rate and opts.default_rate ~= "" then
        if is_monitor_active() then
            last_rate = nil
            set_refresh_rate(tonumber(opts.default_rate), true)
        end
    end
end)