Wine

This page contains changes which are not marked for translation.

Other languages:

Resources

Home

Wine (Wine Is Not an Emulator) is an application compatibility layer that allows Microsoft Windows software to run on Linux and other POSIX-compliant operating systems. This article deals with installing, configuring, and maintaining a general purpose Wine environment on Gentoo.

Wine variants

app-emulation/wine-vanilla: Upstream Wine with no external patchsets.
app-emulation/wine-staging: Wine with the Wine Staging patchset.
app-emulation/wine-proton: Wine with the Valve Software patchset.

Choosing a variant

Additional patchsets may introduce bugs that don't exist in vanilla Wine, but they may also fix others that do.

The app-emulation/wine-proton variant is only the Wine fork which is used to build Proton, and is not a stand-alone version of Proton which comes with Steam. If there are any issues with running applications with it, it would be best to test if the issues can be seen with a build of the upstream Wine as well, and then file a report to the upstream Wine project if none exists.

Installation

USE flags

USE flags for virtual/wine Virtual for Wine that supports multiple variants and slotting

`proton`	Enable Valve Software's fork of Wine
`staging`	Enable Wine-Staging's Patchset

Data provided by the Gentoo Package Database · Last update: 2022-10-12 13:43 More information about USE flags

USE flags for app-emulation/wine-vanilla Free implementation of Windows(tm) on Unix, without external patchsets

`+X`	Add support for X11
`+alsa`	Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
`+fontconfig`	Support for configuring and customizing font access via media-libs/fontconfig
`+gecko`	Enable mshtml support using app-emulation/wine-gecko
`+gstreamer`	Add support for media-libs/gstreamer (Streaming media)
`+mingw`	Build PE files using a MinGW toolchain for better compatibility
`+mono`	Enable .NET support using app-emulation/wine-mono
`+opengl`	Add support for OpenGL (3D graphics)
`+sdl`	Enable gamepad support using media-libs/libsdl2
`+ssl`	Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
`+strip`	Allow symbol stripping to be performed by the ebuild for special files
`+truetype`	Add support for FreeType and/or FreeType2 fonts
`+unwind`	Add support for call stack unwinding and function name resolution
`+vkd3d`	Enable DirectX 12 support using app-emulation/vkd3d
`+vulkan`	Add support for 3D graphics and computing via the Vulkan cross-platform API
`+xcomposite`	Enable support for the Xorg composite extension
`capi`	Enable ISDN support using net-libs/libcapi
`crossdev-mingw`	Use sys-devel/crossdev for the toolchain rather than dev-util/mingw64-toolchain (requires manual setting up)
`cups`	Add support for CUPS (Common Unix Printing System)
`custom-cflags`	Build with user-specified CFLAGS (unsupported)
`debug`	Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
`dos`	Pull in games-emulation/dosbox to run DOS applications
`ffmpeg`	Enable ffmpeg/libav-based audio/video codec support
`gphoto2`	Add digital camera support
`kerberos`	Add kerberos support
`ldap`	Add LDAP support (Lightweight Directory Access Protocol)
`llvm-libunwind`	Use sys-libs/llvm-libunwind instead of sys-libs/libunwind
`netapi`	Enable support for configuring remote shares using net-fs/samba
`nls`	Add Native Language Support (using gettext - GNU locale utilities)
`odbc`	Add ODBC Support (Open DataBase Connectivity)
`openal`	Add support for the Open Audio Library
`opencl`	Enable OpenCL support (computation on GPU)
`osmesa`	Enable off-screen rendering (OpenGL in bitmaps) support
`pcap`	Support packet capture software (e.g. wireshark)
`perl`	Install helpers that require perl (winedump/winemaker)
`pulseaudio`	Add sound server support via media-libs/libpulse (may be PulseAudio or PipeWire)
`samba`	Pull in net-fs/samba with winbind for NTLM auth support
`scanner`	Add support for scanner hardware (e.g. build the sane frontend in kdegraphics)
`selinux`	!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
`smartcard`	Enable smartcard support
`udev`	Enable virtual/udev integration (device discovery, power and storage device support, etc)
`udisks`	Enable storage management support (automounting, volume monitoring, etc)
`usb`	Add USB support to applications that have optional USB support (e.g. cups)
`v4l`	Enable support for video4linux (using linux-headers or userspace libv4l libraries)
`wayland`	Enable dev-libs/wayland backend
`wow64`	Enable running 32bit applications without 32bit ELF multilib by mapping to 64bit calls (experimental, may have worse/unusable OpenGL performance or other issues compared to USE=abi_x86_32, also lacks 16bit support) -- still need dev-util/mingw64-toolchain with abi_x86_32 which itself does not need multilib
`xinerama`	Add support for querying multi-monitor screen geometry through the Xinerama API

