[HowTo] Install and use Wine on Debian

[CynicalDebian]

For many of us the transition from Windows to Linux can be a painful process. Proprietary Windows software hooks into your life and makes you dependent on it. Thankfully there is a way to taper off.
Thanks to Alexandre Julliard, the CodeWeavers team, and the many contributors to Wine, it is possible to run Windows programs on Linux.

Sometimes using Wine can feel like black magic, like the plague of Windows was never meant to touch this holy place. Strange bugs, crashes, and lag are all commonly seen when using Wine. WINEDEBUG output can feel like arcane runes as you struggle to understand how to run ExampleProgram.EXE.

Not all is lost, this guide is for complete Debian beginners, but veterans may find some information here useful. In this guide I will demonstrate how to install Wine correctly from Debian, how to configure Wine for use with your Windows Program, how to use Wine documentation, and I will demonstrate the running of a simple windows program.

1. What is Wine?
The name Wine is a recursive acronym for Wine is not an emulator. That's correct, it isn't an emulator, Wine converts Windows API calls to POSIX^[1] calls during runtime. You may be familiar with Virtual machines or video game console emulators, those simulate a different environment completely, making them very taxing to run on your computer. Wine has low-overhead, and sometimes it's minimalist Windows configuration actually makes Windows programs run better on Linux than they do on Windows!

This allows us to hopefully run Windows programs on Linux rather easily, but as we will soon see it is not so simple.

