FAQ & Troubleshooting
Common Issues
Section titled “Common Issues”I don’t see any files in the grid
Section titled “I don’t see any files in the grid”- Make sure you have opened a folder that contains supported media files. Press O to open the folder picker.
- Check that your files have recognized extensions. See the Media Capabilities page for the full list of supported formats.
- If you are searching, click the clear button (×) in the search bar to reset the filter and show all files.
Videos don’t play (preview is blank or shows a placeholder)
Section titled “Videos don’t play (preview is blank or shows a placeholder)”Video playback needs libmpv, which every released package bundles:
- Linux (AppImage), macOS and Windows: mpv, ffmpeg and dav1d ship inside the package, so no media library has to be installed. The AppImage still uses the base system libraries your desktop already has (on Linux: ALSA
libasound, the C++ runtimelibstdc++,libdrmand the GPU drivers). If video still doesn’t work, the cause is usually the GPU: update your graphics drivers so they support Vulkan. - Building from source: install
libmpv-dev(Debian/Ubuntu) or the equivalent for your distribution, pluslibdav1d-devfor AVIF images. A from-source build links the system libmpv.
You can still view images and play audio without libmpv. Use the “Open in system player” button to play video files in your default media player.
The application won’t start or crashes on launch
Section titled “The application won’t start or crashes on launch”- Stale configuration: Try deleting your
config.tomlfile. Its location depends on your OS; see the Configuration File page. The app will recreate it with defaults on next launch. - Vulkan / GPU issues: Media Sort uses wgpu for rendering, which requires Vulkan, Metal, or DirectX 12 support. Update your GPU drivers and ensure your graphics stack is functional.
- Missing system libraries: The AppImage bundles its own X11/Wayland libraries, but it deliberately uses the host’s ALSA (
libasound), C++ runtime (libstdc++),libdrmand GPU drivers — every desktop distribution ships those, so a missing one means the desktop itself is incomplete. A self-compiled build additionally needslibmpv-dev(and the equivalent oflibx11/libwayland/libasound2when they are not installed).
How do I reset all settings to defaults?
Section titled “How do I reset all settings to defaults?”Delete the config.toml file at the location listed on the Configuration File page. Media Sort will create a fresh configuration file on next launch.
I upgraded from the old WPF v2.x version. Where are my settings?
Section titled “I upgraded from the old WPF v2.x version. Where are my settings?”Media Sort automatically migrates settings from the legacy WPF application on first launch. If migration didn’t work, ensure the old config.json file exists at the expected location:
$CONFIG_DIR/Image Sort/config.json
If the file is present but settings still weren’t migrated, delete the new config.toml and restart the application. Migration runs only once, when no config.toml exists.
Can I use Media Sort entirely with the keyboard?
Section titled “Can I use Media Sort entirely with the keyboard?”Yes. Media Sort is designed for keyboard-first operation. Every action (navigating folders, selecting files, moving, copying, deleting, renaming, creating folders, and managing pinned folders) has a keyboard shortcut. See the Keyboard Layout page for the complete reference.
Where are my files after I delete them?
Section titled “Where are my files after I delete them?”Deleted files are moved to your operating system’s trash (Recycle Bin on Windows, Trash on macOS/Linux). They are not permanently deleted. While Media Sort is running, you can press Q to undo a deletion and restore the file to its original location. After closing the app, you can still manually restore files from the system trash.
Does Media Sort modify my original files?
Section titled “Does Media Sort modify my original files?”Sorting actions (move, copy, rename, delete) modify file locations and names, but Media Sort never alters file contents. Metadata extraction is read-only. Image and video files are never re-encoded or modified.
Where to Report Issues
Section titled “Where to Report Issues”If you encounter a bug or have a feature request, please open an issue on GitHub: