From Gentoo Wiki
Jump to: navigation, search

Wine (Wine Is Not an Emulator) is an application that allows Windows software to run on Linux. This article deals with installing, configuring, and maintaining a general purpose Wine environment on Gentoo.

Packaging details

As many Wine users know, there are often regressions or an application works better on one version of wine than another. Going forward, packaging in Gentoo will allow simultaneous installation of multiple versions of Wine.

Additionally, to expedite vanilla releases as well as permit multiple configurations for each Wine installation, the major patchsets have been split out into separate packages.

Quick start

For most users, worrying about the various packages and what they do should not be a concern.The split packaging and slotting is a power user feature, and most users will be OK with simply installing virtual/wine, which chooses which wine version for the user.

root #emerge --ask virtual/wine

Wine variants

  • app-emulation/wine-vanilla: upstream Wine with no external patchsets.
    (like if the old packaging forced USE="-staging -d3d9".)
  • app-emulation/wine-staging: Wine with Wine-Staging's patchset.
    (like if the old packaging forced USE="+staging -d3d9".)
  • app-emulation/wine-d3d9: Wine with Ixit's Gallium Nine patchset.
    (like if the old packaging forced USE="-staging +d3d9".)
  • app-emulation/wine-any: Wine with any of the patchsets or flags.
    (exactly like the old packaging regarding USE flags.)
    wine-any exists to allow the user to build any combination that they'd like (like the old packaging). This means the user could use wine-any to use both Wine-Staging and Gallium Nine. Alternatively, the user could use wine-any to try out another configuration from other packages. For example, the user could build wine-vanilla without PulseAudio, and could build wine-any with PulseAudio. The sky is the limit on how a user may choose to use app-emulation/wine-any.

Choosing a variant

Shouldn't I just choose wine-any, even if I'm not going to use all of its flags?
The answer to that is a resounding no. virtual/wine manages selection of of a variant in such a way as to provide the best experience to the user. Most users don't want to be dealing with external patchsets. External patchsets may introduce bugs that don't exist in the vanilla Wine release and can make using Wine more complicated for the user. External patchsets also can be released up to a week or two after vanilla wine (or each other), meaning that the period for releases can be significantly slower for those using app-emulation/wine-staging, app-emulation/wine-d3d9, or app-emulation/wine-any.
I was perfectly happy with app-emulation/wine, what should I choose?
For the least change, wine-any should do, since regarding its USE flags, it's exactly like the old packaging.
What if I want to manually choose a variant anyway? Which should I choose?
This really isn't a question that the authors of this document can answer. Typically, the logic works as follows:
  • Unless you need something more, choose app-emulation/wine-vanilla.
  • If an application requires advanced features only available in Wine-Staging, choose app-emulation/wine-staging.
  • If you do research online and find that Wine-Staging provides better performance for an application, choose app-emulation/wine-staging.
  • If you do research online and find that Gallium Nine provides better performance for an application, choose app-emulation/wine-d3d9
  • If you do research online and find that you need Wine-Staging features and Gallium Nine for an application, choose app-emulation/wine-any
  • If you have built another variant with a USE flag set and want to try an alternative flag set, like using Gstreamer on app-emulation/wine-vanilla and are wanting to use PulseAudio on the same version, choose app-emulation/wine-any in addition to the other variant choice.
I went through the trouble of choosing a variant... Why don't I see an ebuild for a particular version?
As mentioned earlier, part of the benefit of the split packaging is that some packages can be released without holding up others. A chart detailing all available versions and where in the pipeline they are can be found here.


USE flags

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

staging Enable Wine-Staging's Patchset

Not all USE flags are available on all package variants.

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

