Hardware FixRecommendedDevice not working? Your driver may be the problemCheck updates for common hardware issues.Fix DriversHalloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsPC HealthRecommendedCrashes, freezes, slowdowns? Check your PC nowSpot repairable issues before they interrupt work.Check PC×
FREEDOM251

Freedom251 › Blog › Controllers

How to install and configure RetroArch on a RISC-V Linux board

By Freedom251 Team · · 11 min read

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Install RetroArch natively when your board is running a 64-bit riscv64 userspace and your distribution has a matching package. If no suitable package exists, compile RetroArch and at least one libretro core into a directory you own. Choose the video driver from the board’s working Mesa/DRM stack—usually OpenGL or OpenGL ES first—and treat Vulkan as optional until the board proves it works. After launch, set writable directories, install or build cores, detect and map your controller, then test one lightweight game before changing advanced settings.

The same frontend can start on many RISC-V boards, but GPU drivers, Mesa versions, memory bandwidth, display servers and available cores differ substantially. A successful riscv64 package installation therefore confirms only that the frontend can run; it does not establish that every renderer or emulator core will work.

As an Amazon Associate I earn from qualifying purchases.

Check the board before choosing an installer

Do not download an x86_64 or ARM64 build and hope that translation will make it usable. First identify the userspace architecture, distribution release and graphics environment from the board itself:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
uname -m
dpkg --print-architecture 2>/dev/null || true
cat /etc/os-release

Continue with a native package only when the first command reports riscv64 and the package manager reports the distribution’s native RISC-V architecture. A 32-bit userspace on a 64-bit-capable board is a different target and cannot use a riscv64 package directly.

#1 Best Overall
Elebase USB to USB C Adapter for iPhone 18 Pro Max,USBC Car Charger Adapter | 4Pack Type C Female to A Male Cable Converter for Apple Duo 17 16 15 14 Plus,iWatch Watch 12 11 10,iPad 9 8 Air,Airpods 5 4
  • Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
  • Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
  • Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
  • Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
  • 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.

Also confirm that the board has the display path you intend to use: a working desktop session, DRM/KMS, Wayland, X11 or another supported path. The existence of a display connector does not prove that accelerated Mesa rendering is available. Record the board model, kernel, Mesa version, display protocol, resolution and renderer string; those details are essential if a window is black or a core behaves differently from another board.

Choose an installation route

Route Architecture requirement Advantages Important limitations
Distribution package Native riscv64 package in an enabled repository Dependency integration, ordinary security updates and the simplest uninstall Version, compile-time features and core locations are controlled by the distribution; in-app updating may be disabled
Flatpak A Flatpak build published for the board’s architecture Self-contained application and a consistent frontend version Sandbox permissions can limit graphics, devices or cores; an x86_64 or ARM64 artifact will not run on RISC-V
Source build A working compiler, headers and libraries for the board Works when repositories lack a package and lets you select features and cores Compilation takes time and memory; every optional backend adds dependencies and maintenance

Use the first route that satisfies both architecture and graphics requirements. If a package starts but exposes no usable renderer or core-management path, a source build may be more useful than repeatedly changing frontend settings.

Install the native Ubuntu or Debian package

Refresh metadata and install

  1. Refresh the repository indexes:
    sudo apt update
  2. Install the packaged frontend:
    sudo apt install retroarch
  3. Check what was installed and which repository candidate is selected:
    retroarch --version
    apt policy retroarch

Repository contents are volatile, so query the live index instead of copying a version from an old tutorial. The Ubuntu package index listed retroarch_1.18.0+dfsg-1_riscv64.deb (6.2 MB) when accessed on 16 October 2026. Debian trixie listed RetroArch 1.20.0+dfsg-2, with a 6,053.1 kB package and 20,044.0 kB installed size, on the same date. These are package metadata, not speed or compatibility measurements.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Ubuntu places RetroArch in its community-maintained universe archive. The Libretro GNU/Linux guidance warns that there is “no promise of support or regular update schedule.” Its Linux instructions also state: “Distro packages can be nice, but we don’t control those builds (aside from the official PPAs) and can’t guarantee their quality or how often they are updated.” Treat those builds as convenient integration, not as a guarantee that the newest frontend or every core is available.

