Winapps for Ubuntu

Installing and using WinApps on Ubuntu is a great way to seamlessly run Microsoft Office and other Windows applications directly from your Linux desktop.

Here is a complete guide covering installation, configuration, and troubleshooting.

What is WinApps?

WinApps is a script and set of configuration files that automates the integration of a Windows Virtual Machine (VM) or a Remote Desktop Server (RDP) with your Linux desktop. It provides:

• Desktop shortcuts and menu entries for Windows apps (like they were native apps).
• File association (e.g., double-clicking a .docx file opens in Word).
• Access to your Linux home directory (/home/youruser) from within the Windows VM.

It uses Microsoft’s official RDP protocol under the hood, making it very responsive.

---

Method 1: Installation via Script (Recommended)

This is the easiest and most common method.

Step 1: Prerequisites

Before installing WinApps, you must have the following installed and configured:

1. A Windows Virtual Machine (VM) or a Remote Desktop Server:
   • VM Option (Recommended for most users): You need a Windows 10/11 VM running in KVM/QEMU (virt-manager). The VM must be configured with VirtIO drivers for best performance and must be running when you use WinApps.
   • RDP Server Option: You can point WinApps to a physical Windows machine or server on your network that has RDP enabled.
2. Enable RDP on the Windows Machine:
   • Inside your Windows VM/machine, go to Settings -> System -> Remote Desktop.
   • Turn on “Enable Remote Desktop”.
3. Install freerdp2 and other dependencies on Ubuntu:
   Open a terminal (Ctrl+Alt+T) and run:
   bash sudo apt update sudo apt install freerdp2-x11 git

Step 2: Download WinApps

Clone the official GitHub repository:

git clone https://github.com/Fmstrat/winapps.git
cd winapps

Step 3: Configuration

This is the most critical step. You need to create a config file that tells WinApps how to connect to your Windows machine.

1. Copy the sample config file: cp winapps.conf.sample ~/.config/winapps/winapps.conf
2. Edit the config file with your text editor (e.g., nano or gedit): nano ~/.config/winapps/winapps.conf
3. Modify the following lines with your specific details: # For a local KVM VM (most common setup) RDP_USER="YourWindowsUsername" RDP_PASS="YourWindowsPassword" #RDP_DOMAIN="MYDOMAIN" # You can usually leave this commented out RDP_IP="192.168.122.123" # Replace with your VM's IP address # For a remote RDP server # RDP_IP="my.rdp.server.com" # RDP_PORT="3389" # Change if using a non-standard portHow to find your VM’s IP address?
   • Inside the Windows VM, open Command Prompt and type ipconfig. Look for the IPv4 address (often something like 192.168.122.xxx).

Step 4: Run the Installer/Checker

The installation script will test your connection and install the shortcuts.

./bin/winapps check

If everything is configured correctly, this script will:

• Successfully RDP into your Windows machine.
• Detect installed applications (like Microsoft Office).
• Automatically create .desktop files in ~/.local/share/applications for them.

You should see output indicating that apps like Microsoft Office were found.

Step 5: Using Your Apps

After a successful check:

• Log out and log back into your Ubuntu session. This refreshes the application menu.
• Search for your Windows apps in the application menu (e.g., “Word”, “Excel”). They will appear alongside your native Linux apps.
• Clicking on them will launch a seamless window for that specific application.

---

Method 2: Manual Installation (for Docker)

WinApps also supports running in a Docker container, which can be more isolated. This is less common for desktop users but good to know.

1. Install Docker: (If not already installed) sudo apt install docker.io sudo systemctl enable --now docker sudo usermod -aG docker $USER # Log out and back in for group changes to take effect.
2. Clone the repo and build: git clone https://github.com/Fmstrat/winapps.git cd winapps docker build -t winapps .
3. Create the config file (as in Step 3 above) in ~/.config/winapps/winapps.conf.
4. Run the containerized check command:
   bash docker run -it \ -v /etc/localtime:/etc/localtime:ro \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v $HOME/.config/winapps:/config \ -e DISPLAY=unix$DISPLAY \ --security-opt seccomp=unconfined \ --name winapps \ winapps \ check

---

Troubleshooting Common Issues

• “Authentication failure” or cannot connect:
  • Double-check your RDP_USER, RDP_PASS, and RDP_IP in the config file.
  • Ensure RDP is enabled on the Windows machine.
  • If using a VM, ensure the network is bridged or NAT is configured correctly so the host (Ubuntu) can reach the guest (Windows) at the IP address.
• Apps are not detected after check:
  • The automatic detection script might not find every app. You can create manual application definitions.
  • Copy a sample from the apps folder: cp apps/office-example.conf ~/.config/winapps/office.conf
  • Edit office.conf to point to the correct paths for your Office installation (e.g., C:\Program Files\Microsoft Office\root\Office16\WINWORD.EXE).
• Error: Failed to open X display or display not found:
  • You are likely running the script over SSH or without GUI access. Ensure you are running it from a terminal on your Ubuntu desktop.
• Performance is slow:
  • Ensure your KVM VM has VirtIO drivers installed for the disk and network.
  • Allocate more CPU cores and RAM to the VM if possible.
• The RDP window shows the full desktop instead of a single app:
  • This is the fallback behavior if WinApps cannot launch the specific application. Check the application path in your config file for typos.

By following these steps, you should be able to integrate Windows applications into your Ubuntu workflow seamlessly. The project’s GitHub page is an excellent resource for more advanced configurations and community support.