Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
This shell script walks you through the steps required to change the monitor underscan or overscan value on OS-X, when the Display Preferences are not providing the underscan/overscan slider for a given display. This process was documented by Ishan Sharma here: http://ishan.co/external-monitor-underscan and is a part of BashMatic library.
#!/usr/bin/env bash
#
# Script to change underscan/overscan value of a monitor on OS-X.
# © 2016-2019 Konstantin Gredeskoul, distributed under the MIT License.
#
#———————————————————————————————————————————————————————————————————————————————————————————
# EXCEPT AS REPRESENTED IN THIS AGREEMENT, ALL WORK PRODUCT BY DEVELOPER IS PROVIDED "AS IS".
# OTHER THAN AS PROVIDED IN THIS AGREEMENT, DEVELOPER MAKES NO OTHER WARRANTIES, EXPRESS OR
# IMPLIED, AND HEREBY DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING ANY WARRANTY OF
# MERCHANTABILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE.
#———————————————————————————————————————————————————————————————————————————————————————————
#
# How to run this script?
# 1. Open Terminal application (/Applications/Utilities/Terminal.app)
#
# 2. Decide if you want to reduce (negative) or increase (positive) screen size.
# You should think of a number of percentage points to change it by, for example
# it could be -5 (for underscan) or 5 for overscan.
#
# 3. Set the following variable to this number by pasting the following, and changing the value:
#
# export SCAN_CHANGE_PERCENT=5 # overscan, change 5 to -5 for underscan
#
# 3. Copy and paste the following commands:
#
# curl -fsSL http://bit.ly/change-underscan-osx > ./change-underscan
# chmod 755 ./change-underscan
# ./change-underscan ${SCAN_CHANGE_PERCENT}
#
# 4. You can also run it as:
#
# ./change-underscan 5
#
# 5. Follow the prompts and perform actions asked by the script.
#
# 6. Enjoy being able to see Mac OSX top menu and your dock :)
curl -fsSL http://bit.ly/bashmatic-bootstrap | /usr/bin/env bash
if [[ -d ~/.bashmatic ]]; then
source ~/.bashmatic/init.sh
change-underscan "$1"
else
echo "The script $0 was installed correctly, however underlying library"
echo "was not. Please install it by running the following:"
echo
echo " cd ~/"
echo " curl -so bashmatic.zip https://codeload.github.com/kigster/bashmatic/zip/master"
echo " unzip bashmatic.zip && mv bashmatic-master ~/.bashmatic"
echo
echo "After that, re-run this script."
fi
@jneuendorf

This comment has been minimized.

Copy link

@jneuendorf jneuendorf commented Jan 17, 2019

This is REALLY awesome! Thank you soo much ❤️ 😄

@HashBah

This comment has been minimized.

Copy link

@HashBah HashBah commented Jan 17, 2019

How do I open it properly? i downloaded it and tried to drag adn to open it manuaelly with terminal but nothing seem to work. it just gives says session finished.

@chestertc

This comment has been minimized.

Copy link

@chestertc chestertc commented Mar 2, 2019

Managed to fix the problem in two iterations! Really awesome! Thank you so much!!

@nativeman2

This comment has been minimized.

Copy link

@nativeman2 nativeman2 commented Aug 30, 2019

(tears in my eyes)
This script is awesome.

@kigster

This comment has been minimized.

Copy link
Owner Author

@kigster kigster commented Sep 4, 2019

How do I open it properly? i downloaded it and tried to drag adn to open it manuaelly with terminal but nothing seem to work. it just gives says session finished.

How to Run This Script

  1. Open Terminal application
  2. Paste the following code, setting SCAN_PERCENT to the percentage desired. Less than 100 is underscan, more than 100 is overscan.
SCAN_PERCENT=100
curl -fsSL http://bit.ly/fix-underscan > /tmp/fmu; bash /tmp/fmu ${SCAN_PERCENT}
@kigster

This comment has been minimized.

Copy link
Owner Author

@kigster kigster commented Sep 4, 2019

(tears in my eyes)
This script is awesome.

❤️

@kigster

This comment has been minimized.

Copy link
Owner Author

@kigster kigster commented Sep 18, 2019

Please note — the script now lives as a part of bashmatic library and therefore installs it into ~/.bashmatic.

@ianvoyager

This comment has been minimized.

Copy link

@ianvoyager ianvoyager commented Sep 25, 2019

Hi kirsten, I have attempted to use your script many times however I simply cannot get it to work on my Mac Mini running 10.14.6 in regards to setting / resetting the overscan and under scan issues when connected to my TV via HDMI cable.

I have taken some screen shots of the errors or screens I get in terminal; here is the link.

Thanks in advance!

@kigster

This comment has been minimized.

Copy link
Owner Author

@kigster kigster commented Sep 25, 2019

Yes, I can see the error thanks for posting images.

In the second screen shot you have ${10} as the last argument. Change that to just 10 and it should work.