When APT reports no candidate

  • Run the architecture checks again and make sure the repository actually publishes your release for riscv64.
  • Verify that the required repository component is enabled, then run sudo apt update again.
  • Confirm the release codename in /etc/os-release matches the configured sources.
  • Do not install a foreign-architecture .deb by hand unless you have verified every dependency and intentionally configured multi-architecture support.

If no native candidate exists after those checks, use a supported Flatpak build or compile from source rather than forcing an unrelated binary.

Rank #2
Anker USB-C Hub, 5-in-1 USB Hub for Laptops, 4K HDMI Multiport Adapter | USB C Dongle with 90W Max Power Delivery, 3×5Gbps USB A Data Ports, for MacBook, Dell, and More (Charger Not Included)
  • 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
  • 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
  • Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
  • 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
  • What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.

Try Flatpak only when a RISC-V build exists

RetroArch’s documented Flatpak commands are:

flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install --user flathub org.libretro.RetroArch
flatpak run org.libretro.RetroArch

Before running them, verify that the Flathub application has a build for your board’s architecture. A universal package is not automatically universal across CPU families. Even with a matching build, sandboxing can restrict access to Vulkan, input devices, system directories or downloadable cores. If the application launches but cannot see a controller, ROM directory or graphics device, inspect its permissions and prefer a native package or user-owned source install when the sandbox is the cause.

Flatpak can be a clean choice for a desktop board with a supported build, but it is not a workaround for missing RISC-V graphics drivers. The sandbox cannot create a Vulkan device that the host Mesa stack does not provide.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Build RetroArch and cores from source

Install the base toolchain

The official compilation guidance requires a compiler/toolchain, pkg-config, OpenGL headers and at least one libretro implementation. On Debian or Ubuntu, begin with this dependency family:

sudo apt install build-essential pkg-config libxkbcommon-dev zlib1g-dev 
  libfreetype6-dev libegl1-mesa-dev libgles2-mesa-dev libgbm-dev 
  libavcodec-dev libsdl2-dev libxml2-dev yasm

This is a starting set, not a promise that every feature will compile. Add libraries only for the renderer, audio backend, controller stack and optional functions you intend to use. A headless or minimal image may need additional development packages; a board with no Vulkan driver should not acquire Vulkan headers merely to select that backend.

Fetch the source and build

The libretro-super repository supplies scripts for fetching RetroArch and libretro projects. A user-owned installation avoids modifying system files:

Rank #3
Sale
Anker USB C Hub, 7in1 Multi-Port USB Adapter, 4K@60Hz USBC to HDMI Splitter | 85W Max PD, 2 USB 3.0 & 1 USBC Data Ports, SD/TF Card Reader, for Laptops/Mac and Other Type C Devices (Charger Not Included)
  • Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
  • Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
  • Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
  • Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
  • What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
git clone https://github.com/libretro/libretro-super.git
cd libretro-super
SHALLOW_CLONE=1 ./libretro-fetch.sh
./retroarch-build.sh
# Build at least one core with the project's core build scripts.
mkdir -p "$HOME/ra/cores"
cd retroarch
make DESTDIR="$HOME/ra" install
cd ..
./libretro-install.sh "$HOME/ra/cores"

Build at least one core rather than installing only the frontend. The fetch script and project core scripts can retrieve many projects; on a memory-constrained board, select only the systems you plan to use and allow extra time for compilation. The exact optional dependencies depend on those choices.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Launch the user install

The staged files normally place the executable below your chosen prefix, but the exact path can vary with the build configuration. Launch the executable from the $HOME/ra tree or add its bin directory to your shell’s PATH. Confirm the result with:

retroarch --version

If the command is not found, invoke the full path to the installed binary rather than installing a second system copy. Keeping one known executable prevents you from editing the configuration for the package while launching the source build, or vice versa.

