Install Guide Wine Docker

Install Guide: Wine in Docker 🟨

This page covers the Dockerfile in this project's repository, at Guides/Wine/Docker/Dockerfile. It builds an Ubuntu 24.04 container with Wine 11.15 (devel) and its dependencies preinstalled, as an alternative to installing Wine directly on your host system as in Install Guide: Wine.

The Dockerfile itself has no prose documentation. This page describes what the image actually does, based on building and running it directly rather than guessing from the file alone. Two real issues turned up during that testing; see Known Issues below. This page is marked in-progress because Affinity itself was not installed and launched end-to-end inside the container during this testing.

What the Dockerfile Does

1. Starts from ubuntu:24.04.
2. Enables the 32-bit (i386) architecture, and installs base packages: X11 client libraries, xvfb (a virtual framebuffer, for headless display), audio libraries, Vulkan/Mesa drivers, and general utilities like curl, wget, and cabextract.
3. Adds the WineHQ APT repository, and installs winehq-devel (Wine 11.15 at build time) and winetricks.
4. Creates a non-root user, dev, and switches to it. All later steps, and the container's default shell, run as this user.
5. Runs wineboot --init to create a WINEPREFIX at /home/dev/.affinity.
6. Runs winetricks -q remove_mono vcrun2022 dotnet48 corefonts win11 to install Affinity's runtime dependencies, the same set used in the manual guide's Step 3.
7. Downloads the same WinRT helper files used in Install Guide: Wine, Step 5 (Windows.winmd and the wintypes shim) into /tmp/affinity-helpers.
8. Writes two convenience scripts, setup_affinity_runtime.sh and run_affinity.sh, meant to copy those helper files into place once you've installed Affinity, and to launch Affinity afterward.
9. Ends with CMD ["/bin/bash"], so the container drops you at a shell rather than running anything automatically.

The image does not include an Affinity installer. You bring your own downloaded .exe, the same one used in Install Guide: Wine, Step 4, and mount it into the container.

Building the Image

From the Guides/Wine/Docker directory:

docker build -t affinity-wine .

This was tested successfully with Docker 29.7.2 on the AffinityOnLinux repository's current Dockerfile. Expect the build to take a while: the base package install and Wine/winetricks download are the bulk of it.

Running the Container

Since Affinity is a GUI application, you need to give the container access to a display. On a typical Linux desktop with X11 (including XWayland), the usual pattern is to share your host's X11 socket:

xhost +local:docker
docker run -it --rm \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
  -v "$HOME/Downloads:/home/dev/Downloads:ro" \
  affinity-wine

The Dockerfile sets DISPLAY=:0 itself, but that only works if your host's actual display also happens to be :0. Passing -e DISPLAY=$DISPLAY overrides it with the correct value for your session. The Dockerfile does not do this X11 wiring for you. It also doesn't include a VNC or noVNC server, even though it installs xvfb. On its own, xvfb gives you a virtual, invisible display, useful for headless testing of Wine commands, but not for actually seeing Affinity's window. To see the window, pair xvfb with a VNC server (not included), or forward a real X11 socket as above.

Once inside the container, you land at a bash prompt as the dev user, with $WINEPREFIX already set to /home/dev/.affinity.

Installing Affinity inside the container

Follow the same installer step as the manual guide, pointing at wherever you mounted your downloaded .exe:

wine "$HOME/Downloads/Affinity x64.exe"

Finishing WinRT setup

The Dockerfile's setup_affinity_runtime.sh script is meant to copy the pre-downloaded Windows.winmd and wintypes shim into place once Affinity is installed, and remind you to run winecfg to set the wintypes library override. As tested, this script and run_affinity.sh are both written to the image as empty (0-byte) files. See Known Issues. Until that's fixed, do this step manually instead, following Install Guide: Wine, Steps 5 through 7:

mkdir -p "$WINEPREFIX/drive_c/windows/system32/winmetadata"
cp /tmp/affinity-helpers/Windows.winmd "$WINEPREFIX/drive_c/windows/system32/winmetadata/"
cp /tmp/affinity-helpers/wintypes_shim.dll.so "$WINEPREFIX/drive_c/Program Files/Affinity/Affinity/wintypes.dll"
winecfg

Then set the wintypes library override to Native (Windows) as described in that step.

Launching Affinity

wine "$WINEPREFIX/drive_c/Program Files/Affinity/Affinity/Affinity.exe"

Troubleshooting

Nothing appears on screen when Affinity launches

Confirm you passed through a real X11 socket and DISPLAY value as shown above, rather than relying on the Dockerfile's baked-in DISPLAY=:0. If you only need to run non-interactive Wine commands (for example, to script an unattended install), prefix them with xvfb-run -a, which was confirmed working in testing: xvfb-run -a wine cmd /c ver.

Some runtime dependencies seem missing after the container builds

See the winetricks issue below. Check whether dotnet48, corefonts, and the win11 version override actually installed, by inspecting the prefix, before assuming they're present.

Known Issues

Both found through direct testing of this Dockerfile on 2026-08-21/22, with Docker 29.7.2:

• winetricks silently stops after vcrun2022 in the dependency step. The vcrun2022 component's vc_redist.x86.exe download failed its SHA256 checksum verification during testing (Microsoft has updated the file since winetricks' known hash was recorded), which made winetricks abort. Because the Dockerfile's RUN winetricks -q remove_mono vcrun2022 dotnet48 corefonts win11 || true line has || true, the Docker build step still reports success, but dotnet48, corefonts, and win11 are never actually installed. Confirmed in a built container: no mscorlib files existed anywhere under the prefix, no Windows fonts were installed, and wine cmd /c ver still reported Windows 10 (10.0.19045), not Windows 11. If you hit this, install the remaining components yourself inside the container, for example winetricks --force dotnet48 corefonts win11 (accepting or bypassing the vcrun2022 checksum mismatch as needed), the same way the manual guide's Manual Winetricks Install section works around winetricks problems.
• The two convenience scripts are written as empty files. setup_affinity_runtime.sh and run_affinity.sh are both generated in the Dockerfile using a RUN cat << 'EOF' > file ... EOF heredoc. In testing, both ended up as 0-byte files in the built image, so running either script does nothing (exits immediately with no output). Use the manual commands under Finishing WinRT setup and Launching Affinity above instead until this is fixed upstream in the Dockerfile.

Usage steps beyond what's verified above (in particular, an actual end-to-end Affinity install and launch through a forwarded display, inside the container) are not yet confirmed. Tracked on the Roadmap.

FAQ

Why use Docker instead of installing Wine directly?

The Dockerfile is useful for testing a clean Wine 10.17+/11.x environment without touching your host system, or for CI-style automated testing. For day-to-day use of Affinity, the direct Install Guide: Wine is better supported and better tested.