Home

Adding and setting a custom resolution using xrandr

This guide details how to add and set a new custom screen resolution with xrandr. The inspiration for this post was the fact that this is a recurring question on help forums and have written this explanation up as comments multiple times, but have also gotten this question from multiple coworkers as they were setting up VMs for frontend testing.

The problem

When wanting to go full screen in a VM, you might want to set such a resolution that isn’t one of the already available options. E.g. 1920x1080 is often not available by default on a freshly installed debian in a VM. I will be using this scenario going forth.

Sidenote about wayland and Gnome

If you have installed debian with default settings, you probably have gnome + wayland installed. In this case, a switch to X11 is needed because there is no simple way to add a custom resolution with Gnome and Wayland at the time of writing this guide.

To make the switch to X11, in /etc/gdm3/daemon.conf uncomment the following line:

#WaylandEnable=false

Once that’s done, reboot and you should be on X11.

Finding and testing the right settings

To begin, we need to identify the primary connected monitor, by executing:

xrandr --listmonitors

Look for the entry with the * symbol. This is the monitor/display we want to apply new settings to. In my case, this is Virtual1.

Next we want to get the modeline string for the resolution we desire by executing:

gtf 1920 1080 60

It’s beyond the scope of this tutorial to explain in detail about gtf, but the gist of it is that the string it produces is something that can be added into the xorg.conf file, as well as compatible for use with the xrandr command. So the output of the above command should give you some result like:

Modeline "1920x1080_60.00" 172.80 1920 2040 2248 2576 1080 1081 1084 1118 -HSync +Vsync

If gtf doesn’t work for you, you may try the cvt command instead, with the same inputs. These two programs are both used to generate modelines, in rare cases, one might work better than the other.

Copy out this string with the exception of the word Modeline. We will use xrandr to get the system to recognize these display parameters.

So now execute:

xrandr --newmode "1920x1080_60.00"  172.80  1920 2040 2248 2576  1080 1081 1084 1118  -HSync +Vsync

The part enclosed in the double quotes is just the alias/name of the display setting, so you can call it anything you want, but it’s wise to keep it something understandable.

Now we can apply this mode to our display. In my case xrandr --listmonitors returned Virtual1 as my primary connected monitor. (If you have are not in a VM, it might be something like VGA1 or HDMI-0)

Do so by executing (keep in mind to change Virtual1 to what makes sense in your situation):

xrandr --addmode Virtual1 "1920x1080_60.00"

Now at this point, 1920x1080 should be a valid display resolution, so let’s apply it by executing:

xrandr -s 1920x1080

Unfortunately, setting the resolution this way only lasts until the end of the current session.

How to permanently add a resolution?

You might decide that you want to stick to a resolution permanently, and you do not want to switch with xrandr each time you log in. In this case, you will need to modify the xorg config (xorg.conf) file.

The xorg.conf does not exist by default any more, so the first step is that we create it. (But depending on your situation, it might already exist, so if it does, then you can skip ahead here)

However, you need a new display socket in order to run the necessary command. If you are using :0 on your current X session, you probably need to run the command on socket :1

To check what display sockets are in use (e.g. you might have multiple in use if you use something like VNC), check the contents of the following folder:

ls /tmp/.X11-unix/

Once you have found what ports are in use, become root, and execute (replace :1 with the next number depending on the results of running ls /tmp/.X11-unix:

X :1 -configure

This will generate a file called xorg.conf.new, which we want to move:

mv ~/xorg.conf.new /etc/X11/xorg.conf

Now reboot and we are ready to add our custom configuration. As root, create a new folder into /etc/X11:

mkdir /etc/X11/xorg.conf.d

Create a custom configuration file into it, e.g.

vim /etc/X11/xorg.conf.d/10-monitor.conf

In there, a new Monitor section should be added:

Section "Monitor"
    Identifier "Virtual1"
    Modeline "1920x1080_60.00"  172.80  1920 2040 2248 2576  1080 1081 1084 1118  -HSync +Vsync
    Option "PreferredMode" "1920x1080_60.00"
EndSection

Make sure that you get the syntax in this file absolutely right because a misconfigured xorg.conf file will render X unusable, and upon login, you will be stuck on a shell session with no way to start X. If this happens, delete/move your custom configuration file, reboot and X will work again.