icon

Real-Time Upscaler for Linux

PyPI version Python versions License: GPLv3

A real-time SRCNN upscaler for any X-Window (X11 or XWayland) on GNU/Linux. It uses CuNNy neural networks to perform 2x (or 4x) upscaling to full screen while preserving aspect ratio. Mouse clicks and motion are automatically forwarded to the original window.

Results at 400% magnification

Features

  • Neural-Network upscaling using SRCNNs trained for high-quality upscaling of visual novels and illustrations.
  • Model selection from 9 variants with variable quality/performance trade-offs.
  • Hardware accelerated using Vulkan compute.
  • Tile-Based processing that upscales only the frame regions that change, reducing GPU load for mostly static content.
  • Customizable output geometry: scaling mode (fit, stretch, cover), offset, crop and zoom.
  • Input forwarding as if interacting directly with the original window.

Requirements

  • GNU/Linux (X11 or Wayland with XWayland)
  • Vulkan-capable GPU (NVIDIA, AMD, Intel)
  • Python 3.10 or newer
  • Qt XCB plugin

[!IMPORTANT]

Qt XCB plugin

This library is not installed by default on most desktop environments.

Install instructions (click to expand)

Debian / Ubuntu / Linux Mint

sudo apt update
sudo apt install libxcb-cursor0

Fedora / RHEL / CentOS

sudo dnf install xcb-util-cursor

Arch Linux / CachyOS

sudo pacman -S xcb-util-cursor

openSUSE

sudo zypper install libxcb-cursor0

Installation

Install with pipx (recommended)

pipx install linux-rt-upscaler

Install from source

Required development packages (click to expand)

Debian / Ubuntu / Linux Mint

sudo apt update
sudo apt install gcc make libvulkan-dev libx11-dev libxcb1-dev libx11-xcb-dev \
    libxext-dev libxdamage-dev libxfixes-dev

Fedora / RHEL / CentOS

sudo dnf install gcc make vulkan-loader-devel libX11-devel libxcb-devel libX11-xcb-devel \
    libXext-devel libXdamage-devel libXfixes-devel

Arch Linux / CachyOS

sudo pacman -S base-devel vulkan-devel libx11 libxcb libxext libxdamage libxfixes

openSUSE

sudo zypper install gcc make vulkan-devel libX11-devel libxcb-devel libX11-xcb-devel \
    libXext-devel libXdamage-devel libXfixes-devel

git clone https://github.com/baronsmv/linux-rt-upscaler.git
cd linux-rt-upscaler

pip install -e .

Optional: Desktop integration

After installing, you can add a desktop entry so the GUI appears in your application menu:

curl -fsSL https://raw.githubusercontent.com/baronsmv/linux-rt-upscaler/refs/heads/main/scripts/desktop_integration.sh \
    -o /tmp/desktop_integration.sh
less /tmp/desktop_integration.sh  # always review scripts before running them
sh /tmp/desktop_integration.sh

Usage

After installation, the upscale-gui and upscale commands will be available globally:

Graphical mode

upscale-gui

The GUI displays live thumbnails of every open valid window. Click one to start upscaling that window.

Use the right panel to adjust any setting, and the left panel to create profiles that automatically apply when a matching window is detected, or when selected manually.

Command-line mode

# Upscale the currently active window
upscale

# Interactively select from visible windows
upscale -s

# Run a command and upscale its window
upscale -- <command>

# Choose a specific model (examples)
upscale -m 8x32      # Highest quality, slowest
upscale -m veryfast  # Maximum performance

# Perform 4x upscaling (two 2x passes)
upscale -2

# Crop 100 pixels from top and left, then upscale
upscale --crop-top 100 --crop-left 100

For a full list of options and examples:

upscale --help

Controls

Shortcut Action
Alt+Shift+S Pause upscaling
Alt+Shift+Escape Exit upscaling
Alt+Shift+P Take a lossless screenshot
Alt+Shift+M Switch to the next model
Alt+Shift+G Cycle output geometry (fit, stretch, cover)
Alt+Shift++ / - Zoom in / Zoom out
Alt+Shift+↑ / ↓ / ← / → Pan the upscaled content

All hotkeys can be customised in the configuration file.

Profiles

You can define named configuration profiles in your YAML config file. Profiles let you quickly switch settings for different games or applications without typing long command lines each time.

Create a config file (e.g., ~/.config/linux-rt-upscaler/config.yaml) and add a top-level profiles key. Each profile is a dictionary with an optional match section and an options section.

If no profile is selected manually, the program checks all profiles that have a match section against the title of the target window. If a profile matches (any match criterion is sufficient), its options are applied automatically.

# General defaults (lowest priority)
model: 3x12
double_upscale: true

# Profiles that override if matched
profiles:
  game:
    match:
      title: "Danganronpa"     # Exact match (case-insensitive)
      title_contains: "ronp"   # Or substring match (case-insensitive)
      title_regex: "Dangan.*"  # Or regular expression (case-insensitive)
    options:
      model: 4x24
      double_upscale: true

A more detailed example is included here.