X Add support for X11
alsa Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
capi Enable ISDN support via CAPI
cups Add support for CUPS (Common Unix Printing System)
custom-cflags Bypass strip-flags; use at your own peril
d3d9 Apply highly experimental patches for Gallium Nine support. This patch may break some applications.
dos Pull in games-emulation/dosbox to run DOS applications
ffmpeg Use media-video/ffmpeg to decode WMA formats
fontconfig Support for configuring and customizing font access via media-libs/fontconfig
gecko Add support for the Gecko engine when using iexplore
gphoto2 Add digital camera support
gsm Add support for the gsm lossy speech compression codec
gssapi Use GSSAPI (Kerberos SSP support)
gstreamer Use media-libs/gstreamer to provide DirectShow functionality;
jpeg Add JPEG image support
kerberos Add kerberos support
lcms Add lcms support (color management engine)
ldap Add LDAP support (Lightweight Directory Access Protocol)
mono Add support for .NET using Wine's Mono add-on
mp3 Add support for reading mp3 files
ncurses Add ncurses support (console display library)
netapi Use libnetapi from net-fs/samba to support Windows networks in netapi32.dll
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
opengl Add support for OpenGL (3D graphics)
osmesa Add support for OpenGL in bitmaps using libOSMesa
oss Add support for OSS (Open Sound System)
pcap Support packet capture software (e.g. wireshark)
perl Install helpers written in perl (winedump/winemaker)
pipelight Apply Wine-Staging patches for Pipelight/Silverlight support
png Add support for libpng (PNG images)
prelink Run prelink on DLLs during build; For Gentoo hardened, do not disable if you do not know what this means as it can break things at runtime
pulseaudio Add support for PulseAudio sound server
realtime Pull in sys-auth/rtkit for low-latency pulseaudio support
run-exes Use Wine to open and run .EXE and .MSI files
samba Add support for NTLM auth. See: and (these pages are not currently in the updated WineHQ Wiki).
scanner Add support for scanner hardware (e.g. build the sane frontend in kdegraphics)
sdl Add support for gamepad detection using SDL
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
ssl Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
staging Apply Wine-Staging patches for advanced feature support that haven't made it into upstream Wine yet
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
themes Support GTK+:3 window theming through Wine-Staging
threads Add threads support for various packages. Usually pthreads
truetype Add support for FreeType and/or FreeType2 fonts
udev Use virtual/libudev to provide plug and play support
udisks Enable storage management support (automounting, volume monitoring, etc)
v4l Enable support for video4linux (using linux-headers or userspace libv4l libraries)
vaapi Enable Video Acceleration API for hardware decoding
vkd3d Use app-emulation/vkd3d to provide Direct3D 12 support
vulkan Enable Vulkan drivers
xcomposite Enable support for the Xorg composite extension
xinerama Add support for querying multi-monitor screen geometry through the Xinerama API
xml Add support for XML files

Users may also find information about specific USE flags required to run their applications here.

32-bit vs 64-bit

Invariably, users want to understand why they have to rebuild tons of packages to install Wine because they have to enable abi_x86_32 on a lot of Wine's dependencies... This is unavoidable, and we must highly warn against disabling abi_x86_32 and installing only with abi_x86_64 unless you really know what you are doing. Often, an application will have components that are 32-bit (or even 16-bit) and by installing Wine without 32-bit support, the user is left unable to install or launch an application. It is best to enable 32-bit support on a per-package basis, as indicated by the package manager, rather than globally.

Environment variables

Traditionally, live (9999) ebuilds support setting the repository commit as an environmental variable. This poses some issues with an ebuild that has multiple upstream repositories. To work around this issue, Wine's live ebuilds support three environmental variables for individually configuring the commit that each repository checks out. The WineHQ repository is controlled by WINE_COMMIT, Wine-Staging repository by STAGING_COMMIT, and Ixit's Gallium Nine repository by D3D9_COMMIT. The *_COMMIT variables may contain either a commit hash from that repository or a git tag from that repository.

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