2. Obtaining Wine on Debian.
(Commands prefixed with # should be run as root^[2], commands prefixed with $ can be run as a regular user.)

a. Enabling Multiarch
(Assuming you are using x86_64 or x64 architecture, Wine supports other architectures but that is beyond the scope of this guide)

If you are on a 32 bit machine feel free to skip to section 2b Determining the Version of Wine to install.

If you are on a 64 bit machine you most likely want to obtain the 32 bit libraries of Wine aswell. For this you will need to enable multiarch on your system, we will verify this with Debians package management backend, dpkg^[3].

This is what we will see if we have multiarch enabled

Code: Select all

$dpkg --print-foreign-architectures 
i386

and if not we will see

Code: Select all

$dpkg --print-foreign-architectures 

To enable 32 bit architecture lets read the dpkg(1) manual.

Code: Select all

$man dpkg
...
 --add-architecture architecture
           Add architecture to the list of architectures for which packages
           can be installed without using --force-architecture (since dpkg
           1.16.2).  The architecture dpkg is built for (i.e. the output of
           --print-architecture) is always part of that list.
...
#dpkg --add-architecture i386 

Next we should update the package cache with

Code: Select all

#apt update

b. Determining the Version of Wine to install
Now we are ready to install Wine, or are we?
Wine is something that improves greatly with each new version, if you are on Debian Bullseye the Wine in the repos at the time of this was 5.0.3-3, you can check what version will be installed with..

Code: Select all

$apt policy wine
wine:
  Installed: (none)
  Candidate: 5.0.3-3
  Version table:
Packages
     5.0.3-3 500
        500 http://deb.debian.org/debian bullseye/main amd64 Packages
        500 http://deb.debian.org/debian bullseye/main i386 Packages

On a basic Debian Bullseye installation with multiarch enabled you will see something like this. As you can see the installation candidate is version 5.0.3-3. This is a good version of Wine capable of running many Windows programs. But you may be interested in a newer version of Wine...

For Wine 7.0^[4] there is some basic WoW64^[5] support. WOW64 stands for Windows 32 bit on Windows 64 bit, this is useful to us as it allows us to attempt to run 32 bit applications in a 64 bit environment, some day we may able to use Wine without using multiarch at all!

So we have two Options

i. Option 1 Installing the Bullseye version of Wine.

This can be done with

Code: Select all

#apt install wine wine64 wine32

This likely will install a lot of stuff, depending on your connection this could take awhile. Once the install is complete, lets verify our version of wine...

Code: Select all

$wine --version
wine-5.0.3 (Debian 5.0.3-3)

This is what we should see if everything went correctly!

Cool! Head to section 3, configuring Wine and optionally Winetricks
ii. Option 2 Installing the bullseye-backports version of Wine.

So you have decided you need a newer version of Wine, OK! We are going to do this with a backport^[5].

First we will need to configure our /etc/apt/sources.list file.

Code: Select all

#apt edit-sources
...
#You will need to have this line, in this situation # is the COMMENT[6] character
#Bullseye Backports
deb http://deb.debian.org/debian bullseye-backports main contrib non-free
...

Your '/etc/apt/sources.list' file changed, please run 'apt-get update'.
#apt update

[6]

Contrib and non-free are optional components^[7], but it is likely that you want to add them.


Let us verify it worked with

Code: Select all

$apt policy wine
wine:
  Installed: (none)
  Candidate: 5.0.3-3
  Version table:
 *** 7.0~repack-10~bpo11+1 100
        100 http://deb.debian.org/debian bullseye-backports/main amd64 Packages
        100 http://deb.debian.org/debian bullseye-backports/main i386 Packages
        100 /var/lib/dpkg/status
     5.0.3-3 500
        500 http://deb.debian.org/debian bullseye/main amd64 Packages
        500 http://deb.debian.org/debian bullseye/main i386 Packages

Notice the new lines for bullseye-backports?

Now it is time to install our backports
WARNING! Do not install Wine from backports with '-t' target release! This can lead to strange dependency issues with your 32 bit and 64 bit libraries! Follow the instructions of this guide.

Code: Select all

#apt install \      
wine/bullseye-backports \
wine32/bullseye-backports \   
wine64/bullseye-backports \
libwine/bullseye-backports \
libwine:i386/bullseye-backports \  
fonts-wine/bullseye-backports \
libvkd3d1/bullseye-backports \
libz-mingw-w64/bullseye-backports \
libvkd3d1:i386/bullseye-backports 

This will install lots of things and may take awhile!
Once it is complete, let us check our version of wine.

Code: Select all

$wine --version
wine-7.0 (Debian 7.0~repack-10~bpo11+1)

Alright! Now we are ready to begin using Wine!

3. Configuring Wine
Now we are ready to configure Wine to run our windows program. But we need to plan how we are going to run our Windows program in advance.

a. Environment Variables
There are three Wine environment variables that are important to us

WINEDEBUG controls how much Wine will report about what it is doing. For regular use, it is often convenient to turn it completely off.

WINEARCH controls whether we will be in a 64 or 32 bit environment, this is important for debugging, often a 32 bit environment is necessary to get a program to work. By default, it uses the architecture of the host.

WINEPREFIX controls where our psuedo windows filesystem will live. By default, it is set to $HOME/.wine

Let us configure a basic WINE environment for practice.
We can do this using the bash builtin command 'export' (winecfg will open a gui, close it by hitting (ok) or (cancel))

Code: Select all

$export WINEARCH=win64
$export WINEPREFIX=~/.wine/wine64testing
$winecfg
...
wine: configuration in L"/home/USER/.wine/wine64testing" has been updated.
...

Lets browse our new Windows filesystem.

Code: Select all

$ls ~/.wine/wine64testing
dosdevices  drive_c  system.reg  userdef.reg  user.reg
$ls ~/.wine/wine64testing/drive_c
ProgramData  'Program Files'  'Program Files (x86)'   users   windows

For those who are familiar with Windows this is likely familiar to you. Notice that we have a Program Files (x86) folder confirming we are in 64 bit environment. It is like we are in C:\

Wine does many fancy things to make this filesystem compatible with Linux, most of the concerns you could think of like case sensitivity or / vs \ file paths have already been fixed by the Wine team.

b. Issues we will run into when installing and running a Windows program

Remember, Wine intercepts API calls and changes them for POSIX, but the implementation is not perfect. The Wine team is effectively trying to make a new OS that is Windows API Compliant, it is not easy!
Often times we will see unimplemented functions, strange bugs and error messages. As lowly users without Win32 and C experience there is not much we can do about these bugs.

Most of the time these bugs are not issues in the core Win32 api but rather in proprietary libraries that programs use such as MSVC^[8] or DirectX^[9]

When we encounter these issues we can replace Wines implementation of these with our own native versions from windows to hopefully fix any issues. For example replacing Wines DirectX implementation (WineD3D), with the more bleeding edge system (DXVK) Direct X to Vulkan). Or installing Internet Explorer, and many more. There is a helper program winetricks that can help us do that, but we can also manually configure Wine to prefer the native (native as in Windows!) version of a dll^[10] rather than builtin (wine)! Using winecfg.


Determining what native libraries can be difficult by ourselves, luckily there is the very helpful Wine Application Database.
https://appdb.winehq.org/

For getting software to work, this is your biggest friend, least you can do to give back is submit test results so that others can know what your experience is like! Many of the tutorials on here will use the helper program winetricks in their examples, it is very likely you will want to install it.
b. OPTIONAL Installing winetricks
Winetricks lives in the contrib section of the repos due to its ability to pull in non-free proprietary windows dlls and libraries. If you have not configured it already you will need to add contrib to your sources.list file.

Code: Select all

#apt edit-sources
...
deb http://deb.debian.org/debian/ bullseye main contrib
....
deb http://security.debian.org/debian-security bullseye-security main contrib
...
deb http://deb.debian.org/debian/ bullseye-updates main contrib
...
Your '/etc/apt/sources.list' file changed, please run 'apt-get update'.
#apt update