Data provided by the Gentoo Package Database · Last update: 2024-10-19 01:28 More information about USE flags

USE flags for app-emulation/wine-staging Free implementation of Windows(tm) on Unix, with Wine-Staging patchset

`+X`	Add support for X11
`+alsa`	Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
`+fontconfig`	Support for configuring and customizing font access via media-libs/fontconfig
`+gecko`	Enable mshtml support using app-emulation/wine-gecko
`+gstreamer`	Add support for media-libs/gstreamer (Streaming media)
`+mingw`	Build PE files using a MinGW toolchain for better compatibility
`+mono`	Enable .NET support using app-emulation/wine-mono
`+opengl`	Add support for OpenGL (3D graphics)
`+sdl`	Enable gamepad support using media-libs/libsdl2
`+ssl`	Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
`+strip`	Allow symbol stripping to be performed by the ebuild for special files
`+truetype`	Add support for FreeType and/or FreeType2 fonts
`+unwind`	Add support for call stack unwinding and function name resolution
`+vulkan`	Add support for 3D graphics and computing via the Vulkan cross-platform API
`+xcomposite`	Enable support for the Xorg composite extension
`capi`	Enable ISDN support using net-libs/libcapi
`crossdev-mingw`	Use sys-devel/crossdev for the toolchain rather than dev-util/mingw64-toolchain (requires manual setting up)
`cups`	Add support for CUPS (Common Unix Printing System)
`custom-cflags`	Build with user-specified CFLAGS (unsupported)
`dos`	Pull in games-emulation/dosbox to run DOS applications
`ffmpeg`	Enable ffmpeg/libav-based audio/video codec support
`gphoto2`	Add digital camera support
`kerberos`	Add kerberos support
`llvm-libunwind`	Use sys-libs/llvm-libunwind instead of sys-libs/libunwind
`netapi`	Enable support for configuring remote shares using net-fs/samba
`nls`	Add Native Language Support (using gettext - GNU locale utilities)
`odbc`	Add ODBC Support (Open DataBase Connectivity)
`opencl`	Enable OpenCL support (computation on GPU)
`osmesa`	Enable off-screen rendering (OpenGL in bitmaps) support
`pcap`	Support packet capture software (e.g. wireshark)
`perl`	Install helpers that require perl (winedump/winemaker)
`pulseaudio`	Add sound server support via media-libs/libpulse (may be PulseAudio or PipeWire)
`samba`	Pull in net-fs/samba with winbind for NTLM auth support
`scanner`	Add support for scanner hardware (e.g. build the sane frontend in kdegraphics)
`selinux`	!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
`smartcard`	Enable smartcard support
`udev`	Enable virtual/udev integration (device discovery, power and storage device support, etc)
`udisks`	Enable storage management support (automounting, volume monitoring, etc)
`usb`	Add USB support to applications that have optional USB support (e.g. cups)
`v4l`	Enable support for video4linux (using linux-headers or userspace libv4l libraries)
`wayland`	Enable dev-libs/wayland backend
`wow64`	Enable running 32bit applications without 32bit ELF multilib by mapping to 64bit calls (experimental, may have worse/unusable OpenGL performance or other issues compared to USE=abi_x86_32, also lacks 16bit support) -- still need dev-util/mingw64-toolchain with abi_x86_32 which itself does not need multilib
`xinerama`	Add support for querying multi-monitor screen geometry through the Xinerama API

Data provided by the Gentoo Package Database · Last update: 2024-10-19 01:28 More information about USE flags

USE flags for app-emulation/wine-proton Valve Software's fork of Wine