Configure video for the board’s actual graphics stack

Open Settings → Drivers → Video and select a backend that the board exposes. Start with OpenGL or OpenGL ES when Mesa reports a working implementation. Select Vulkan only after the board’s own Vulkan tools identify a working device and the desktop session can use it.

Backend Use it when What to watch for
OpenGL The desktop Mesa stack exposes desktop OpenGL through the active X11 or Wayland path A package can include OpenGL support while the board’s driver still lacks acceleration
OpenGL ES The board exposes GLES through its DRM or embedded graphics stack Some shader or scaling features may differ from desktop OpenGL
Vulkan A working Vulkan userspace and device are confirmed on that exact board and image Driver maturity, package sandboxing and core requirements can make it unavailable
SDL or software path Accelerated paths fail and you need a diagnostic or fallback window Software rendering can be too slow for demanding systems and does not fix a broken display session

Apply one change at a time and restart RetroArch if the driver selection requires it. A black window or immediate crash is usually a graphics-path problem, not proof that the CPU architecture is unsupported. Switch among the available OpenGL, OpenGL ES, SDL and software paths, then inspect the board’s Mesa/DRM logs.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #4
Sale
UGREEN USB to USB C Adapter Combo 4-Pack, 10Gbps USB C Converter Space Gray | Data transfer & Fast charging for MacBook, iPhone 17/16/15, iPad, Samsung Galaxy, Apple Watch
  • Dual Converters, Infinite Potential:Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
  • Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
  • Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
  • Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
  • Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft

Set audio and writable directories

Choose the audio driver

Go to Settings → Drivers → Audio and select the active PipeWire, PulseAudio, ALSA or SDL path. Test the system audio device outside RetroArch first. If the operating system cannot play a basic sound, changing RetroArch’s driver will not repair the device, permissions or session service.

Use directories your account can write

Set the content, core and system locations to paths owned by your user, for example:

  • ~/RetroArch/cores for core shared libraries
  • ~/RetroArch/system for firmware and system data required by particular cores
  • ~/Games for your legally obtained game files

Create the directories before selecting them in Settings → Directory. A read-only system directory can make downloads appear to succeed while leaving no usable file, especially when a distribution deliberately disables in-app updates.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Install, update and locate libretro cores

Upstream-style core management

When the build exposes the updater, open Online Updater → Update Core Info Files, then use Core Downloader or Core Updater. Select one small, well-supported system first and verify that it appears under Load Core before adding more. Update the information files before downloading so the frontend has current metadata and paths.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Distribution-package management

Debian documents that package management disables in-app auto-update and that cores may live in a system-wide directory. If Core Updater is missing, install the distribution’s matching libretro-* packages, run Update Core Info Files, and inspect Settings → Directory → Core to see where the package expects them. Do not mix a system package’s cores with files from an unrelated architecture or build unless you have verified their ABI and location.

Best Value
Anker USB C Hub, 5-in-1 USBC to HDMI Splitter with 4K Display | 85W Max PD, 1 Powered USB-C 5Gbps & 2 Powered USB-A 3.0 5Gbps Data Ports, for MacBook Pro, MacBook Air, Dell and More (Black)
  • 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
  • Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
  • Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
  • HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
  • What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.

Source-build management

For a source install, place the files produced by the core build scripts in the same user-owned core directory passed to libretro-install.sh. If a core is not listed, check that the file has the board’s architecture, is readable by your account and is in the directory shown under Settings → Directory → Core. The frontend and core are separate components: rebuilding RetroArch alone does not create an emulator core.

Connect and map a controller

  1. Connect the USB or Bluetooth controller and confirm that Linux sees it. Useful checks include lsusb for USB enumeration and the presence of an input device below /dev/input.
  2. If no device appears, check the cable, Bluetooth pairing, udev permissions and whether your Wayland or X11 session exposes the device to desktop applications.
  3. In RetroArch open Settings → Input → RetroPad Binds → Port 1 Controls.
  4. Choose the detected device, map each button and analog direction, and save the controller profile.
  5. Load a small test game and verify the menu, confirm, cancel, shoulder and hotkey buttons before changing latency or turbo settings.