Then it can be installed with

Code: Select all

#apt install winetricks

c. Security Concerns with Wine^[11]


While this meme is funny, it shows us the false sense of security Wine can give us. Wine still gives a windows program access to everything in your home directory, while file permissions will prevent it from doing anything to your OS all your data is freely readable by whatever you run. Considering you are probably running a proprietary Windows program, you have no idea what it is going to do.

Consider using a sandboxer such as firejail to sandbox wine, such a configuration is outside the scope of this guide.
An easier solution is to run things in wine as a seperate user. That is also outside the scope of this guide.

4.Running a windows program
For reference, I am using Wine 8.0 on Debian Bookworm.

Code: Select all

cynicaldebian@localhost:~$wine --version
wine-8.0 (Debian 8.0~repack-4)

Let us configure a sane wine prefix.
You may wish to keep all your games in the same wine prefix, or have each game in its separate wine prefix. If you are using a traditional desktop environment, Wine will create .desktop files that remember the wineprefix for you.
For our purposes, let us just use one wineprefix for now. Having a .wine/wine32 and a .wine/wine64 directory is a common and sane scheme.

Code: Select all

$export WINEPREFIX=~/.wine/wine64
$wine notepad

a. Running notepad
This should open the notepad program, you just ran your first windows program in Wine ^_^ Yay!



b. Running and debugging a basic Windows Program.
[WARNING] I take no responsibility for you running this proprietary windows program! It is just an example![WARNING]
For practice, you may try installing the freeware program BYOND.

First, lets read the page for it on the WINE app DB.

https://appdb.winehq.org/objectManager. ... &iId=41198

Here we see test results, and a how to guide on how to run the program.



Cool, lets obtain the program using the free download link.

Code: Select all

$wget https://www.byond.com/download/build/514/514.1589_byond.exe

Let us configure a 32 bit wine prefix for it to live in since it is what the guide told us to do.

Code: Select all

$export WINEARCH=win32
$export WINEPREFIX=~/.wine/wine32

We can now install BYOND.

Code: Select all

$wine 514.1589_byond.exe

We will see a traditional windows installer. If we set our architecture right it should install to C:\Program Files\
You can choose yes or no to launch the game, I chose no.

Code: Select all

$wine ~/.wine/wine32/Program\ Files/BYOND/byond.exe

Huhh... seems like it is getting stuck.
IF we look at the log we see this error.

Code: Select all

Could not find Wine Gecko. HTML rendering will be disabled.
0024:err:mshtml:create_document_object Failed to init Gecko, returning CLASS_E_CLASSNOTAVAILABLE

Wine Gecko is WINEs internet explorer installation, it does not come default installed with wine, but if you remember the tutorial from the Wine App DB told us we need internet explorer 8!
We can install it with

Code: Select all

$winetricks ie8

We will get some interactive menus here, it does not matter what you say but you will encounter the least issues if you refuse updates and refuse to restart. (And makes us wonder why Windows requires you to restart after installing ie8 when it works just fine on Wine?)

After that lets try running our program again.

Code: Select all

$wine ~/.wine/wine32/Program\ Files/BYOND/byond.exe
... for context 0x1
0024:err:ole:apartment_getclassobject DllGetClassObject returned error 0x80040111 for dll L"C:\\windows\\system32\\Dxtrans.dll"
0024:err:ole:com_get_class_object no class object {81397204-f51a-4571-8d7b-dc030521aabd} could be created for context 0x1
0024:err:ole:apartment_getclassobject DllGetClassObject returned error 0x80040111 for dll L"C:\\windows\\system32\\Dxtrans.dll"
0024:err:ole:com_get_class_object no class object {81397204-f51a-4571-8d7b-dc030521aabd} could be created for context 0x1
0024:err:ole:apartment_getclassobject DllGetClassObject returned error 0x80040111 for dll L"C:\\windows\\system32\\Dxtrans.dll"
0024:err:ole:com_get_class_object no class object {81397204-f51a-4571-8d7b-dc030521aabd} could be created for context 0x1
0024:err:ole:apartment_getclassobject DllGetClassObject returned error 0x80040111 for dll L"C:\\windows\\system32\\Dxtrans.dll"
0024:err:ole:com_get_class_object no class object {81397204-f51a-4571-8d7b-dc030521aabd} could be created for context 0x1
0024:err:ole:apartment_getclassobject DllGetClassObject returned error 0x80040111 for dll L"C:\\windows\\system32\\Dxtrans.dll"
0024:err:ole:com_get_class_object no class object {81397204-f51a-4571-8d7b-dc030521aabd} could be created for context 0x1
0024:err:ole:apartment_getclassobject DllGetClassObject returned error 0x80040111 for dll L"C:\\windows\\system32\\Dxtrans.dll"
0024:err:ole:com_get_class_object no class object {81397204-f51a-4571-8d7b-dc030521aabd} could be created for context 0x1
0024:err:ole:apartment_getclassobject DllGetClassObject returned error 0x80040111 for dll L"C:\\windows\\system32\\Dxtrans.dll"
0024:err:ole:com_get_class_object no class object {81397204-f51a-4571-8d7b-dc030521aabd} could be created for context 0x1
0024:err:ole:apartment_getclassobject DllGetClassObject returned error 0x80040111 for dll L"C:\\windows\\system32\\Dxtrans.dll"
0024:err:ole:com_get_class_object no class object {81397204-f51a-4571-8d7b-dc030521aabd} could be created for context 0x1
0024:err:ole:apartment_getclassobject DllGetClassObject returned error 0x80040111 for dll L"C:\\windows\\system32\\Dxtrans.dll"
0024:err:ole:com_get_class_object no class object {81397204-f51a-4571-8d7b-dc030521aabd} could be created for context 0x1
...