`+alsa`	Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
`+fontconfig`	Support for configuring and customizing font access via media-libs/fontconfig
`+gecko`	Enable mshtml support using app-emulation/wine-gecko
`+gstreamer`	Add support for media-libs/gstreamer (Streaming media)
`+mono`	Enable .NET support using app-emulation/wine-mono
`+sdl`	Enable gamepad support using media-libs/libsdl2
`+ssl`	Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
`+strip`	Allow symbol stripping to be performed by the ebuild for special files
`+unwind`	Add support for call stack unwinding and function name resolution
`+vkd3d`	Enable DirectX 12 support using app-emulation/vkd3d
`+xcomposite`	Enable support for the Xorg composite extension
`crossdev-mingw`	Use sys-devel/crossdev for the toolchain rather than dev-util/mingw64-toolchain (requires manual setting up)
`custom-cflags`	Build with user-specified CFLAGS (unsupported)
`debug`	Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
`llvm-libunwind`	Use sys-libs/llvm-libunwind instead of sys-libs/libunwind
`nls`	Add Native Language Support (using gettext - GNU locale utilities)
`openal`	Add support for the Open Audio Library
`osmesa`	Enable off-screen rendering (OpenGL in bitmaps) support
`perl`	Install helpers that require perl (winedump/winemaker)
`pulseaudio`	Add sound server support via media-libs/libpulse (may be PulseAudio or PipeWire)
`selinux`	!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
`udev`	Enable virtual/udev integration (device discovery, power and storage device support, etc)
`udisks`	Enable storage management support (automounting, volume monitoring, etc)
`usb`	Add USB support to applications that have optional USB support (e.g. cups)
`v4l`	Enable support for video4linux (using linux-headers or userspace libv4l libraries)
`wow64`	Enable running 32bit applications without 32bit ELF multilib by mapping to 64bit calls (experimental, may have worse/unusable OpenGL performance or other issues compared to USE=abi_x86_32, also lacks 16bit support) -- still need dev-util/mingw64-toolchain with abi_x86_32 which itself does not need multilib
`xinerama`	Add support for querying multi-monitor screen geometry through the Xinerama API

Data provided by the Gentoo Package Database · Last update: 2024-10-05 08:11 More information about USE flags

32-bit vs 64-bit

Note
When compiling Wine with the wow64 USE-flag on a no-multilib system, the kernel config option CONFIG_IA32_EMULATION is required for the 32bit support to function.

More often than not, Windows applications will require 32-bit support. This may be true even in the case of 64-bit applications, because they can still use a 32-bit installer.

This means that a lot of dependencies of Wine will require 32-bit support as well. If not enabled for all the packages globally, using the autounmask option with emerge can be helpful with building the list.

Compiling Wine with the wow64 USE-flag enabled will enable running 32-bit applications without building Wine and its dependencies with 32-bit support enabled, but it is (at the time of writing) more or less experimental. It does work very well with a lot of applications, but is unusable with others.

Note
Some dependencies of Wine need CONFIG_COMPAT_32BIT_TIME set in the kernel config to work. Failing to do so will generate error messages of the kind: “The futex facility returned an unexpected error code.” during build or at runtime. Affected are for example the packages dev-libs/icu^[1] and sys-devel/llvm.

Build-time environment variables

The live (9999) ebuilds support setting the repository branch, commit, commit date, and repo via the following environment variables:

EGIT_OVERRIDE_BRANCH
EGIT_OVERRIDE_COMMIT
EGIT_OVERRIDE_COMMIT_DATE
EGIT_OVERRIDE_REPO

As an example, one could select the WineHQ tag "wine-2.0-rc5" to emerge the 2.0 RC 5:

root #EGIT_OVERRIDE_COMMIT_WINE_WINE="wine-2.0-rc5" emerge -a '=app-emulation/wine-vanilla-9999'

One could additionally pin Wine Staging to the same release by finding the appropriate tag, "v2.0-rc5", and augmenting the previous as follows:

root #

EGIT_OVERRIDE_COMMIT_WINE_WINE="wine-2.0-rc5" EGIT_OVERRIDE_COMMIT_WINE_WINE_STAGING="v2.0-rc5" emerge -a '=app-emulation/wine-staging-9999'

Other variables, which affect Wine at runtime, are discussed below.

Emerge

Enable the USE flags of your choosing on the virtual and then on the variant selected (automatically by the virtual or manually by yourself) and emerge the package:

root #emerge --ask virtual/wine

or

root #emerge --ask app-emulation/wine-${VARIANT}

