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.


USE flags

It is likely for many users to desire Wine to support as much media as possible, in these cases be sure to enable the related flags.

USE flags for app-emulation/wine Free implementation of Windows(tm) on Unix

X Add support for X11 global
alsa Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture) global
capi Enable ISDN support via CAPI local
cups Add support for CUPS (Common Unix Printing System) global
custom-cflags Bypass strip-flags; use at your own peril local
d3d9 Apply highly experimental patches for Gallium Nine support. This patch may break some applications. local
dos Pull in games-emulation/dosbox to run DOS applications local
fontconfig Support for configuring and customizing font access via media-libs/fontconfig global
gecko Add support for the Gecko engine when using iexplore local
gphoto2 Add digital camera support global
gsm Add support for the gsm lossy speech compression codec global
gstreamer Use media-libs/gstreamer to provide DirectShow functionality; local
jpeg Add JPEG image support global
lcms Add lcms support (color management engine) global
ldap Add LDAP support (Lightweight Directory Access Protocol) global
mono Add support for .NET using Wine's Mono add-on local
mp3 Add support for reading mp3 files global
ncurses Add ncurses support (console display library) global
netapi Use libnetapi from net-fs/samba to support Windows networks in netapi32.dll local
nls Add Native Language Support (using gettext - GNU locale utilities) global
odbc Add ODBC Support (Open DataBase Connectivity) global
openal Add support for the Open Audio Library global
opencl Enable OpenCL support local
opengl Add support for OpenGL (3D graphics) global
osmesa Add support for OpenGL in bitmaps using libOSMesa local
oss Add support for OSS (Open Sound System) global
pcap Support packet capture software (e.g. wireshark) local
perl Install helpers written in perl (winedump/winemaker) local
pipelight Apply Wine-Staging patches for Pipelight/Silverlight support local
png Add support for libpng (PNG images) global
prelink Run prelink on DLLs during build; For versions before wine-1.7.55 or hardened, do not disable if you do not know what this means as it can break things at runtime local
pulseaudio Add support for PulseAudio sound server global
realtime Pull in sys-auth/rtkit for low-latency pulseaudio support local
run-exes Use Wine to open and run .EXE and .MSI files local
s3tc Pull in media-libs/libtxc_dxtn for DXTn texture compression, needed for many games local
samba Add support for NTLM auth. see and local
scanner Add support for scanner hardware (e.g. build the sane frontend in kdegraphics) global
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur global
ssl Add support for Secure Socket Layer connections global
staging Apply Wine-Staging patches for advanced feature support that haven't made it into upstream Wine yet local
test Workaround to pull in packages needed to run with FEATURES=test. Portage-2.1.2 handles this internally, so don't set it in make.conf/package.use anymore global
themes Support GTK+:3 window theming through Wine-Staging local
threads Add threads support for various packages. Usually pthreads global
truetype Add support for FreeType and/or FreeType2 fonts global
udev Use virtual/libudev to provide plug and play support local
udisks Enable storage management support (automounting, volume monitoring, etc) global
v4l Enable support for video4linux (using linux-headers or userspace libv4l libraries) global
vaapi Enable Video Acceleration API for hardware decoding global
xcomposite Enable support for the Xorg composite extension global
xinerama Add support for the xinerama X11 extension, which is mandatory if you work in multiple monitors setup global
xml Add support for XML files global

Environmental 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 3 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-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-9999'

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


Enable the USE flags of choice and emerge the package:

root #emerge --ask app-emulation/wine

To install the latest development version of Wine the package needs to be individually unmasked:

root #echo "app-emulation/wine" >> /etc/portage/package.accept_keywords

The above command does not apply to systems that have ~amd64 defined globally in the ACCEPT_KEYWORDS variable located in /etc/portage/make.conf


Disabling the menubuilder

To prevent Wine from adding menu entries and desktop links, the following .dll override can be used:

FILE ~/.bashrc
# Prevent Wine from adding menu entries and desktop links.
export WINEDLLOVERRIDES='winemenubuilder.exe=d'

Previously added entries can be deleted by removing the corresponding files from ~/.local/share/applications. See Wine FAQ for examples.

Tools and interfaces

Tools such as graphical interfaces for Wine can be helpful for users who want an alternative to the command-line:

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.


To create a Wine prefix in a custom location without affecting the default:

user $WINEPREFIX=~/wine_testi wineboot

The above would create the Windows installation in the home path of the user, under ~/wine_testi

Once a prefix has been created, the 'bitness' (arch) can not be changed. As such, the WINEARCH is not required to be defined for every command, unlike the WINEPREFIX variable. When using a non-default prefix without exporting it, the prefix and path need to be defined for each command.


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

user $WINEARCH=win32 WINEPREFIX=~/wine_testi wineboot

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


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


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.

Packaging Notes

Version 1.9.24 was skipped due to a lack of a staging release

Wine-Staging in >=wine-2.0

Starting with the release of =wine-2.0, the "staging" and related USE flags will not be available for stable branch wine ebuilds. This means that wine-2.0* will not have staging available, but versions >=wine-2.1 and <wine-3.0 will. Through a special arrangement with the Wine-Staging developers, staging tarballs were created for the previous stable branch, but after some discussion, it was decided to terminate this going forward because Wine-Staging, by definition and mission, is staging quality, not stable. Though Wine-Staging released a tarball for =wine-2.0, it will not be packaged, to provide consistency with the Gentoo stable packaging going forward.

Upcoming packaging changes

Soon, a rework of the wine package will be released for Gentoo which allows multiple installations in parallel. What this means for users is that if they have an application that only works on a particular version of wine, they can install that version along side any other version. Additionally, wine will be split into several packages. Currently, the intention is to have "wine-vanilla," "wine-staging," and "wine-d3d9" packages so that users can also use multiple patchsets in parallel. Management of the default wine installation will be handled with an eselect module.

See also

  • Game emulators – contains lists of game emulators available through Gentoo.

External resources