root #WINE_COMMIT="wine-2.0-rc5" emerge -av '=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 #WINE_COMMIT="wine-2.0-rc5" STAGING_COMMIT="v2.0-rc5" emerge -av '=app-emulation/wine-staging-9999'

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


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


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.keywords file to allow for installation of development versions of Wine.

Here is a list of some use-flags you might have to set when compiling wine with the abi_x86_32 use-flag

media-libs/gstreamer abi_x86_32
media-plugins/gst-plugins-meta abi_x86_32
media-libs/lcms abi_x86_32
media-sound/mpg123 abi_x86_32
dev-libs/libxslt abi_x86_32
app-emulation/wine-gecko abi_x86_32
dev-libs/libgcrypt abi_x86_32
dev-libs/libgpg-error abi_x86_32
media-libs/gst-plugins-base abi_x86_32
media-libs/gst-plugins-good abi_x86_32
media-plugins/gst-plugins-a52dec abi_x86_32
media-plugins/gst-plugins-faad abi_x86_32
media-plugins/gst-plugins-dts abi_x86_32
media-libs/gst-plugins-ugly abi_x86_32
media-plugins/gst-plugins-dvdread abi_x86_32
media-plugins/gst-plugins-mpeg2dec abi_x86_32
media-plugins/gst-plugins-resindvd abi_x86_32
media-plugins/gst-plugins-flac abi_x86_32
media-plugins/gst-plugins-mpg123 abi_x86_32
media-plugins/gst-plugins-pulse abi_x86_32
media-plugins/gst-plugins-x264 abi_x86_32
media-libs/x264 abi_x86_32
media-libs/libdvdnav abi_x86_32
media-libs/libdvdread abi_x86_32
media-libs/gst-plugins-bad abi_x86_32
media-plugins/gst-plugins-gtk abi_x86_32
dev-lang/orc abi_x86_32
x11-libs/gtk+ abi_x86_32
media-libs/libepoxy abi_x86_32
x11-misc/colord abi_x86_32
app-accessibility/at-spi2-atk abi_x86_32
app-accessibility/at-spi2-core abi_x86_32
dev-libs/libgusb abi_x86_32
media-libs/libdvdcss abi_x86_32
media-libs/libmpeg2 abi_x86_32
media-libs/libdca abi_x86_32
media-libs/faad2 abi_x86_32
media-libs/a52dec abi_x86_32
media-libs/libtheora abi_x86_32
x11-libs/libXv abi_x86_32
media-plugins/gst-plugins-cdparanoia abi_x86_32
media-sound/cdparanoia abi_x86_32
virtual/libusb abi_x86_32
dev-libs/libusb abi_x86_32
virtual/libgudev abi_x86_32
dev-libs/libgudev abi_x86_32
dev-libs/libusb-compat abi_x86_32
virtual/glu abi_x86_32
media-libs/glu abi_x86_32

Another option is to simulate to install wine on an empty system and search all packages which would be installed with abi_x86_32 set. This will result in a list of all packages required based on your actual set USE flags.

export USE=abi_x86_32; emerge --color n -epv wine-${VARIANT} | grep 'ABI_X86="32' | sed -n 's/^[^]]*\] \+\([^ ]*\).*/=\1/p' | python -c "import sys,portage;[sys.stdout.write(portage.dep.Atom(line).cp+'\n') for line in sys.stdin]" |sort -u | sed -s 's/$/ abi_x86_32/'


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.


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.

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.


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.


Essential in finding out why an application is misbehaving when the basic terminal output or messages boxes are not enough. See for examples.

Configuration tools

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

Upstream FAQs

Some upstream FAQ entries that users might find useful:


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 custom-cflags USE flag should be enabled for debugging builds.

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


Users may find additional support in the #gentoo-wine channel on Freenode.

See also

  • Game emulators – Contains lists of game emulators available through Gentoo.
  • Proton (app-emulation) – Valve's compatibility tool for Steam Play based on Wine and additional components.
  • Lutris — an open source gaming platform for Linux.

External resources