Detection and mapping are separate. A controller can be visible to Linux yet have an unusable RetroPad layout until the profile is saved. If it works in one session but not another, compare the session type and device permissions rather than remapping every game.

Run a controlled first test

  1. Start RetroArch from the package or the full path to your user install.
  2. Confirm the selected video driver and that a visible menu renders without corruption.
  3. Confirm audio with a known working system output.
  4. Load one lightweight 8-bit or 16-bit core and a test ROM.
  5. Check controller directions, buttons, save-state behavior and exit handling.
  6. Only after those paths work, save a per-core or per-content configuration.

This order isolates failures. Changing shaders, run-ahead, latency, scaling and multiple cores before the basic path works makes it difficult to tell whether the fault is the frontend, driver, core or content.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Troubleshoot by symptom

Symptom Likely checks Corrective action
No APT package candidate Architecture, enabled repository component, release codename and repository metadata Enable the native RISC-V repository and refresh indexes; otherwise use a matching Flatpak or source build
Black window or startup crash Selected renderer, Mesa/DRM logs, display protocol and permissions Try the available OpenGL, OpenGL ES, SDL or software path; fix the host graphics stack before tuning cores
Vulkan is unavailable Whether the board has a Vulkan userspace and working device; whether Flatpak can access it Install or repair the board’s Vulkan driver if supported, or use OpenGL/OpenGL ES
No cores listed Core info files, Settings → Directory → Core, package contents and file permissions Update core info files; install the distribution’s libretro-* packages or place source-built cores in the configured directory
Controller not detected lsusb, /dev/input, udev rules, Bluetooth pairing and Wayland/X11 access Fix Linux visibility and permissions, then remap and save the Port 1 profile
Compilation is extremely slow or fails from memory pressure Available RAM, swap and the number of cores selected for the build Use a swap file if appropriate for the board, build only the needed core and avoid unsupported optimization flags
Emulation is slow despite a successful launch Core choice, renderer, resolution, Mesa version, memory bandwidth and board model Retest with a lightweight 8- or 16-bit system and record the complete graphics and core details before changing settings

Set realistic performance expectations

RISC-V boards do not share one graphics implementation. GPU hardware, Mesa maturity, kernel DRM drivers, memory bandwidth and display output can differ even when two boards run the same distribution. No authoritative benchmark establishes a universal frame rate or a list of cores that works on every board, so do not infer performance from the frontend version or package size.

Measure one core at a time on the exact board and image. Start with systems that place modest demands on CPU and GPU, then move to heavier cores only after video, audio and input remain stable. Keep a troubleshooting record containing the board model, kernel, Mesa version, renderer string, resolution, RetroArch version and core name. That record is more useful than a generic “RISC-V is fast” or “RISC-V is slow” claim.

Maintain and back up the installation

  • For APT installs, use the distribution’s normal update process and check apt policy retroarch when you need to know which candidate is available.
  • For Flatpak, update through Flatpak and recheck device permissions after major runtime changes.
  • For source builds, keep the commit or release used for RetroArch and each core, retain the dependency list and rebuild in the same user-owned prefix when upgrading.
  • Back up your configuration, controller profiles, saves, states and BIOS/system files separately from the executable. A package reinstall should not erase those user directories.
  • After an update, retest the renderer, one core and the controller before changing several settings at once.

When a distribution package lacks an in-app core updater, that behavior is intentional package management policy rather than evidence that the frontend is broken. Keep the package’s core directory and your user content directory clearly separated so an update does not overwrite the files you maintain yourself.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

ControllersemulationLibretroLinuxMesaRetroArchRISC-Vriscv64

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
Outdated Drivers Are Slowing You DownFree scan - exact matches
PC Slower Than It Used to Be?Free scan - under a minute

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.