This guide explains how to use the Python GUI installer for Affinity software on Linux. The installer provides a user-friendly graphical interface to set up and install Affinity applications.
- Overview
- Getting Started
- Button Reference
- Step-by-Step Workflows
- Understanding the Log Output
- Troubleshooting
The GUI installer is a graphical application that helps you:
- Set up Wine (a compatibility layer to run Windows software)
- Install system dependencies automatically
- Download and install Affinity applications
- Configure hardware acceleration (OpenCL)
- Manage and update your Affinity installations
The installer window has:
- Button sections on the left side (organized by function)
- Log output on the right side (shows what's happening)
- Status information at the bottom
- Open a terminal
- Navigate to the installer directory:
cd ~/.config/AffinityOnLinux/AffinityScripts
- Run the Python installer:
python3 AffinityLinuxInstaller.py
The GUI window will open. You'll see several button sections on the left and a log area on the right.
The easiest way to get started! This button does everything automatically:
- Detects your Linux distribution
- Checks and installs all required system packages
- Downloads and sets up Wine
- Installs Windows components (.NET, fonts, etc.)
- Configures everything for Affinity
- Asks if you want to install an Affinity app
When to use: If this is your first time installing, or you want a fresh setup.
Time required: 10-30 minutes (depends on internet speed)
These buttons handle the setup process step-by-step. Use them if you prefer manual control or need to fix something.
Downloads and configures the custom Wine build needed to run Affinity software.
What it does:
- Downloads Wine binaries
- Sets up the Wine environment in
~/.AffinityLinux - Downloads and installs Windows metadata files
- Sets up OpenCL support (vkd3d-proton)
- Configures Wine for Windows 11 compatibility
When to use: When you need Wine set up but don't want to do the full setup.
Time required: 5-10 minutes
Installs required Linux packages on your system (wine, winetricks, wget, curl, etc.).
What it does:
- Checks which packages are missing
- Installs them using your distribution's package manager
- Shows progress in the log
When to use: If you get dependency errors or want to install packages manually.
Time required: 1-5 minutes (may ask for your password)
Installs Windows components needed by Affinity (like .NET Framework, fonts, Visual C++).
What it does:
- Installs .NET Framework 3.5 and 4.8
- Installs Windows core fonts
- Installs Visual C++ Redistributables
- Installs MSXML libraries
- Configures Vulkan renderer
When to use: If Affinity complains about missing Windows components.
Time required: 10-20 minutes
Re-downloads and installs Windows metadata files (may get corrupted during Affinity installation).
What it does:
- Removes old metadata files
- Downloads fresh Windows metadata from archive.org
- Extracts them to the Wine environment
When to use: If you get errors about missing Windows components or metadata corruption.
Time required: 2-5 minutes
Downloads the Affinity installer file to your computer.
What it does:
- Opens a file save dialog
- Downloads
Affinity x64.exefrom Affinity Studio - Saves it where you choose (defaults to Downloads folder)
- Shows download progress
When to use: When you want to download the installer separately, or prepare it for later.
Time required: 2-10 minutes (depends on internet speed)
Note: You can use this downloaded file with "Install from File Manager" later.
Install any Windows program (.exe file) using the custom Wine setup.
What it does:
- Opens a file dialog to select an .exe file
- Asks for the application name
- Runs the installer through Wine
- Creates a desktop entry for the app
When to use: When you have an installer file already downloaded, or want to install non-Affinity software.
These buttons let you update existing Affinity installations.
Updates the corresponding Affinity application to a newer version.
What it does:
- Asks you to select the new installer .exe file
- Runs the installer (updates existing installation)
- Reinstalls WinMetadata (to prevent corruption)
- For Affinity v3 (Unified), reinstalls settings files
When to use: When a new version of Affinity is released and you want to update.
Time required: 5-15 minutes
Note: These buttons only work if the application is already installed. If a button is disabled (grayed out), that app isn't installed yet.
These tools help fix common issues.
Opens the Wine configuration tool (winecfg) using your custom Wine setup.
What it does:
- Launches the Wine configuration GUI
- Lets you adjust Wine settings, Windows version, graphics, etc.
When to use: If you need to change Wine settings manually, troubleshoot graphics issues, or configure libraries.
Sets the Windows version to Windows 11 and configures the graphics renderer.
What it does:
- Sets Wine to Windows 11 mode
- Lets you choose between Vulkan (recommended) or OpenGL renderer
- Applies the configuration
When to use: If OpenCL/hardware acceleration isn't working, or you're having graphics issues.
Renderer options:
- Vulkan (Recommended): Better performance, enables OpenCL support
- OpenGL (Alternative): Fallback option if Vulkan doesn't work
Installs Affinity v3 settings files to enable settings saving.
What it does:
- Downloads settings files from the repository
- Copies them to the correct location in the Wine environment
- Only works for Affinity v3 (Unified application)
When to use: If Affinity v3 doesn't save your preferences/settings.
Note: This only works for Affinity v3 (Unified). It won't help with Photo/Designer/Publisher v2.
Shows credits for contributors to the project.
Closes the installer window.
Goal: Install Affinity for the first time with minimal steps.
Steps:
- Start the installer (see Getting Started)
- Click "One-Click Full Setup"
- Wait for the setup to complete (watch the log for progress)
- When prompted, choose "Yes" to install an Affinity application
- Select which app you want (e.g., "Affinity (Unified)")
- Choose "Download from Affinity Studio (automatic)" and click OK
- Wait for the download and installation
- Done! Your app should appear in your application menu
Total time: 15-40 minutes
Goal: Install Affinity manually with full control over each step.
Steps:
- Start the installer
- Click "Install System Dependencies" → Wait for completion
- Click "Setup Wine Environment" → Wait for completion
- Click "Install Winetricks Dependencies" → Wait for completion
- Download the installer:
- Option A: Click "Download Affinity Installer" → Choose save location → Wait
- Option B: Download manually from https://downloads.affinity.studio/Affinity%20x64.exe
- Click "Install from File Manager" → Select the downloaded .exe file → Enter app name
- Follow the installer wizard that opens
- Done!
Total time: 20-45 minutes
Goal: Install the new unified Affinity application.
Steps:
- Complete setup (use "One-Click Full Setup" or manual steps)
- Click "One-Click Full Setup" and when prompted, select "Affinity (Unified)"
- OR use "Install from File Manager" if you have the installer
- Choose download or provide your own installer
- After installation completes, click "Fix Settings" to enable settings saving
- Done! Launch Affinity from your application menu
Note: The unified app requires the settings fix to save preferences properly.
Goal: Update Affinity Photo/Designer/Publisher to a new version.
Steps:
- Download the new installer:
- Click "Download Affinity Installer" → Save it
- OR download manually from your Affinity account
- Click the appropriate update button (e.g., "Affinity Photo")
- Select the new installer .exe file you downloaded
- Wait for the update to complete
- Done! Your app is updated
Note: The update process preserves your existing settings and files.
Goal: Make Affinity v3 save your settings properly.
Steps:
- Make sure Affinity v3 is installed
- Click "Fix Settings"
- Wait for the settings files to install
- Launch Affinity v3 and check if settings save
Note: You may need to restart Affinity for changes to take effect.
Goal: Enable GPU acceleration if it's not working.
Steps:
- Click "Set Windows 11 + Renderer"
- Select "Vulkan (Recommended - OpenCL support)"
- Click OK and wait for configuration
- Restart Affinity and check:
- Affinity → Preferences → Performance → Hardware Acceleration
Note: If Vulkan doesn't work, try OpenGL as an alternative.
The log area on the right side of the window shows what's happening. Here's what different message types mean:
- [INFO] - General information about what's happening
- [SUCCESS] or ✓ - Something completed successfully
- [WARNING] or ⚠ - Something went wrong but it's not critical
- [ERROR] or ✗ - Something failed
Good signs:
- Messages ending with "✓ ... installed" or "completed"
- Progress percentages increasing
- "Download completed" messages
- "Installation completed" messages
Warning signs:
- Many "[WARNING]" messages (might be okay, but pay attention)
- "Failed to..." messages
- Errors that stop the process
Action required:
- If you see errors that stop installation, check the error message
- Try running the failed step again
- Check the Troubleshooting section
The log is divided by separator lines (━━━━━━━━━━━━━━━━). Each section represents a different operation (e.g., "Wine Binary Setup", "Affinity Photo Installation").
Solution: Click "Setup Wine Environment" first and wait for it to complete.
Solution: Click "Install System Dependencies". If it fails, you may need to install packages manually using your package manager.
Solutions:
- Check your internet connection
- Try clicking the download button again
- Use "Download Affinity Installer" to download separately, then use "Install from File Manager"
- Download manually from https://downloads.affinity.studio/Affinity%20x64.exe
Solutions:
- Wait a few seconds (it may take time to start)
- Check the log for errors
- Make sure Wine is fully set up
- Try running the installer again
Solutions:
- Click "Set Windows 11 + Renderer" → Choose Vulkan
- Make sure you have Vulkan drivers installed on your system
- Check Affinity Preferences → Performance → Hardware Acceleration
- If still not working, try OpenGL renderer
Solution: Click "Fix Settings" to install the settings files.
Solution: Those apps aren't installed yet. Install them first using "One-Click Full Setup" or "Install from File Manager".
Solutions:
- Some operations require your password (sudo) - enter it when prompted
- Make sure you have write permissions in
~/.AffinityLinux
Solutions:
- Wait 5-10 minutes (some operations take a long time)
- Check the log - it should show progress
- If truly frozen, close and restart the installer
- Try the manual step-by-step workflow instead
Solutions:
- Refresh your application menu (log out and back in, or restart)
- Check
~/.local/share/applications/for desktop files - Try launching from terminal to see error messages
- Read the log: The log tells you what's happening. Pay attention to it.
- Be patient: Some operations take 10-20 minutes. Don't close the installer.
- Complete one step at a time: Don't click multiple buttons simultaneously.
- Use "One-Click Full Setup" first: It's the easiest way for beginners.
- Keep installer open: Don't close the installer window until everything is done.
- Check requirements: Make sure you're on a supported Linux distribution.
If you're still having issues:
- Read the log output carefully - it often contains helpful error messages
- Check that you're on a supported distribution
- Make sure all dependencies are installed
- Try the troubleshooting steps above
- Check the main README.md for additional information
| Button | When to Use | Time |
|---|---|---|
| One-Click Full Setup | First time installation | 15-40 min |
| Setup Wine Environment | Wine not set up | 5-10 min |
| Install System Dependencies | Missing packages | 1-5 min |
| Install Winetricks Dependencies | Missing Windows components | 10-20 min |
| Download Affinity Installer | Want installer file | 2-10 min |
| Install from File Manager | Have installer file | 5-15 min |
| Update [App Name] | Update existing app | 5-15 min |
| Set Windows 11 + Renderer | OpenCL not working | 1 min |
| Fix Settings | Affinity v3 won't save settings | 2-5 min |
Last Updated: This guide covers the GUI installer as of the latest version.