screenman

A Python tool to manage and configure multi-monitor setups using EDID information, allowing users to apply predefined screen layouts with ease.

Setup

$ screenman --help
Usage: screenman [OPTIONS]

  Console script for screenman.

Options:
  --log-level TEXT  Set the logging level (e.g., DEBUG, INFO, WARNING, ERROR,
                    CRITICAL)
  --log-file TEXT   Set the log file path.
  --print-info      Print the connected screens and the corresponding
                    layout.If no layout is defined, the default layout 'auto'
                    is used.
  --rescan-pci      Rescan PCI bus before applying layout. Useful for
                    dock/display detection issues after resume.
  --mirror          Mirror the internal (eDP) display to the external display.
  --mirror-off      Revert mirroring and apply the normal layout.
  --help            Show this message and exit.

When wanting to setup a new screen layout, you can use the --print-info flag to get the connected screens information. This information can be used to create a new screen layout.

$ screenman --print-info
<HDMI-2, UID: DL51145435704, primary: True, modes: 13, conn: True, rot: normal, enabled: True, res: (1920, 1080)>
Layout: auto

From that we can create our toml configuration file with the following content:

# the hierarchy of the configuration file is as follows:
# layouts.<layout_name>.<screen_uid>
[layouts.single_baetylus.DL51145435704]
primary = true
mode = [1920, 1080]
position = [0, 0]
rotation = "normal"

A more advanced screenman.toml configuration file can be found in the examples directory.

Mirroring

For presentations or other scenarios where you want to mirror your internal (eDP) display to an external screen:

# Start mirroring — scales the internal display to match the external resolution
screenman --mirror

# Revert to your normal layout
screenman --mirror-off

Usage

I have screenman --log-file ~/.local/logs/screenman.log --log-level DEBUG mapped to a keybinding.

If you can't install screenman with your package manager, you can also run it with uv:

uv tool run screenman --help

Configuration

The configuration file can be stored in one of the following paths:

• Current working directory
• Home directory
• User configuration directory (roaming)
• User configuration directory for "screenman" (non-roaming)
• Site configuration directory

Installation

Dependencies

Install edid-decode.

pip release version

pip install screenman

pip live version

pip install git+https://github.com/Jimmy2027/screenman.git

portage

screenman is available via Jimmy's overlay. Either enable the repo or copy the ebuild to your local overlay.

Then run:

emerge -av screenman