Only versions classified as "stable" by upstream will be stabilized in Gentoo, and only as the app-emulation/wine-vanilla variant, as external patchsets are not considered stable. Some users may opt to add Wine variants to their package.accept_keywords file to allow for installation of development versions of Wine.

Configuration

Runtime environment variables

The environment variables of the shell that wine is started from are made accessible to the Windows/DOS processes. Some very useful Wine-specific variables include, but are not limited to, WINEPREFIX, WINEARCH, and WINEDEBUG.

See the man wine and man wineserver manual entries for more detailed information concerning Wine's environment variables.

WINEPREFIX

Important
The prefix directory (by default $HOME/.wine) is generated when Wine is executed in any way (by for example, running winecfg). This also means that, if executed as the root user (see WineHQ FAQ - Should I Run Wine as Root), a Wine prefix will (by default) be generated at /root/.wine.

To create a Wine prefix in a custom location (instead of ~/.wine) without affecting the default:

user $WINEPREFIX="$HOME/.wine-someprefix" wineboot

The above would create a Wine prefix at /home/<user>/.wine-someprefix.

Note
Once a prefix has been created, the 'bitness' (arch) can not be changed. As such, the WINEARCH should be defined the when the prefix is created if the user wants to override the default. WINEARCH is meaningless beyond prefix instantiation.

WINEARCH

To create a 32-bit installation instead of the default (when built) 64-bit:

user $WINEARCH="win32" WINEPREFIX="$HOME/.wine-someprefix" wineboot

The Wine executable used could be anything that runs Wine, such as winecfg, which often makes sense while creating a clean, new prefix.

WINEARCH requires that Wine be built with the corresponding abi_x86 flags.

WINEDEBUG

Essential in finding out why an application is misbehaving when the basic terminal output or messages boxes are not enough. See https://wiki.winehq.org/Debug_Channels for examples.

Configuration tools

The following tools include graphical and command line interfaces for managing Wine prefixes:

app-emulation/q4wine – Qt5 GUI configuration tool for Wine.
app-emulation/winetricks – Easy way to install DLLs needed to work around problems in Wine.

Graphics drivers

Graphics registry value is comma seperated string and REG_SZ type.

Driver	Description
x11	Use the X11 driver
wayland	Use the Wayland driver
mac	Use the native quartz driver (default on macOS)
null	Use the null driver (a virtual screen will be created, but not displayed; available since Wine 5.2)

Default (on linux)

user $wine cmd /c "reg add HKEY_CURRENT_USER\\Software\\Wine\\Drivers /v Graphics /t REG_SZ /d x11 /f"

For enabling only experimental wayland driver:

user $wine cmd /c "reg add HKEY_CURRENT_USER\\Software\\Wine\\Drivers /v Graphics /t REG_SZ /d wayland /f"

Easy Anti Cheat Support

Due to DT_HASH not being enabled by default since glibc 2.36 then the follow needs to be applied to allow EAC games to work

FILE /etc/portage/package.use/glibc

sys-libs/glibc hash-sysv-compat

root #emerge --ask --oneshot sys-libs/glibc

Upstream FAQs

Some upstream FAQ entries that users might find useful:

Troubleshooting

When a user encounters a problem with an application, they should try the latest development version to see if the unwanted behavior still exists. If Wine has been built with options such as -fomit-frame-pointer or --hash-style=both, the Wine developers will likely be unable to help with the issue, and reports including output from such builds should not be reported to the Wine Bugzilla.

The strip USE flag should be disabled for debugging MinGW builds.

For more directions on reporting bugs, see Bugzilla and Bugs at wiki.winehq.

Support

Users may find additional support in the #gentoo-wine (webchat) channel on Libera.Chat.

External resources

Gentoo bugtracker: known bugs — Wine related bugs.
Wine Application Database — Search for the game or program to install here to see if it is stable.
Wine Staging at GitHub
WineHQ Wiki
Darling — a Darwin and macOS application comparability layer for Linux.

References

↑ Can't emerge dev-libs/icu[abi_x86_32], futex error? [SOLVED], Gentoo Forums. Retrieved on October 17th, 2020.

[1] Can't emerge dev-libs/icu[abi_x86_32], futex error? [SOLVED], Gentoo Forums. Retrieved on October 17th, 2020.

[1]