Wow that is a lot of errors, but nothing seems to be going wrong with our program.
We can hide these errors with

Code: Select all

$export WINEDEBUG=-all

before we run our program next time.

But we can also replace dxtrans.dll with its native version by running winetricks, but if there is no issues you should not do this no matter how scary the error messages seem, the goal of Wine is to run without using native libraries.

Code: Select all

$winetricks dxtrans

Cool huh!


5. Closing Thoughts
Wine is a very powerful program that definitely takes some time to learn. Your best is going out and trying to run some Windows programs, remember, CHECK THE WINEAPPDB before running a program. Also PLEASE, file test results! It is the easiest way to contribute to Wine and is very helpful to the next person trying to run Windows software!

This is my first HowTo guide I have written, so people. please give me scatching criticism so I can improve it! I hope you found it helpful.

--Further Reading--
The Excellent Wine Users Guide
https://wiki.winehq.org/Wine_User's_Guide
The Debian Wiki Page for Wine
https://wiki.debian.org/Wine
The WineHQ Website
https://www.winehq.org/
The WineAppDB
https://appdb.winehq.org/
-------------------------
---LINKS---
[1] https://www.opengroup.org/austin/papers/posix_faq.html
[2] https://wiki.debian.org/Root
[3] https://manpages.debian.org/bullseye/dp ... .1.en.html
[4] https://www.winehq.org/announce/7.0
[5] https://learn.microsoft.com/en-us/windo ... on-details
[6] https://en.wikipedia.org/wiki/Comment_( ... ogramming)
[7] https://wiki.debian.org/SourcesList#Component
[8]https://en.wikipedia.org/wiki/Microsoft_Visual_C%2B%2B
[9]https://en.wikipedia.org/wiki/DirectX
[10] https://en.wikipedia.org/wiki/Dynamic-link_library
[11] https://en.wikipedia.org/wiki/Wine_%28s ... 9#Security

[CwF]

Nice post CynicalDebian !

I'm curious, are newer games 64bit and it is there a use case or ability to not use multiarch support at all with condensed 64 bit only? Asking for a friend of a friend!

[CynicalDebian]

Nice post CynicalDebian !

I'm curious, are newer games 64bit and it is there a use case or ability to not use multiarch support at all with condensed 64 bit only? Asking for a friend of a friend!

Yes, exactly as you say. If you only plan to use 64 bit programs you can avoid multiarch, and some 32 bit software will be able to run entirely on WoW64 but it is rather buggy and having a fallback is always nice.

https://wiki.winehq.org/FAQ#Is_there_a_64_bit_Wine.3F

[Hallvor]

Well done, this is high quality stuff! I'll be sure to use your guide if I'll need Wine in the future. (The only thing I had a problem with, was the single line with a yellow font. It was unreadable.)

[CynicalDebian]

Well done, this is high quality stuff! I'll be sure to use your guide if I'll need Wine in the future. (The only thing I had a problem with, was the single line with a yellow font. It was unreadable.)

There is actually two lines with yellow font, I use the board theme "AcidTech" which has a dark background where many of the colors I chose appear quite well, but looking at my post on a light theme it is definitely not so good. I have changed those lines to hopefully appear more readable on a light theme.

Thank you for the comment ^_^

[alienspy]

It seems a procedure will be different for Bookworm?

https://wiki.winehq.org/Debian

[CynicalDebian]

It seems it's a procedure will be different for Bookworm?

That's for adding the wine repos, which can get you newer versions of wine.

If you are using Debian I don't recommend it and Wine 8 in stable is plenty capable

[CwF]

I'll add that the 11>12 upgrade for an install with wine works fine too.

sample size only 1 i686 image, ran and upgraded as a vm and tested on a few older computers.