How It Works

  1. Selects a window using X11 to find the target window by PID or WM_CLASS.
  2. Captures the window's pixels using XShm and XDamage.
  3. Upscales with SRCNN compute shaders to a 2x (or 4x) larger image.
  4. Scales with a Lanczos2 shader to fill the monitor.
  5. Renders in a overlay window that bypasses the window manager (so it always stays on top).
  6. Forwards mouse events to the original window.

Future Plans

  • Addition of more SRCNN models (FSRCNNX planned).
  • Native Wayland support (on hold: Wayland capture is deeply compositor-specific and currently doesn’t align with the XShm/XDamage pipeline.)

Known Issues

Mouse forwarding may not work with Wine, Proton <10 and other applications

Synthetic mouse events (clicks, motion, wheel) sent by the overlay are ignored by:

  • Wine and Proton versions older than 10.0 (GE-Proton10 + UMU works).
  • Some native applications like Firefox.

For more details, see issue #7.

Acknowledgments

This project stands on the shoulders of several open-source works, mantained by amazing people:

  • L65536, for the original RealTimeSuperResolutionScreenUpscalerforLinux, which demonstrated the feasibility of real-time SRCNN upscaling on Linux and served as a proof-of-concept for this project.
  • funnyplanter, for the incredible CuNNy neural network upscaling models.
  • Compushady, which served as an invaluable Vulkan foundation during early development.
  • PySide6, the Qt binding that powers the entire graphical interface and overlay window.
  • xcffib, the XCB binding used for window management, monitor querying and event forwarding.
  • Pillow, the Python Imaging Library, used for saving screenshots and rendering OSD messages.
  • PyYAML, the YAML parser used for configuration file operations.

Project links

Data verified by PyPI on Jul 30, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.1.1.post2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for baronsmv from gravatar.com baronsmv

Credits

Author: Mauricio Valentín Barón Salinas

GitHub Statistics

Data verified by PyPI on Jul 30, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

GPL-3.0-or-later
View SPDX License List

Requires

Python >=3.10

Tags

srcnn upscaling cunny super-resolution neural-network linux x11 vulkan

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

linux_rt_upscaler-1.1.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (4.7 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

linux_rt_upscaler-1.1.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (4.7 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

linux_rt_upscaler-1.1.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (4.7 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

linux_rt_upscaler-1.1.1-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (4.7 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

linux_rt_upscaler-1.1.1-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (4.7 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

File details

Details for the file linux_rt_upscaler-1.1.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for linux_rt_upscaler-1.1.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b936fb73d4ef94f780a4671768ca691e9ce0ac87827407800087272106f7f274
MD5 c98170394faa729cff5f9a03353d5468
BLAKE2b-256 c7992f236edbef81056cb4237076f0895f9dea4e5d5c3553cb5e3efaa67c0849

See more details on using hashes here.

Provenance

The following attestation bundles were made for linux_rt_upscaler-1.1.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: build_wheels.yml on baronsmv/linux-rt-upscaler

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file linux_rt_upscaler-1.1.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for linux_rt_upscaler-1.1.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 34b37744dc1cce90d8084e51413ca35306abbf17944bb2c9ec5ac03eb9e09ec8
MD5 44e9a454def4a6454f0f566a8037626e
BLAKE2b-256 a7f55835fec0d57de336c27650e0429119985e4beb19e7ca7bf06ec81f12dbf2

See more details on using hashes here.

Provenance

The following attestation bundles were made for linux_rt_upscaler-1.1.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: build_wheels.yml on baronsmv/linux-rt-upscaler

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file linux_rt_upscaler-1.1.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for linux_rt_upscaler-1.1.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d0fa990aa06d8a01da9c91795541bd1e9cebb986c7d38b3f698ab6c4719a11b2
MD5 1a81f72c0f853f9815c9556712ac31dc
BLAKE2b-256 6e6bed3ff904fc3826e572af8d8a29ba1c71e51c9b18ebc8a8cc79579ed7db4d

See more details on using hashes here.

Provenance

The following attestation bundles were made for linux_rt_upscaler-1.1.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: build_wheels.yml on baronsmv/linux-rt-upscaler

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file linux_rt_upscaler-1.1.1-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for linux_rt_upscaler-1.1.1-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f0a83d19615fd006c206febf1e53a43f12eeace155b3d83d6daedb137ad55847
MD5 1f5d1bfa44ac7189ce513cf0c08dee4e
BLAKE2b-256 3ae5db2e887d1fe8a20972aa5da328c452d123cd03fcde38b36180ce356962a8

See more details on using hashes here.

Provenance

The following attestation bundles were made for linux_rt_upscaler-1.1.1-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: build_wheels.yml on baronsmv/linux-rt-upscaler

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file linux_rt_upscaler-1.1.1-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for linux_rt_upscaler-1.1.1-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9a4bf1f836341513aeaa8760b5757ce1acac6b88d548285dfc5c759d5a6673e4
MD5 a0cd440b14ec4c90bee88e8156671bfe
BLAKE2b-256 a91b47481a86d14416041a5667bce476046e2bba1cef24d1d4e1f15ac0d0bce3

See more details on using hashes here.

Provenance

The following attestation bundles were made for linux_rt_upscaler-1.1.1-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: build_wheels.yml on baronsmv/linux-rt-upscaler

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page