I apologize as I’m working on bashmatic framework now and may have introduced breaking bugs, so email your screen shots to kigster AT gmail.com.

@ryanwwest

This comment has been minimized.

Copy link

@ryanwwest ryanwwest commented Dec 22, 2019

This is awesome! However it inevitably leads to a scaled image, causing pixel blur since the resolution is no longer 1:1 with the pixel count. Is there a way in MacOS to instead change the resolution displayed on the monitor as this person did on Windows so you still use pixels 1:1, eliminating blur?

@itsazzad

This comment has been minimized.

Copy link

@itsazzad itsazzad commented Jul 2, 2020

How do I open it properly? i downloaded it and tried to drag adn to open it manuaelly with terminal but nothing seem to work. it just gives says session finished.

How to Run This Script

  1. Open Terminal application
  2. Paste the following code, setting SCAN_PERCENT to the percentage desired. Less than 100 is underscan, more than 100 is overscan.
SCAN_PERCENT=100
curl -fsSL http://bit.ly/fix-underscan > /tmp/fmu; bash /tmp/fmu ${SCAN_PERCENT}

/tmp/fmu: line 23: ~/.bashmatic/lib/Loader.bash: No such file or directory
/tmp/fmu: line 25: change-underscan: command not found

@yougotwill

This comment has been minimized.

Copy link

@yougotwill yougotwill commented Jul 10, 2020

If this script isn't working for you I have found a working alternative for me. I hope this helps someone else :) https://github.com/univ-of-utah-marriott-library-apple/display_manager#underscan

@msropp

This comment has been minimized.

Copy link

@msropp msropp commented Sep 24, 2020

This works like a charm!!!

@kigster

This comment has been minimized.

Copy link
Owner Author

@kigster kigster commented Sep 24, 2020

Glad someone is able to follow the instructions!!! LOL ♥️

@msropp

This comment has been minimized.

Copy link

@msropp msropp commented Sep 24, 2020

I was dealing with a monitor that is too big for my ergonomic comfort. I've had the right side and bottom taped off for months and had to move my dock to the left (shudder). I still had problems with not being able to see notifications in the notification center (upper right) due to the paper blocking that portion, as well as part of the menu bar. Now, I'm all good! :)

@ianvoyager

This comment has been minimized.

Copy link

@ianvoyager ianvoyager commented Sep 25, 2020

Hello! I was the original question asker and I’m afraid I don’t really know how to implement these code based actions... 😅 ...Is anyone able to help me out? My understanding is I could create an icon on my desktop that I can double click and this will adjust the Overscan back to what it should be in system preferences...?

@kigster

This comment has been minimized.

Copy link
Owner Author

@kigster kigster commented Sep 25, 2020

@ianvoyager Dear Ian, Mac OS-X is — behind the scenes — a UNIX-like system. You need to use Spotlight (⌘-Space) and search for "Terminal". Run the Terminal Application, and you will see a window with a prompt. You can type commands into the prompt, and the OS will execute them for you. You can read more about using Terminal and UNIX commands here: https://macpaw.com/how-to/use-terminal-on-mac

Once you have Terminal open, you can switch back to Chrome and copy the following commands:

curl -fsSL http://bit.ly/change-underscan-osx > ./change-underscan
bash ./change-underscan 5

(Make sure to press ENTER after the last command, in case it doesn't get run automatically.

You should replace "5" above with the value representing a percentage of the screen you want to resize by. Try starting with "5", if it goes the wrong direction, try again with "-5". And so on.

Hope this helps.

@billdlv

This comment has been minimized.

Copy link

@billdlv billdlv commented Oct 14, 2020

I ran the script but I am getting Unable to find the display scan value to change error. I tried connecting a second display and still get the same error. I need to increase the screen size a bit so I used 5. I'm running 10.15.7. I also notice that the pscan key does not appear in the file.

@kigster

This comment has been minimized.

Copy link
Owner Author

@kigster kigster commented Oct 14, 2020

@billdlv it’s possible OSX changed how they do this recently.

Having said that, the most important thing is to follow the riot instructions exactly. You need to unplug the monitor when it says so, and plug it back in when asked. Don’t skip any step! HTH

@robjr3

This comment has been minimized.

Copy link

@robjr3 robjr3 commented Oct 14, 2020

Hi, I've had the same problem with overscanning whenever I restart. The only solution I found was reseting the whole computer. I ran the scipt as described but when a window pops up for downloading it says it can't find the software. I have a macbook pro mid 2012 running catalina 10.15.7. what could possibly be wrong? thanks in advance.

@billdlv

This comment has been minimized.

Copy link

@billdlv billdlv commented Oct 15, 2020

@billdlv it’s possible OSX changed how they do this recently.

Having said that, the most important thing is to follow the riot instructions exactly. You need to unplug the monitor when it says so, and plug it back in when asked. Don’t skip any step! HTH

I think it's changed, I tried another python based script univ-of-utah-marriott-library-apple/display_manager It also complains about not being able to find the parameter in the file.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.