https://wiki.archlinux.org/api.php?action=feedcontributions&user=Jwh7&feedformat=atomArchWiki - User contributions [en]2024-03-28T10:02:49ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=PipeWire&diff=801275PipeWire2024-02-25T18:42:49Z<p>Jwh7: /* PulseAudio clients */ Add sink/source info for setting overall or individual channel volume</p>
<hr />
<div>[[Category:Multimedia]]<br />
[[fi:PipeWire]]<br />
[[ja:PipeWire]]<br />
[[pt:PipeWire]]<br />
[[ru:PipeWire]]<br />
[[zh-hans:PipeWire]]<br />
{{Related articles start}}<br />
{{Related|PipeWire/Examples}}<br />
{{Related|WirePlumber}}<br />
{{Related articles end}}<br />
<br />
[https://pipewire.org PipeWire] is a new low-level multimedia framework. It aims to offer capture and playback for both audio and video with minimal latency and support for [[PulseAudio]], [[JACK]], [[ALSA]] and [[GStreamer]]-based applications.<br />
<br />
The daemon based on the framework can be configured to be both an audio server (with PulseAudio and JACK features) and a video capture server.<br />
<br />
PipeWire also supports containers like [[Flatpak]] and does not rely on the {{ic|audio}} and {{ic|video}} [[user group]]s. Instead, it uses a [[Polkit]]-like security model, asking Flatpak or Wayland for permission to record screen or audio.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|pipewire}} package from the official repositories. There is also {{Pkg|lib32-pipewire}} for [[multilib]] support.<br />
<br />
Pipewire uses [[systemd/User]] for management of the server and automatic socket activation.<br />
<br />
Optionally, install {{Pkg|pipewire-docs}} to review the documentation.<br />
<br />
Pipewire can work as drop-in replacement for others audio servers. See [[#Audio]] for details.<br />
<br />
=== Session manager ===<br />
<br />
Like [[JACK]], PipeWire implements no connection logic internally. The burden of watching for new streams and connect them to the appropriate output device or application is left to an external component known as a session manager.<br />
<br />
Currently, the only recommended session manager is:<br />
<br />
* {{App|[[WirePlumber]]|A more powerful manager and the current recommendation. It is based on a modular design, with Lua plugins that implement the actual management functionality.|https://pipewire.pages.freedesktop.org/wireplumber/|{{Pkg|wireplumber}}}}<br />
<br />
The following session manager is deprecated in favor of WirePlumber:<br />
<br />
* {{App|PipeWire Media Session|A very simple session manager that caters to some basic desktop use cases. It was mostly implemented for testing and as an example for building new session managers.|https://gitlab.freedesktop.org/pipewire/media-session|{{Pkg|pipewire-media-session}}}}<br />
<br />
Switch between session managers by simply installing the appropriate package, which will conflict with and replace the other option.<br />
<br />
=== GUI ===<br />
<br />
* {{App|qpwgraph|Qt-based Graph/Patchbay for PipeWire, inspired by the JACK tool QjackCtl. Saves wire sets.|https://gitlab.freedesktop.org/rncbc/qpwgraph|{{Pkg|qpwgraph}}}}<br />
* {{App|Helvum|GTK-based patchbay for PipeWire, inspired by the JACK tool ''catia''. Does not save wire sets.|https://gitlab.freedesktop.org/pipewire/helvum|{{Pkg|helvum}}}}<br />
<br />
== Configuration ==<br />
<br />
The PipeWire package provides an initial set of configuration files in {{ic|/usr/share/pipewire}}. You should not edit these files directly, as package updates will overwrite your changes. To configure PipeWire, you can copy files from {{ic|/usr/share/pipewire}} to the alternate system-wide location {{ic|/etc/pipewire}}, or to the user location {{ic|~/.config/pipewire}}. An equally named file in a directory with a higher precedence makes the analogous files ignored. [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PipeWire#configuration-file-pipewireconf]<br />
<br />
=== Profiles ===<br />
<br />
Pipewire brings a custom "Pro Audio" profile in addition to the PulseAudio profiles, selectable through pavucontrol. The effect of which is described here: https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#what-is-the-pro-audio-profile<br />
<br />
== Usage ==<br />
<br />
=== Audio ===<br />
<br />
PipeWire can be used as an audio server, similar to PulseAudio and JACK. It aims to replace both PulseAudio and JACK, by providing a PulseAudio-compatible server implementation and ABI-compatible libraries for JACK clients. See the blog post [https://blogs.gnome.org/uraeus/2020/09/04/pipewire-late-summer-update-2020/ PipeWire Late Summer Update 2020] for more information.<br />
<br />
First, install {{Pkg|pipewire-audio}}. Depending on the type of audio clients, you may also need to take some extra steps.<br />
<br />
==== ALSA clients ====<br />
<br />
Install {{Pkg|pipewire-alsa}} (and remove {{Pkg|pulseaudio-alsa}} if it was installed) to route all applications using the ALSA API through PipeWire.<br />
<br />
==== PulseAudio clients ====<br />
<br />
Install {{Pkg|pipewire-pulse}}. It will replace {{Pkg|pulseaudio}} and {{Pkg|pulseaudio-bluetooth}}. Reboot, re-login or [[stop]] {{ic|pulseaudio.service}} and [[start]] the {{ic|pipewire-pulse.service}} [[user unit]] to see the effect. <br />
<br />
Normally, no further action is needed as the user service {{ic|pipewire-pulse.socket}} should be enabled automatically by the package. To check if the replacement is working, run the following command for the ''Server Name'' and default input/output:<br />
<br />
{{hc|$ pactl info|2=<br />
...<br />
Server Name: PulseAudio (on PipeWire ''x.y.z'')<br />
...<br />
Default Sink: alsa_output.{bus}-{device}.{profile}<br />
Default Source: alsa_input.{bus}-{device}.{profile}<br />
...<br />
}}<br />
<br />
===== Setting overall or individual channel volume =====<br />
To adjust output channel volume, the ''sink'' needs to be specified using {{ic|pactl get-sink-volume {sink}}} using the value of ''Default Sink:'' (above) or ''Name:'' (below), default sink device (''@DEFAULT_SINK@''), or ''Sink #'' (e.g. ''1'' below):<br />
{{hc|$ pactl list sinks {{!}} grep -B1 -A9 State:|2=<br />
Sink #1<br />
State: RUNNING<br />
Name: alsa_output.pci-0000_2d_00.4.analog-surround-51<br />
...<br />
Driver: PipeWire<br />
...<br />
Mute: no<br />
Volume: front-left: 65536 / 100% / 0.00 dB, front-right: 65536 / 100% / 0.00 dB, rear-left: 65536 / 100% / 0.00 dB, rear-right: 65536 / 100% / 0.00 dB, front-center: 65536 / 100% / 0.00 dB, lfe: 65536 / 100% / 0.00 dB<br />
balance 0.00<br />
}}<br />
Hint: if audio is playing, {{man|1|grep}} for ''RUNNING'' as other devices will be ''SUSPENDED''.<br />
<br />
The ''balance'' ratio is calculated automatically. To set the overall volume of the default device use: {{bc|pactl set-sink-volume @DEFAULT_SINK@ 75%}}<br />
To set individual channels, provide each channel volume separately:<br />
{{bc|pactl set-sink-volume @DEFAULT_SINK@ 100% 75% 100% 75% 100% 100%}}<br />
<br />
''Source'' inputs are handled similarly. For further configuration (e.g. regarding modules) see the official upstream Wiki about [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Migrate-PulseAudio Migration from PulseAudio] and [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio Pipewire-Pulse Configuration].<br />
<br />
==== JACK clients ====<br />
<br />
Install {{Pkg|pipewire-jack}} for [[JACK]] support. There is also {{Pkg|lib32-pipewire-jack}} for [[multilib]] support.<br />
<br />
{{man|1|pw-jack}} may be used to start JACK clients, but it is technically not required, as it only serves as a wrapper around the {{ic|PIPEWIRE_REMOTE}}, {{ic|PIPEWIRE_DEBUG}} and {{ic|PIPEWIRE_LATENCY}} environment variables.<br />
<br />
It is possible to request a custom buffer size by setting a quotient of buffersize/samplerate (which equals the block latency in seconds):<br />
<br />
PIPEWIRE_LATENCY="128/48000" ''application''<br />
<br />
==== Bluetooth devices ====<br />
<br />
PipeWire handles [[Bluetooth#Audio|Bluetooth audio devices]] if the {{Pkg|pipewire-audio}} package is installed.<br />
<br />
===== Automatic profile selection =====<br />
<br />
[[WirePlumber]] has profile auto-switching enabled by default. It can automatically switch between HSP/HFP and A2DP profiles whenever an input stream is detected. You can disable it with:<br />
<br />
{{hc|/etc/wireplumber/policy.lua.d/11-bluetooth-policy.lua (or ~/.config/wireplumber/policy.lua.d/11-bluetooth-policy.lua)|output=<br />
bluetooth_policy.policy["media-role.use-headset-profile"] = false<br />
}}<br />
<br />
{{Pkg|pipewire-media-session}} has it disabled by default. You can set {{ic|bluez5.autoswitch-profile}} property to {{ic|true}} to enable it:<br />
<br />
{{hc|/etc/pipewire/media-session.d/bluez-monitor.conf (or ~/.config/pipewire/media-session.d/bluez-monitor.conf)|output=<br />
...<br />
rules = [<br />
{<br />
...<br />
actions = {<br />
update-props = {<br />
...<br />
'''bluez5.autoswitch-profile = true'''<br />
...<br />
}}<br />
<br />
==== PipeWire patch sets for command line ====<br />
<br />
{{Pkg|qpwgraph}} can be used to visualize and create connections, and also save and load patch sets.<br />
<br />
For non-GUI needs, the following are bash scripts to save wiresets, load wiresets, and dewire all connections. For saving and loading, use a command-line parameter for the filename.<br />
<br />
{{hc|pw-savewires|<nowiki><br />
#!/bin/bash<br />
<br />
if [[ "$#" -ne 1 ]]; then<br />
echo<br />
echo 'usage: pw-savewires filename'<br />
echo<br />
exit 0<br />
fi<br />
<br />
rm $1 &> /dev/null<br />
while IFS= read -r line; do<br />
link_on=`echo $line | cut -f 4 -d '"'`<br />
link_op=`echo $line | cut -f 6 -d '"'`<br />
link_in=`echo $line | cut -f 8 -d '"'`<br />
link_ip=`echo $line | cut -f 10 -d '"'`<br />
echo "Saving: " "'"$link_on:$link_op"','"$link_in:$link_ip"'"<br />
echo "'"$link_on:$link_op"','"$link_in:$link_ip"'" >> $1<br />
done < <(pw-cli dump short link)<br />
</nowiki>}}<br />
<br />
{{hc|pw-loadwires|<nowiki><br />
#!/bin/python<br />
<br />
import sys<br />
import csv<br />
import os<br />
<br />
if len(sys.argv) < 2:<br />
print('\n usage: pw-loadwires filename\n')<br />
quit()<br />
<br />
with open(sys.argv[1], newline='') as csvfile:<br />
pwwreader = csv.reader(csvfile, delimiter=',', quotechar='"')<br />
for row in pwwreader:<br />
print('Loading: ' + row[0] + ' --> ' + row[1])<br />
process = os.popen('pw-link ' + row[0] + ' ' + row[1])<br />
</nowiki>}}<br />
<br />
{{hc|pw-dewire|<nowiki><br />
#!/bin/bash<br />
while read -r line; do<br />
echo 'Dewiring: ' $line '...'<br />
pw-link -d $line<br />
done < <(pw-cli dump short link {{!}} grep -Eo '^[0-9]+')<br />
</nowiki>}}<br />
<br />
==== Sharing audio devices with computers on the network ====<br />
<br />
While PipeWire itself is not network transparent, its pulse implementation supports [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio#network-support network streaming]. An easy way to share audio between computers on the network is to use the [[Avahi]] daemon for discovery. To enable this functionality, [[install]] the {{Pkg|pipewire-zeroconf}} package.<br />
<br />
Make sure that the {{ic|avahi-daemon.service}} is running (and UDP port {{ic|5353}} is open if using a [[Avahi#Firewall|firewall]]) on all computers that will be sharing audio.<br />
<br />
{{Note|Some GUI volume managers hide network cards by default. (ex: in Plasma one has to "Configure Audio Volume..." and check "Show virtual devices".}}<br />
<br />
To share the local audio devices load the appropriate modules on the host (make sure to use the local IP address):<br />
<br />
$ pactl load-module module-native-protocol-tcp listen=''192.168.1.10''<br />
$ pactl load-module module-zeroconf-publish<br />
<br />
Then load the discovery module on the clients:<br />
<br />
$ pactl load-module module-zeroconf-discover<br />
<br />
It is also possible to load the modules automatically by creating a dedicated configuration file:<br />
<br />
{{Style|Use {{ic|context.modules}} instead of {{ic|context.exec}} as below.}}<br />
<br />
{{hc|/etc/pipewire/pipewire-pulse.conf.d/50-network-party.conf|2=<br />
context.exec = [<br />
{ path = "pactl" args = "load-module module-native-protocol-tcp" }<br />
{ path = "pactl" args = "load-module module-zeroconf-discover" }<br />
{ path = "pactl" args = "load-module module-zeroconf-publish" }<br />
]<br />
}}<br />
<br />
===== Streaming audio to an AirPlay receiver =====<br />
<br />
It is possible to stream audio to a device that is posing as an [[Wikipedia:AirPlay#Receivers|AirPlay Receiver]]. To enable this functionality, load the [https://docs.pipewire.org/page_module_raop_discover.html RAOP Discover module]: <br />
<br />
$ pactl load-module module-raop-discover<br />
<br />
It is also possible to load this module automatically by creating a dedicated configuration file:<br />
<br />
{{hc|/etc/pipewire/pipewire.conf.d/raop-discover.conf (or ~/.config/pipewire/pipewire.conf.d/raop-discover.conf)|2=<br />
context.modules = [<br />
{<br />
name = libpipewire-module-raop-discover<br />
args = { }<br />
}<br />
]<br />
}}<br />
<br />
Some speakers' AirPlay implementations (like Sonos AirPlay 2 speakers) may require opening up ports 6001 and 6002 for incoming UDP traffic on your source device.<br />
<br />
<br />
==== Run PipeWire on top of native JACK ====<br />
<br />
PipeWire can also run as a [[JACK]] client on top of the native JACK daemon if desired.<br />
<br />
See [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/JACK JACK and PipeWire (PipeWire wiki)] and [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-JACK#jack-bridge JACK Bridge (PipeWire wiki)] for more information and additional configuration (like available channels for example).<br />
<br />
To use it install the {{pkg|pipewire-jack-client}} and start JACK. Pipewire should be bridged automatically.<br />
<br />
{{Note|Since pipewire [https://gitlab.freedesktop.org/pipewire/pipewire/-/releases/0.3.81 0.3.81] loading the jackdbus module is done automatically and is no longer necessary.<br />
It can manually be loaded (as explained by {{man|1|pactl}}) like a PulseAudio module: {{ic|pactl load-module module-jackdbus-detect}} before starting jack.<br />
}}<br />
<br />
==== Use ALSA dmix devices as PipeWire sinks ====<br />
<br />
It is possible to have a PipeWire server (or multiple, for each user) output to ALSA via [[Advanced Linux Sound Architecture#Dmix|ALSA dmix devices]]. This allows you to use ALSA as the primary audio output system while being able to use non-ALSA devices such as Bluetooth headphones.<br />
<br />
===== ALSA dmix setup =====<br />
<br />
Suppose you have two cards, {{ic|PCH}} and {{ic|HDMI}}:<br />
<br />
{{hc|/proc/asound/cards|<br />
0 [PCH ]: HDA-Intel - HDA Intel PCH<br />
HDA Intel PCH at 0xdff40000 irq 146<br />
1 [HDMI ]: HDA-Intel - HDA ATI HDMI<br />
HDA ATI HDMI at 0xdfe60000 irq 147<br />
}}<br />
<br />
and your PCMs look like:<br />
<br />
{{hc|/proc/asound/pcm|<br />
00-00: ALC1220 Analog : ALC1220 Analog : playback 1 : capture 1<br />
00-02: ALC1220 Alt Analog : ALC1220 Alt Analog : capture 1<br />
01-03: HDMI 0 : HDMI 0 : playback 1<br />
01-07: HDMI 1 : HDMI 1 : playback 1<br />
01-08: HDMI 2 : HDMI 2 : playback 1<br />
01-09: HDMI 3 : HDMI 3 : playback 1<br />
01-10: HDMI 4 : HDMI 4 : playback 1<br />
01-11: HDMI 5 : HDMI 5 : playback 1<br />
}}<br />
<br />
and suppose your ALSA configuration looks something like this:<br />
<br />
{{hc|/etc/asound.conf|<br />
ctl.!default {<br />
type hw<br />
card PCH<br />
}<br />
<br />
pcm.!default {<br />
type plug<br />
slave.pcm "'''dmix:PCH,0'''"<br />
}<br />
<br />
pcm.dhdmi {<br />
type plug<br />
slave.pcm "'''dmix:HDMI,9'''"<br />
}<br />
}}<br />
<br />
In this particular example, the dmix devices would be {{ic|dmix:PCH,0}} and {{ic|dmix:HDMI,9}}.<br />
<br />
===== PipeWire dmix setup =====<br />
<br />
{{Expansion|Add {{Pkg|pipewire-media-session}} instructions.}}<br />
<br />
First of all, stop {{ic|wireplumber}} from monitoring and adding hardware ALSA devices by commenting out {{ic|alsa_monitor.enable()}}:<br />
<br />
{{hc|/etc/wireplumber/main.lua.d/90-enable-all.lua (or ~/.config/wireplumber/main.lua.d/90-enable-all.lua)|<br />
...<br />
-- Load devices<br />
'''-- alsa_monitor.enable()'''<br />
v4l2_monitor.enable()<br />
libcamera_monitor.enable()<br />
...<br />
}}<br />
<br />
Now, configure {{ic|pipewire}} to use dmix devices. The default configuration file ({{ic|/usr/share/pipewire/pipewire.conf}}) contains a [https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/0.3.59/src/daemon/pipewire.conf.in#L219-239 commented out example] which you can use as a basis.<br />
<br />
Add your own element to the {{ic|context.objects}} array:<br />
<br />
{{hc|/etc/pipewire/pipewire.conf.d/alsa-dmix.conf (or ~/.config/pipewire/pipewire.conf.d/alsa-dmix.conf)|output=<br />
context.objects = [<br />
# We do not start with dmix, but with an input device.<br />
# Do not forget to add an input device.<br />
# On a friend's Laptop, I saw Zoom having a nervous<br />
# breakdown and endlessly crying because no input device<br />
# was configured! You have been warned.<br />
{ factory = adapter<br />
args = {<br />
factory.name = api.alsa.pcm.source<br />
node.name = "alsa-mic-internal" # name of pulse device (mpv)<br />
node.description = "Mic Internal" # name of pulse device (pavucontrol)<br />
media.class = "Audio/Source"<br />
api.alsa.path = "'''hw:PCH,0'''"<br />
}<br />
}<br />
# Okay, now we add our dmix PCMs<br />
{ factory = adapter<br />
args = {<br />
factory.name = api.alsa.pcm.sink # sink for dmix<br />
node.name = "alsa-dmix-internal" # name of pulse device (mpv)<br />
node.description = "PCM Internal" # name of pulse device (pavucontrol)<br />
media.class = "Audio/Sink" # Sink for dmix<br />
api.alsa.path = "'''dmix:PCH,0'''"<br />
}<br />
}<br />
<br />
{ factory = adapter<br />
args = {<br />
factory.name = api.alsa.pcm.sink # sink for dmix<br />
node.name = "alsa-dmix-hdmi" # name of pulse device (mpv)<br />
node.description = "PCM HDMI" # name of pulse device (pavucontrol)<br />
media.class = "Audio/Sink" # Sink for dmix<br />
# remember this is a non-default dmix from /etc/asound.conf<br />
api.alsa.path = "'''dmix:HDMI,9'''"<br />
}<br />
}<br />
]<br />
}}<br />
<br />
As a user (non-root), check out the output of {{ic|wpctl status}}, and set the default input(source) and output(sink) devices to your liking with {{ic|wpctl set-default ''ID''}}. {{ic|''ID''}} is the number before sink/source names.<br />
<br />
Now, you can fully test your configuration.<br />
<br />
==== Switching between device profiles ====<br />
<br />
Some hardware audio devices, like {{ic|snd_hda_intel}}, function differently depending on which profile the device is running in. In the case of {{ic|snd_hda_intel}}, there are separate profiles for HDMI and analog output.<br />
<br />
Switching to HDMI with WirePlumber:<br />
<br />
{{hc|<br />
$ wpctl set-profile <device-ID> 3<br />
$ wpctl status<br />
|output=<br />
...<br />
├─ Sinks:<br />
│ * 53. Built-in Audio Digital Stereo (HDMI) [vol: 1.00]<br />
...<br />
}}<br />
<br />
Switching to analog with WirePlumber:<br />
<br />
{{hc|<br />
$ wpctl set-profile <device-ID> 1<br />
$ wpctl status<br />
|output=<br />
...<br />
├─ Sinks:<br />
│ * 51. Built-in Audio Analog Stereo [vol: 0.60]<br />
...<br />
}}<br />
<br />
=== WebRTC screen sharing ===<br />
<br />
Most applications used to rely on X11 for capturing the desktop (or individual applications), for example when using WebRTC in web browsers (e.g. on Google Meet). On Wayland, the screen sharing mechanism is handled through the [[XDG Desktop Portal]] and PipeWire, which enables sharing content under Wayland with fine-grained access controls.<br />
<br />
{{Tip|Test whether WebRTC screen sharing is working by using [https://mozilla.github.io/webrtc-landing/gum_test.html Mozilla's GetUserMedia WebRTC test page].}}<br />
<br />
{{Note|1={{Pkg|xdg-desktop-portal}} 1.10.0 fixed a mismatch between specification and implementation of its D-Bus interface. [https://github.com/flatpak/xdg-desktop-portal/pull/609] Hence, some clients may not work with xdg-desktop-portal 1.10.0 or newer.}}<br />
<br />
Firefox (84+) and Chromium (110+) support this method by default, while on older versions of Chromium (73+), one needs to enable [https://bugs.chromium.org/p/chromium/issues/detail?id=682122 WebRTC PipeWire support] by setting the corresponding (experimental) flag at the URL {{ic|chrome://flags/#enable-webrtc-pipewire-capturer}} or via CLI argument {{ic|1=--enable-features=WebRTCPipeWireCapturer}}.<br />
<br />
{{Pkg|obs-studio}} (27+) supports this method by using the new PipeWire capture source.<br />
<br />
=== Video ===<br />
<br />
{{Expansion|{{Pkg|pipewire-v4l2}}}}<br />
<br />
Although the software is not yet production-ready, it is safe to play around with. Most applications that rely on [[GStreamer]] to handle e.g. video streams should work out-of-the-box using the PipeWire GStreamer plugin, see [[GStreamer#PipeWire]]. Applications like e.g. {{Pkg|cheese}} are therefore already able to share video input using it.<br />
<br />
Using {{Pkg|pipewire-v4l2}}, it should also be possible to use the {{ic|pw-v4l2}} script to preload a library ({{ic|/lib/pipewire-0.3/v4l2/libpw-v4l2.so}}) that intercepts v4l2 calls and routes video through pipewire.<br />
<br />
== Audio post-processing ==<br />
<br />
=== Pipewire module-filter-chain ===<br />
<br />
Pipewire has an internal module called [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Filter-Chain filter-chain] that can create nodes to process audio input and output. See {{ic|/usr/share/pipewire/filter-chain/}} for examples including equalization, virtual surround sound, LADSPA plugins and channel mixing.<br />
<br />
==== Systemwide parametric equalization ====<br />
<br />
Copy the config file to your {{ic|.config}} folder:<br />
<br />
$ mkdir -p ~/.config/pipewire/pipewire.conf.d<br />
$ cp /usr/share/pipewire/filter-chain/sink-eq6.conf ~/.config/pipewire/pipewire.conf.d/<br />
<br />
Then edit {{ic|sink-eq6.conf}} to incorporate the desired parameters. For headphones, these can be obtained from [https://old.reddit.com/r/oratory1990/wiki/index Oratory1990's database] or, if not listed there, the [https://github.com/jaakkopasanen/AutoEq/tree/master/results/ AutoEQ project].<br />
<br />
If you require a pre-amp, modify {{ic|eq_band_1}} to apply a {{ic|bq_highshelf}} filter at frequency 0Hz with a negative gain (gains from -120 to +20dB supported):<br />
<br />
label = bq_highshelf<br />
control = { "Freq" = 0 "Q" = 1.0 "Gain" = -7.5 }<br />
<br />
For more than 6 bands, add more entries to the {{ic|nodes}} list and corresponding {{ic|links}} connecting one filter ":Out" to the next filter ":In", for instance to increase to 11 bands (preamp + 10):<br />
<br />
{ output = "eq_band_6:Out" input = "eq_band_7:In" }<br />
{ output = "eq_band_7:Out" input = "eq_band_8:In" }<br />
{ output = "eq_band_8:Out" input = "eq_band_9:In" }<br />
{ output = "eq_band_9:Out" input = "eq_band_10:In" }<br />
{ output = "eq_band_10:Out" input = "eq_band_11:In" }<br />
<br />
Restart Pipewire, select "Equalizer Sink" as your default sound output device; this should then apply to all applications.<br />
<br />
=== EasyEffects ===<br />
<br />
EasyEffects (former PulseEffects) is a GTK utility which provides a large array of audio effects and filters to individual application output streams and microphone input streams. Notable effects include an input/output equalizer, output loudness equalization and bass enhancement, input de-esser and noise reduction plug-in. See [https://github.com/wwmm/easyeffects the GitHub page] for a full list of effects.<br />
<br />
In order to use EasyEffects, install {{Pkg|easyeffects}}. See [https://github.com/wwmm/easyeffects/wiki/Community-presets Community Presets] for a collection of preset configurations. See [https://github.com/jaakkopasanen/AutoEq AutoEq] for collection of algorithmically generated EQ presets for headphones.<br />
<br />
{{Note|For PulseEffects legacy version, see [[PulseAudio#PulseEffects]].}}<br />
<br />
=== NoiseTorch ===<br />
<br />
NoiseTorch is an alternative way for noise suppression, packaged with {{AUR|noisetorch}}. There also exists {{AUR|noisetorch-git}}.<br />
<br />
After starting it the module can be loaded for the selected microphone. It is possible to adjust the voice activation threshold, which should be set to the highest level, not filtering out any actual voice.<br />
<br />
You can start audio processing with systemd automatically, see [https://github.com/noisetorch/NoiseTorch/wiki/Start-automatically-with-Systemd]. Note that the noisetorch binary path is different if installed from AUR.<br />
<br />
=== Noise suppression for voice ===<br />
<br />
[[Install]] the {{Pkg|noise-suppression-for-voice}} package.<br />
<br />
Then simply follow the instructions given on [https://github.com/werman/noise-suppression-for-voice#pipewire GitHub].<br />
<br />
=== JamesDSP ===<br />
<br />
[https://github.com/Audio4Linux/JDSP4Linux#readme JamesDSP for Linux] (available as {{AUR|jamesdsp}}) provides open-source sound effects for PipeWire and PulseAudio. It uses its own effects engine and without depending on LADSPA, Calf, etc. JamesDSP was initially published as an audio effects processor for Android devices.<br />
<br />
=== Using LADSPA, LV2 and VST plugins with PulseAudio ===<br />
<br />
{{Accuracy|Does this section relate to using the pulseaudio daemon or the pipewire's interface for pulseaudio clients?}}<br />
<br />
You can create input/output destinations to connect [[PulseAudio]] to Carla's audio plug-ins.<br />
<br />
If you want to choose between the full list of available LADSPA, LV2 and VST plugins, you can apply them using a custom Pulseaudio null sink and Carla Jack host. Install {{Pkg|pipewire-pulse}}, {{Pkg|pipewire-jack}} and {{Pkg|carla}}. At the begin, create a new PulseAudio null sink named {{ic|default_null_sink}}.<br />
<br />
pactl load-module module-null-sink object.linger=1 media.class=Audio/Sink sink_name=default_null_sink channel_map=FL,FR<br />
<br />
Start Carla through Pipewire, {{ic|pw-jack carla-rack}}. In ''Rack'' tab add whichever plugin you want. Make sure they are ''stereo'' type. You can change their order, the one on top of the list will be the first to receive the audio stream, just like in EasyEffects. Afterwards move to ''Patchbay'' tab and connect the {{ic|default_null_sink}} L/R monitors to Carla inputs, then Carla outputs to the playbacks of your desired device (speakers, earphones, HDMI, etc). Save the configuration to a local folder, i.e. {{ic|~/Documents/carla_sink_effects.carxp}}.<br />
<br />
You can test the effects while a multimedia application is reproducing audio, i.e. watching a video on a website through Firefox. There are two methods to do it. The first one, inside Carla ''Patchbay'' tab, disconnecting all Firefox connections and linking its L/R outputs to {{ic|default_null_sink}} playbacks. The second through {{Pkg|pavucontrol}}, locating Firefox audio stream and redirecting it to {{ic|default_null_sink}} (this should remember the connection to automatically redirect the application to the same sink on the next instance).<br />
<br />
To apply these settings at startup, create two systemd user service units:<br />
<br />
{{hc|~/.config/systemd/user/jack-carla-rack.service|output=<br />
[Unit]<br />
Description=Load Carla Rack JACK host<br />
<br />
[Service]<br />
PassEnvironment="PIPEWIRE_LINK_PASSIVE=true"<br />
Type=exec<br />
ExecStart=/usr/bin/pw-jack carla-rack -n<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
{{hc|~/.config/systemd/user/pulseaudio-null-sink@.service|output=<br />
[Unit]<br />
Description=Load %i Pulseaudio null sink<br />
Before=jack-carla-rack.service<br />
After=pipewire-pulse.service<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/pactl load-module module-null-sink object.linger=1 media.class=Audio/Sink sink_name=%i channel_map=FL,FR<br />
ExecStop=/usr/bin/pactl unload-module module-null-sink<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
Then override ''jack-carla-rack'' service specifying the full path of your Carla configuration at ''Environment'' directive:<br />
<br />
{{hc|~/.config/systemd/user/jack-carla-rack.service.d/override.conf|output=<br />
[Service]<br />
Environment="CARLA_CONFIG_FILE=/home/username/Documents/carla_sink_effects.carxp"<br />
ExecStart=<br />
ExecStart=/usr/bin/pw-jack carla-rack -n $CARLA_CONFIG_FILE<br />
}}<br />
<br />
At last, [[enable]] the {{ic|pulseaudio-null-sink@default_null_sink.service}} and {{ic|jack-carla-rack.service}} [[user unit]]s. <br />
<br />
Note that if you set the {{ic|default_null_sink}} as the default device in system settings, all applications will be redirected to it and the volume keys will change its level, not the one on the speakers. If you want to control volume speakers, leave them as the default in system settings and redirect your desired application to {{ic|default_null_sink}} inside pavucontrol (Pipewire compatibility layer will remember the connection on the next instance of the same application).<br />
<br />
== Troubleshooting ==<br />
<br />
{{Merge|PipeWire/Troubleshooting|This section is long enough to be split into a dedicated subpage.|section=Move Troubleshooting into a new separate page}}<br />
<br />
=== Audio ===<br />
<br />
==== Microphone is not detected by PipeWire ====<br />
<br />
PipeWire's {{ic|alsa-monitor}} module uses {{Pkg|alsa-card-profiles}} to detect devices by default. If this is not working for you, try to turn off {{ic|api.alsa.use-acp}}, or optionally turn on {{ic|api.alsa.use-ucm}}. <br />
<br />
If using {{Pkg|pipewire-media-session}}:<br />
<br />
{{hc|/etc/pipewire/media-session.d/alsa-monitor.conf (or ~/.config/pipewire/media-session.d/alsa-monitor.conf)|output=<br />
...<br />
rules = [<br />
{<br />
...<br />
actions = {<br />
update-props = {<br />
...<br />
'''api.alsa.use-acp = false'''<br />
...<br />
}}<br />
<br />
Otherwise, if using {{Pkg|wireplumber}}:<br />
<br />
{{hc|/etc/wireplumber/main.lua.d/50-alsa-config.lua (or ~/.config/wireplumber/main.lua.d/50-alsa-config.lua)|output=<br />
...<br />
alsa_monitor.rules = {<br />
{<br />
...<br />
apply_properties = {<br />
-- Use ALSA-Card-Profile devices. They use UCM or the profile<br />
-- configuration to configure the device and mixer settings.<br />
'''-- ["api.alsa.use-acp"] = true,'''<br />
<br />
-- Use UCM instead of profile when available. Can be<br />
-- disabled to skip trying to use the UCM profile.<br />
'''["api.alsa.use-ucm"] = true,'''<br />
...<br />
}}<br />
<br />
Then, restart PipeWire and check available devices:<br />
<br />
{{Out of date|Option {{ic|--list-targets}} is no longer available in the recent versions of {{ic|pw-record}}; in order to list objects use either {{ic|wpctl status}} or {{ic|pw-cli ls}} or {{ic|pw-dump}} instead.}}<br />
<br />
{{hc|$ pw-record --list-targets|2=<br />
Available targets ("*" denotes default): 62<br />
58: description="Built-in Audio" prio=1872<br />
60: description="Built-in Audio" prio=2000<br />
* 62: description="Built-in Audio (Loopback PCM)" prio=1984<br />
}}<br />
<br />
An alternative solution suggested in [https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/2332 this PipeWire issue] is to add the microphone manually. First of all, make sure the microphone is detected by ALSA.<br />
<br />
{{hc|$ arecord -l|<br />
**** List of CAPTURE Hardware Devices ****<br />
card ''card_number'': ''card_name'', device ''device_number'': ''device_name''<br />
...<br />
}}<br />
<br />
Choose your microphone from the list, and to further test the microphone, run the following commands.<br />
<br />
{{bc|1=<br />
$ arecord --duration=5 --format=dat --device=hw:''card_number'',''device_number'' test-mic.wav # record from the mic<br />
$ aplay test-mic.wav # play it<br />
}}<br />
<br />
If the microphone is working with {{ic|arecord}}, but not detected by PipeWire, try to add a config file to manually add this device.<br />
<br />
{{hc|/etc/pipewire/pipewire.conf.d/microphone.conf (or ~/.config/pipewire/pipewire.conf.d/microphone.conf)|2=<br />
context.objects = [<br />
{ factory = adapter<br />
args = {<br />
factory.name = api.alsa.pcm.source<br />
node.name = "microphone"<br />
node.description = "Undetected Microphone"<br />
media.class = "Audio/Source"<br />
api.alsa.path = "hw:''card_number'',''device_number''"<br />
}<br />
}<br />
]<br />
}}<br />
<br />
And then restart PipeWire to reload the config.<br />
<br />
==== Sound does not automatically switch when connecting a new device ====<br />
<br />
To automatically switch to newly connected devices, create this file:<br />
<br />
{{hc|/etc/pipewire/pipewire-pulse.conf.d/switch-on-connect.conf (or ~/.config/pipewire/pipewire-pulse.conf.d/switch-on-connect.conf)|output=<br />
# override for pipewire-pulse.conf file<br />
pulse.cmd = [<br />
{ cmd = "load-module" args = "module-always-sink" flags = [ ] }<br />
{ cmd = "load-module" args = "module-switch-on-connect" }<br />
]<br />
}}<br />
<br />
==== Sound does not automatically switch to Bluetooth headphones ====<br />
<br />
{{Accuracy|The linked upstream issue is specific to the xfce pulseaudio panel plugin.}}<br />
<br />
Run {{ic|pactl load-module module-switch-on-connect}} and configure your desktop environment to automatically run that command on login. You might need to execute {{ic|wpctl set-default <id>}}. The {{ic|<id>}} may be found using output of {{ic|wpctl status}}. See [https://gitlab.freedesktop.org/pipewire/wireplumber/-/issues/89 wireplumber issue #89] for more details.<br />
<br />
==== No sound after connecting to Bluetooth device ====<br />
<br />
As of 2020-12-07, if there is no sound after connecting a Bluetooth device, you might need to switch the default sink and/or move a sink input to the correct sink. Use {{ic|pactl list sinks}} to list the available sinks and {{ic|pactl set-default-sink}} to switch the default sink to the Bluetooth device. This can be automated via [[udev]] using a script similar to [https://gist.github.com/tinywrkb/04e7fd644afa9b92d33a3a99ab07ee9e this one].<br />
<br />
See this [https://www.reddit.com/r/archlinux/comments/jydd02/pipewirepulse_03164_in_testing_now_replaces/gd3m7fu/?context=3 Reddit thread] for a discussion of the issue. According to author of the script, the headset profile (HSP) might still have problems.<br />
<br />
==== Low volume ====<br />
<br />
After replacing PulseAudio with Pipewire, sound may work fine, but after a reboot, the volume becomes intolerably low.<br />
<br />
Open {{ic|alsamixer}}, use {{ic|F6}} to select the proper soundcard, and make sure the ALSA volumes are at 100%. {{ic|alsactl}} should maintain this setting after reboot.<br />
<br />
==== Increasing RLIMIT_MEMLOCK ====<br />
<br />
Dec 13 11:11:11 HOST pipewire-pulse[99999]: Failed to mlock memory 0x7f4f659d8000 32832: This is not a problem but for best performance, consider increasing RLIMIT_MEMLOCK<br />
<br />
Install {{Pkg|realtime-privileges}} and add your own user to the {{ic|realtime}} group.<br />
<br />
Alternatively, increasing memlock from 64kB to 128kB seems enough to fix this. If you are running {{ic|pipewire-pulse}} under [[systemd/User]], add:<br />
<br />
username soft memlock 64<br />
username hard memlock 128<br />
<br />
to {{ic|/etc/security/limits.d/username.conf}}<br />
<br />
==== Changing the default sample rate ====<br />
<br />
By default PipeWire sets a fixed global sample rate of 48kHz. If you need to change it (e.g. you own a DAC supporting a higher value), you can set a new default:<br />
<br />
{{hc|/etc/pipewire/pipewire.conf (or ~/.config/pipewire/pipewire.conf)|output=<br />
...<br />
context.properties = {<br />
...<br />
'''default.clock.rate = ''sample_rate'''''<br />
...<br />
}}<br />
<br />
==== Changing the allowed sample rate(s) ====<br />
<br />
PipeWire can also change dynamically the output sample rates supported by your DAC. The sample rate follows the sample rate of the audio stream being played. <br />
<br />
{{hc|/etc/pipewire/pipewire.conf (or ~/.config/pipewire/pipewire.conf)|output=<br />
...<br />
context.properties = {<br />
...<br />
'''default.clock.allowed-rates = [ ''sample_rate_1'' ''sample_rate_2'' ''sample_rate_3'' ... ]'''<br />
...<br />
}}<br />
for example, {{ic|[ 44100 48000 88200 96000 ]}}. <br />
<br />
According to [https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/1523 the developer]: "PipeWire allows up to 16 different sample rates and will switch when possible". That means, with configuration above, '''no resampling is done''' when supported. Since PipeWire [https://gitlab.freedesktop.org/pipewire/pipewire/-/releases/0.3.61#pipewire 0.3.61] up to 32 different sample rates can be configured.<br />
<br />
Consult your hardware manual for supported values of your DAC. Supported rates by the kernel driver codec are listed with the following command.<br />
<br />
$ grep -E 'Codec|Audio Output|rates' /proc/asound/card*/codec#*<br />
<br />
To check out which output sample rate are configured for a card run:<br />
<br />
$ grep rate: /proc/asound/card?/pcm??/sub?/hw_params<br />
/proc/asound/card1/pcm0p/sub0/hw_params:rate: 96000 (96000/1)<br />
<br />
In {{ic|pcm0p}} or {{ic|pcm0c}} {{ic|c}} is short for "capture" and {{ic|p}} is for "playback".<br />
<br />
$ pw-top<br />
also shows sample rate for each card and audio stream.<br />
<br />
==== Sound quality (resampling quality) ====<br />
<br />
If you used PulseAudio with {{ic|1=resample-method = speex-float-10}} or {{ic|soxr-vhq}}, then you might consider uncommenting and changing {{ic|1=resample.quality = 4}} to {{ic|10}} or the maximum {{ic|15}} in {{ic|stream.properties}} block in both {{ic|/etc/pipewire/client.conf}} and {{ic|/etc/pipewire/pipewire-pulse.conf}} (copy them from {{ic|/usr/share/pipewire/}} if they do not exist). Do not forget to [[restart]] the {{ic|pipewire.service}} and {{ic|pipewire-pulse.socket}} [[user unit]]s (never forget {{ic|pipewire-pulse.socket}} if you want your configuration changes to be applied).<br />
<br />
There is a very little quality difference between {{ic|10}} and {{ic|15}}, but the CPU load difference is 2-3x. And the latency difference between {{ic|4}}, {{ic|10}}, {{ic|15}} is yet to be investigated by anybody. {{ic|1= resample.quality = 15}} on 44100→48000 Hz on Ryzen 2600 causes {{ic|pipewire}} or {{ic|pipewire-pulse}} processes to cause 4.0% one CPU core load.<br />
<br />
You can compare resamplers here: https://src.infinitewave.ca/ (do not pay attention to anything above 18 KHz and over 120 dB). speex is listed as "Xiph.org Speex".<br />
<br />
PipeWire uses its own resampling algorithm called Spa. Like with SoX's {{ic|sox}}, Speex's {{ic|speexenc}}, PipeWire includes its standalone version: {{ic|spa-resample}}. Usage:<br />
<br />
$ spa-resample -q 15 -f s24 -r 48000 input16bit44100orAnythingElse.wav output24bit48000hz.wav<br />
<br />
It is probably somehow possible to use other resamplers by creating your own sink. Or just use a plugin in your music player (e.g., Qmmp has SoX plugin).<br />
<br />
==== External sound card not activated after reconnect ====<br />
<br />
Check {{ic|~/.config/pipewire/media-session.d/default-profile}} if there is any entry with default profile "off" and remove it. If that does not help, remove all files from {{ic|~/.config/pipewire/media-session.d/}} and [[restart]] the {{ic|pipewire.service}} [[user unit]].<br />
<br />
==== No Sound or pactl info shows Failure: Connection refused ====<br />
<br />
It means applications are unable to connect to the PipeWire-Pulse service, confirm that {{ic|/etc/pipewire/pipewire-pulse.conf}} exists and is not empty and [[restart]] the {{ic|pipewire-pulse.service}} [[user unit]].<br />
<br />
If that does not fix it, run {{ic|strace -f -o /tmp/pipe.txt pactl info}} and pastebin {{ic|/tmp/pipe.txt}} while seeking help on IRC ([ircs://irc.oftc.net/pipewire #pipewire] on OFTC) or the mailing-lists.<br />
<br />
==== Low audio quality on Bluetooth ====<br />
<br />
In case Bluetooth playback stutters, check the [[unit status]] of the {{ic|pipewire.service}} user unit for errors similar as below:<br />
<br />
Feb 17 18:23:01 HOST pipewire[249297]: (bluez_input.18:54:CF:04:00:56.a2dp-sink-60) client too slow! rate:512/48000 pos:370688 status:triggered<br />
<br />
If they appear, check the currently selected codec using {{ic|pactl list sinks}} and try changing it by setting {{ic|bluez5.codecs}} to one of {{ic|sbc aac ldac aptx aptx_hd}}. You can also try mSBC support (fixes mic on Sony 1000XM3, i.e. Headphones WH-1000XM3 and Earbuds WF-1000XM3), and the SBC-XQ codec.<br />
<br />
With {{pkg|pipewire-media-session}}:<br />
<br />
{{hc|/etc/pipewire/media-session.d/bluez-monitor.conf (or ~/.config/pipewire/media-session.d/bluez-monitor.conf)|output=<br />
...<br />
properties = {<br />
...<br />
'''bluez5.enable-msbc = true'''<br />
'''bluez5.enable-sbc-xq = true'''<br />
'''bluez5.codecs = [sbc sbc_xq]'''<br />
...<br />
}}<br />
<br />
With {{pkg|wireplumber}}:<br />
<br />
{{hc|/etc/wireplumber/bluetooth.lua.d/51-bluez-config.lua (or ~/.config/wireplumber/bluetooth.lua.d/51-bluez-config.lua)|output=<br />
bluez_monitor.properties = {<br />
["bluez5.enable-sbc-xq"] = true,<br />
["bluez5.enable-msbc"] = true,<br />
["bluez5.codecs"] = "[sbc sbc_xq]",<br />
}<br />
}}<br />
<br />
Restart PipeWire by [[restart]]ing the {{ic|pipewire.service}} user unit for the changes to take effect.<br />
<br />
==== Noticeable audio delay or audible pop/crack when starting playback ====<br />
<br />
This is caused by node suspension when inactive. <br />
<br />
With {{pkg|pipewire-media-session}}: <br />
<br />
Disable this by editing {{ic|/etc/pipewire/media-session.d/*-monitor.conf}} depending on where the delay occurs and changing property {{ic|session.suspend-timeout-seconds}} to 0 to disable or experiment with other values and see what works. <br />
<br />
Alternatively you can comment out the line {{ic|suspend-node}} in {{ic|/etc/pipewire/media-session.d/media-session.conf}}. <br />
<br />
[[Restart]] both {{ic|pipewire.service}} and {{ic|pipewire-pulse.service}} to apply these changes, or alternatively reboot.<br />
<br />
With {{pkg|wireplumber}}, create a new file to overwrite the default configuration: <br />
<br />
{{hc|~/.config/wireplumber/main.lua.d/51-disable-suspension.lua<br />
(or /etc/wireplumber/main.lua.d/51-disable-suspension.lua)|2=<br />
table.insert (alsa_monitor.rules, {<br />
matches = {<br />
{<br />
-- Matches all sources.<br />
{ "node.name", "matches", "alsa_input.*" },<br />
},<br />
{<br />
-- Matches all sinks.<br />
{ "node.name", "matches", "alsa_output.*" },<br />
},<br />
},<br />
apply_properties = {<br />
["session.suspend-timeout-seconds"] = 0, -- 0 disables suspend<br />
},<br />
})<br />
}}<br />
<br />
For bluetooth devices, use the following configuration as well (note the different file location):<br />
<br />
{{hc|~/.config/wireplumber/bluetooth.lua.d/51-disable-suspension.lua<br />
(or /etc/wireplumber/bluetooth.lua.d/51-disable-suspension.lua)|2=<br />
-- Note: bluez_monitor, not alsa_monitor<br />
table.insert (bluez_monitor.rules, {<br />
matches = {<br />
{<br />
-- Matches all sources.<br />
-- Note: bluez_input, not alsa_input<br />
{ "node.name", "matches", "bluez_input.*" },<br />
},<br />
{<br />
-- Matches all sinks.<br />
-- Note: bluez_output, not alsa_output<br />
{ "node.name", "matches", "bluez_output.*" },<br />
},<br />
},<br />
apply_properties = {<br />
["session.suspend-timeout-seconds"] = 0, -- 0 disables suspend<br />
},<br />
})<br />
}}<br />
<br />
Restart {{ic|pipewire.service}} and {{ic|wireplumber.service}} to apply changes.<br />
<br />
Instead of disabling suspension entirely, you can also change the timeout value to the desired number of seconds of delay before source suspension.<br />
<br />
==== Audio cutting out when multiple streams start playing ====<br />
<br />
This problem can typically be diagnosed by reading the [[journal]] of the {{ic|pipewire-pulse.service}} [[user unit]] and finding lines similar to:<br />
<br />
pipewire-pulse[21740]: pulse-server 0x56009b9d5de0: [Nightly] UNDERFLOW channel:0 offset:370676 underrun:940<br />
<br />
According to the [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Troubleshooting#underrununderflow-and-broken-pipe-errors official PipeWire troubleshooting guide], to solve this problem for {{pkg|pipewire-media-session}}:<br />
<br />
{{hc|/etc/pipewire/media-session.d/alsa-monitor.conf (or ~/.config/pipewire/media-session.d/alsa-monitor.conf|2=<br />
api.alsa.headroom = 1024<br />
}}<br />
<br />
With {{pkg|wireplumber}}:<br />
<br />
{{hc|/etc/wireplumber/main.lua.d/50-alsa-config.lua (or ~/.config/wireplumber/main.lua.d/50-alsa-config.lua)|2=<br />
apply_properties = {<br />
["api.alsa.headroom"] = 1024,<br />
},<br />
}}<br />
<br />
If you experience audio stuttering because of kernel page locking or late scheduling see [[Gaming#Tweaking kernel parameters for response time consistency]].<br />
<br />
==== Audio is distorted ====<br />
<br />
* For microphones, try navigating to the card that is having issues after running {{ic|alsamixer}} and use the arrow keys to reduce any "Mic Boost" or "Internal Mic Boost" options.<br />
* Follow [[#Changing the default sample rate]], reducing the sample rate to to {{ic|44100}} (44.1 kHz).<br />
<br />
==== Audio problems after standby ====<br />
<br />
If the sound is missing or otherwise garbled after waking the machine up from sleep, it might help to reinitialize ALSA:<br />
<br />
# alsactl init<br />
<br />
==== High latency with USB DACs (e.g. Schiit DACs) ====<br />
<br />
Changing sample rates or formats might help reduce latency with some DACs such as Schiit Hel 2.[https://www.reddit.com/r/osugame/comments/msifdd/usb_dacamp_and_audio_lag/]<br />
Using matching rules in ''pipewire-media-session'' we can set properties for devices.[https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-pipewire-media-session#matching-rules]<br />
<br />
Copy the default configuration file {{ic|/usr/share/pipewire/media-session.d/alsa-monitor.conf}} into either {{ic|/etc/pipewire/media-session.d/}} or {{ic|~/.config/pipewire/media-session.d/}}.<br />
Then append a new rule-block similar to the following one:<br />
<br />
{{hc|/etc/pipewire/media-session.d/alsa-monitor.conf (or ~/.config/pipewire/media-session.d/alsa-monitor.conf)|output=<br />
...<br />
rules = {<br />
...<br />
{<br />
matches = [<br />
{<br />
node.name = "alsa_output.''name-of-node''"<br />
}<br />
]<br />
actions = {<br />
update-props = {<br />
audio.format = "S24_3LE"<br />
audio.rate = 96000<br />
# Following value should be doubled until audio does not cut out or other issues stop occurring<br />
api.alsa.period-size = 128<br />
...<br />
}}<br />
<br />
{{ic|alsa_output.''name-of-node''}} node can be obtained using {{ic|pw-top}}.<br />
<br />
Your DAC might support a different format or sample rate. You can check what your DAC supports by querying [[ALSA]]:<br />
<br />
First get the card number of your DAC:<br />
<br />
{{hc|$ aplay -l|<br />
...<br />
card 3: S2 [Schiit Hel 2], device 0: USB Audio [USB Audio]<br />
Subdevices: 0/1<br />
Subdevice #0: subdevice #0<br />
...<br />
}}<br />
<br />
So in this example it would be card 3.<br />
Get all supported sample rates and formats:<br />
<br />
{{hc|$ cat /proc/asound/card''X''/stream''X''|<br />
...<br />
Playback:<br />
...<br />
Interface 1<br />
Altset 1<br />
Format: S16_LE<br />
Channels: 2<br />
Endpoint: 0x05 (5 OUT) (ASYNC)<br />
Rates: 44100, 48000, 88200, 96000, 176400, 192000, 352800, 384000<br />
Data packet interval: 125 us<br />
Bits: 16<br />
...<br />
Interface 1<br />
Altset 2<br />
Format: S24_3LE<br />
Channels: 2<br />
Endpoint: 0x05 (5 OUT) (ASYNC)<br />
Rates: 44100, 48000, 88200, 96000, 176400, 192000, 352800, 384000<br />
Data packet interval: 125 us<br />
Bits: 24<br />
...<br />
Interface 1<br />
Altset 3<br />
Format: S32_LE<br />
Channels: 2<br />
Endpoint: 0x05 (5 OUT) (ASYNC)<br />
Rates: 44100, 48000, 88200, 96000, 176400, 192000, 352800, 384000<br />
Data packet interval: 125 us<br />
Bits: 32<br />
...<br />
...<br />
}}<br />
<br />
In this case {{ic|S16_LE, S24_3LE, S32_LE}} are the supported formats and {{ic|44100, 48000, 88200, 96000, 176400, 192000, 352800, 384000}} are the supported sample rates across all formats.<br />
<br />
==== No sound from USB DAC until 30% volume ====<br />
<br />
{{Expansion|Add {{Pkg|pipewire-media-session}} instructions.}}<br />
<br />
Some USB DACs will have no sound output until a certain level of volume is reached [https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/1117]. Typically this is around 25% - 30% which then leads to an uncomfortably loud initial volume and the inability to maintain a low volume. The solution is to ignore hardware mixer volume control by setting {{ic|["api.alsa.soft-mixer"]}} to {{ic|true}}.<br />
<br />
To achieve this with {{Pkg|wireplumber}}, you can add onto the {{ic|/usr/share/wireplumber/main.lua.d/50-alsa-config.lua}} configuration by adding a configuration fragment using {{ic|table.insert}}:<br />
<br />
{{hc|~/.config/wireplumber/main.lua.d/51-volume-fix.lua|output=<br />
<br />
table.insert (alsa_monitor.rules, {<br />
matches = {<br />
{<br />
-- This matches all cards.<br />
{ "device.name", "matches", "alsa_card.*" },<br />
},<br />
},<br />
-- Apply properties on the matched object.<br />
apply_properties = {<br />
-- Do not use the hardware mixer for volume control. It<br />
-- will only use software volume. The mixer is still used<br />
-- to mute unused paths based on the selected port.<br />
["api.alsa.soft-mixer"] = true,<br />
}<br />
})<br />
}}<br />
<br />
Then, restart pipewire. Set your master volume in {{ic|alsamixer}} and then save the settings with {{ic|# alsactl store}}. You should now be able to use your volume mixer as normal.<br />
<br />
==== Realtime audio does not work ====<br />
<br />
If {{ic|RTKit error: org.freedesktop.DBus.Error.AccessDenied}} shows up in the [[unit status|status]] of the {{ic|pipewire.service}} [[user unit]], then the priority of the pipewire daemon was not changed to realtime. See [https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/1069] for this issue.<br />
<br />
==== Simultaneous output to multiple sinks on the same sound card ====<br />
<br />
Create a copy of {{ic|/usr/share/alsa-card-profile/mixer/profile-sets/default.conf}} so that changes persist across updates. Here we define a profile joining the two default mappings for Analog and HDMI.<br />
<br />
{{hc|/usr/share/alsa-card-profile/mixer/profile-sets/multiple.conf|2=<br />
[General]<br />
auto-profiles = no<br />
<br />
[Mapping analog-stereo]<br />
device-strings = front:%f<br />
channel-map = left,right<br />
paths-output = analog-output analog-output-lineout analog-output-speaker analog-output-headphones analog-output-headphones-2<br />
paths-input = analog-input-front-mic analog-input-rear-mic analog-input-internal-mic analog-input-dock-mic analog-input analog-input-mic analog-input-linein analog-input-aux analog-input-video analog-input-tvtuner analog-input-fm analog-input-mic-line analog-input-headphone-mic analog-input-headset-mic<br />
priority = 15<br />
<br />
[Mapping hdmi-stereo]<br />
description = Digital Stereo (HDMI)<br />
device-strings = hdmi:%f<br />
paths-output = hdmi-output-0<br />
channel-map = left,right<br />
priority = 9<br />
direction = output<br />
<br />
[Profile multiple]<br />
description = Analog Stereo Duplex + Digital Stereo (HDMI) Output<br />
output-mappings = analog-stereo hdmi-stereo<br />
input-mappings = analog-stereo<br />
}}<br />
<br />
Now we configure PipeWire's media-session to use the new card-profile for matching devices. Identifying information can be found using {{ic|$ pw-cli dump device}}.<br />
<br />
{{hc|/etc/pipewire/media-session.d/alsa-monitor.conf|2=<br />
rules = [<br />
{<br />
matches = [ { alsa.card_name = "HDA Intel PCH" } ]<br />
actions = {<br />
update-props = {<br />
api.alsa.use-acp = true<br />
device.profile-set = "multiple.conf"<br />
device.profile = "multiple"<br />
api.acp.auto-profile = false<br />
api.acp.auto-port = false<br />
}<br />
}<br />
}<br />
]<br />
}}<br />
<br />
==== No notification sounds from Discord ====<br />
<br />
This might cause by having the min.quantum too low, try setting it to more than 700. You can make an override for Discord specifically by appending the following rule to the pulse.rules section of pipewire-pulse.conf.<br />
<br />
{{hc|/etc/pipewire/pipewire-pulse.conf (or ~/.config/pipewire/pipewire-pulse.conf)|output=<br />
...<br />
pulse.rules = [<br />
...<br />
{<br />
# Discord notification sounds fix<br />
matches = [ { application.process.binary = "Discord" } ]<br />
actions = {<br />
update-props = {<br />
pulse.min.quantum = 1024/48000 # 21ms<br />
}<br />
}<br />
}<br />
...<br />
}}<br />
<br />
==== FMOD games crashing under PipeWire ====<br />
<br />
Some games that use an old version of the [[Wikipedia:FMOD|FMOD audio engine]], like [[Wikipedia:Pillars_of_Eternity|Pillars of Eternity]], invoke {{ic|pulseaudio --check}} and crash if the PulseAudio binary is not present. A workaround is to symlink {{ic|/bin/pulseaudio}} to {{ic|/bin/true}}.[https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/1514]<br />
<br />
# ln -s /bin/true /bin/pulseaudio<br />
<br />
Note that if you wish to reinstall PulseAudio, you need to remove the symlink.<br />
<br />
==== Auto-switching is not working ====<br />
<br />
If auto-switching is not working it may be an issue with [[WirePlumber]] state. As suggested by [https://gitlab.freedesktop.org/pipewire/wireplumber/-/issues/191#note_1252549 this comment] you can delete [[WirePlumber]]'s local state and restart the daemon to see if that helps:<br />
<br />
$ rm -r ~/.local/state/wireplumber/<br />
<br />
Then [[restart]] the {{ic|wireplumber.service}} [[user unit]].<br />
<br />
==== Missing realtime priority/crackling under load after suspend ====<br />
<br />
Due to a [https://github.com/heftig/rtkit/issues/13 bug from 2011] in rtkit, suspend events cause PipeWire's realtime priority to be revoked and not restored. To disable the protection which causes this, [[edit]] {{ic|rtkit-daemon.service}}:<br />
<br />
{{hc|/etc/systemd/system/rtkit-daemon.service.d/override.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/lib/rtkit-daemon --no-canary<br />
}}<br />
<br />
Then restart the {{ic|rtkit-daemon.service}} unit and {{ic|pipewire.service}} user unit, along with the media session service.<br />
<br />
==== No sound during streaming to RAOP devices (Sonos etc.) ====<br />
<br />
Set up mDNS hostname resolution using either [[Avahi]] or [[systemd-resolved]].<br />
<br />
=== Video ===<br />
<br />
==== OBS (etc.) display nothing, even if they ask for a window/screen ====<br />
<br />
If you are sure that you have {{Pkg|xdg-desktop-portal}} installed as well as either {{Pkg|xdg-desktop-portal-gtk}} or {{Pkg|xdg-desktop-portal-kde}}, check the running state of the daemons.<br />
<br />
In OBS, if everything is working, you should see this in {{ic|stdout}}:<br />
<br />
...<br />
info: [pipewire] desktop selected, setting up screencast<br />
info: [pipewire] created stream 0x5632d7456850<br />
info: [pipewire] playing stream…<br />
<br />
For multi-monitor setups the {{Pkg|slurp}} package will allow to capture of all the screens.<br />
<br />
== See also ==<br />
<br />
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home Wiki] — PipeWire Wiki on Freedesktop GitLab<br />
* [https://blogs.gnome.org/uraeus/2018/01/26/an-update-on-pipewire-the-multimedia-revolution-an-update/ Pipewire Update Blog Post] — Blog post from January 2018 outlining the state of PipeWire at the time<br />
* [https://blogs.gnome.org/uraeus/2020/09/04/pipewire-late-summer-update-2020/ PipeWire Late Summer Update 2020] — Blog post from September 2020</div>Jwh7https://wiki.archlinux.org/index.php?title=Activating_numlock_on_bootup&diff=790881Activating numlock on bootup2023-10-24T13:14:45Z<p>Jwh7: /* Extending getty@.service */ add note for directory creation</p>
<hr />
<div>[[Category:Boot process]]<br />
[[Category:Keyboards]]<br />
[[de:Numlock]]<br />
[[es:Activating numlock on bootup]]<br />
[[ja:起動時に Numlock を有効化]]<br />
[[pt:Activating numlock on bootup]]<br />
[[ru:Activating numlock on bootup]]<br />
[[zh-hans:Activating numlock on bootup]]<br />
== Console ==<br />
<br />
=== Early bootup (mkinitcpio) ===<br />
<br />
You can enable numlock right after the kernel boots in the [[initramfs]]. This is the only way to ensure numlock is on even during [[dm-crypt/Encrypting an entire system|full-disk encryption]] password entry. Install {{AUR|mkinitcpio-numlock}} and add the {{ic|numlock}} [[mkinitcpio]] hook before {{ic|encrypt}} in the {{ic|/etc/mkinitcpio.conf}} HOOKS array:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
...<br />
HOOKS=(base udev autodetect keyboard keymap consolefont '''numlock''' modconf block encrypt lvm2 filesystems fsck)<br />
...<br />
}}<br />
<br />
Then [[regenerate the initramfs]] for the change to take effect.<br />
<br />
An advantage of using this method is that the numlock setting will be replicated in the later boot process, and new virtual consoles will default to having numlock on.<br />
<br />
=== With systemd service ===<br />
<br />
{{Tip|These steps can be automated by [[install]]ing the {{AUR|systemd-numlockontty}} package and [[enabling]] the {{ic|numLockOnTty}} service.}}<br />
<br />
First create a script to set the numlock on relevant TTYs:<br />
<br />
{{hc|/usr/local/bin/numlock|<br />
#!/bin/bash<br />
<br />
for tty in /dev/tty{1..6}<br />
do<br />
/usr/bin/setleds -D +num < "$tty";<br />
done<br />
}}<br />
<br />
Once the script is created, you will need to make it [[executable]]. Otherwise the script cannot run.<br />
<br />
Then create and [[enable]] a systemd service:<br />
<br />
{{hc|/etc/systemd/system/numlock.service|2=<br />
[Unit]<br />
Description=numlock<br />
<br />
[Service]<br />
ExecStart=/usr/local/bin/numlock<br />
StandardInput=tty<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
=== Extending getty@.service ===<br />
<br />
This is simpler than using a separate service and does not hardcode the number of VTs in a script. Create a [[drop-in snippet]] for {{ic|getty@.service}} (note: create that directory if needed) which are applied on top of the original unit:<br />
<br />
{{hc|/etc/systemd/system/getty@.service.d/activate-numlock.conf|2=<br />
[Service]<br />
ExecStartPre=/bin/sh -c 'setleds -D +num < /dev/%I'<br />
}}<br />
<br />
{{Note|If you experience any problems, try replacing {{ic|ExecStartPre}} with {{ic|ExecStartPost}}, and/or disabling the hint as described below.}}<br />
<br />
To disable the numlock activation hint displaying on the login screen, [[edit]] {{ic|getty@tty1.service}} and add {{ic|--nohints}} to ''agetty'' options:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=-/sbin/agetty '-p -- \\u' --nohints --noclear %I $TERM<br />
<br />
=== Bash alternative ===<br />
<br />
Add {{ic|setleds -D +num}} to {{ic|~/.bash_profile}}. Note that, unlike the other methods, this will not take effect until after you log in.<br />
<br />
== X.org ==<br />
<br />
Various methods are available.<br />
<br />
=== startx ===<br />
<br />
Install the {{Pkg|numlockx}} package and add it to the [[xinitrc]] file before any {{ic|exec}} statement:<br />
<br />
{{hc|~/.xinitrc|2=<br />
numlockx &<br />
exec ''window manager''<br />
}}<br />
<br />
=== MATE ===<br />
<br />
By default, MATE saves the last state on logout and restores it during the next login. To enable numlock on every login, you must change the following [[dconf]] properties:<br />
<br />
$ dconf write org.mate.peripherals-keyboard remember-numlock-state false<br />
$ dconf write org.mate.peripherals-keyboard numlock-state 'on'<br />
<br />
=== KDE Plasma ===<br />
<br />
Go to ''System Settings > Input Devices > Keyboard'', in the ''Hardware'' tab, in the ''NumLock on Plasma Startup'' section, choose the desired NumLock behavior.<br />
<br />
=== GDM ===<br />
<br />
{{Note|GDM does not execute scripts in {{ic|/etc/gdm/Init}} anymore.}}<br />
<br />
Make sure that you have {{Pkg|numlockx}} installed then add the following code to [[xprofile|~/.xprofile]]:<br />
<br />
if [ -x /usr/bin/numlockx ]; then<br />
/usr/bin/numlockx on<br />
fi<br />
<br />
=== GNOME ===<br />
<br />
Run the following command:<br />
<br />
$ gsettings set org.gnome.desktop.peripherals.keyboard numlock-state true<br />
<br />
In order to remember last state of numlock key (whether you disabled or enabled), use:<br />
<br />
$ gsettings set org.gnome.desktop.peripherals.keyboard remember-numlock-state true<br />
<br />
Alternatively, you can use add {{ic|numlockx on}} (from {{pkg|numlockx}}) to a startup script or {{ic|~/.profile}}.<br />
<br />
=== Xfce ===<br />
<br />
In the file {{ic|~/.config/xfce4/xfconf/xfce-perchannel-xml/keyboards.xml}}, make sure the following values are set to true:<br />
<br />
<property name="Numlock" type="bool" value="true"/><br />
<property name="RestoreNumlock" type="bool" value="true"/><br />
<br />
{{Note|If the file does not exist then open ''Settings > Keyboard'', then check and uncheck the ''Restore num lock state on startup''. This will create the {{ic|keyboards.xml}} file.}}<br />
<br />
=== SDDM ===<br />
<br />
In the file {{ic|/etc/sddm.conf}}, under the {{ic|[General]}} section, set ''Numlock'' value to ''on'' :<br />
<br />
[General]<br />
...<br />
Numlock=on<br />
<br />
=== SLiM ===<br />
<br />
In the file {{ic|/etc/slim.conf}}, find the line and uncomment it (remove the {{Ic|#}}):<br />
<br />
#numlock on<br />
<br />
=== OpenBox ===<br />
<br />
In the file {{ic|~/.config/openbox/autostart}}, add the line:<br />
<br />
numlockx &<br />
<br />
And then save the file.<br />
<br />
=== LightDM ===<br />
<br />
See [[LightDM#NumLock on by default]].<br />
<br />
=== LXDM ===<br />
<br />
Set the option in {{ic|/etc/lxdm/lxdm.conf}}:<br />
<br />
numlock=1<br />
<br />
=== LXQt ===<br />
<br />
Set the option in {{ic|~/.config/lxqt/session.conf}}:<br />
<br />
[Keyboard]<br />
numlock=true<br />
<br />
== Wayland ==<br />
<br />
=== Sway ===<br />
<br />
See [[Sway#Initially enable CapsLock/NumLock]].</div>Jwh7https://wiki.archlinux.org/index.php?title=Mkinitcpio&diff=754953Mkinitcpio2022-10-28T00:49:25Z<p>Jwh7: /* COMPRESSION_OPTIONS */ mention RAM limitations for decompression</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Initramfs]]<br />
[[Category:Kernel]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[de:Mkinitcpio]]<br />
[[fr:Mkinitcpio]]<br />
[[ja:Mkinitcpio]]<br />
[[pt:Mkinitcpio]]<br />
[[ru:Mkinitcpio]]<br />
[[zh-hans:Mkinitcpio]]<br />
{{Related articles start}}<br />
{{Related|Booster}}<br />
{{Related|Boot debugging}}<br />
{{Related|dracut}}<br />
{{Related|Kernel modules}}<br />
{{Related|mkinitcpio/Minimal initramfs}}<br />
{{Related|systemd}}<br />
{{Related articles end}}<br />
[https://github.com/archlinux/mkinitcpio mkinitcpio] is a Bash script used to create an [[Wikipedia:Initial ramdisk|initial ramdisk]] environment. From the {{man|8|mkinitcpio}} man page:<br />
<br />
:The initial ramdisk is in essence a very small environment (early userspace) which loads various kernel modules and sets up necessary things before handing over control to {{ic|init}}. This makes it possible to have, for example, encrypted root file systems and root file systems on a software RAID array. ''mkinitcpio'' allows for easy extension with custom hooks, has autodetection at runtime, and many other features.<br />
<br />
Traditionally, the kernel was responsible for all hardware detection and initialization tasks early in the [[boot process]] before mounting the root file system and passing control to {{ic|init}}. However, as technology advances, these tasks have become increasingly complex. <br />
<br />
Nowadays, the root file system may be on a wide range of hardware, from SCSI to SATA to USB drives, controlled by a variety of drive controllers from different manufacturers. Additionally, the root file system may be encrypted or compressed; within a software RAID array or a logical volume group. The simple way to handle that complexity is to pass management into userspace: an initial ramdisk. See also: [https://web.archive.org/web/20150430223035/http://archlinux.me/brain0/2010/02/13/early-userspace-in-arch-linux/ /dev/brain0 » Blog Archive » Early Userspace in Arch Linux].<br />
<br />
''mkinitcpio'' has been developed by the Arch Linux developers and from community contributions. See the [https://github.com/archlinux/mkinitcpio public Git repository].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mkinitcpio}} package, which is a dependency of the {{Pkg|linux}} package, so most users will already have it installed.<br />
<br />
Advanced users may wish to install the latest development version of ''mkinitcpio'' from Git with the {{AUR|mkinitcpio-git}} package.<br />
<br />
{{Note|It is '''highly''' recommended that you follow the [https://lists.archlinux.org/mailman3/lists/arch-projects.lists.archlinux.org/ arch-projects mailing list] if you use ''mkinitcpio'' from Git!}}<br />
<br />
== Image creation and activation ==<br />
<br />
=== Automated generation ===<br />
<br />
Every time a kernel is installed or upgraded, a [[pacman hook]] automatically generates a ''.preset'' file saved in {{ic|/etc/mkinitcpio.d/}}. For example {{ic|linux.preset}} for the official stable {{Pkg|linux}} kernel package. A preset is simply a list of information required to create initial ramdisk images, instead of manually specifying the various parameters and the location of the output files.<br />
By default, it contains the instructions to create two images:<br />
<br />
# the ''default'' ramdisk image created following the directives specified in the mkinitcpio [[#Configuration]], and<br />
# the ''fallback'' ramdisk image, same as above except that the ''autodetect'' hook is skipped during creation, thus including a full range of modules which supports most systems.<br />
<br />
After creating the preset, the pacman hook calls the ''mkinitcpio'' script which generates the two images, using the information provided in the preset.<br />
<br />
{{Note|''.preset'' files are used to automatically regenerate the initramfs after a kernel update; be careful when editing them.}}<br />
<br />
=== Manual generation ===<br />
<br />
To run the script manually, refer to the {{man|8|mkinitcpio}} manual page for instructions. In particular, to (re-)generate the preset provided by a kernel package, use the {{ic|-p}}/{{ic|--preset}} option followed by the preset to utilize. For example, for the {{Pkg|linux}} package, use the command:<br />
<br />
# mkinitcpio -p linux<br />
<br />
To (re-)generate all existing presets, use the {{ic|-P}}/{{ic|--allpresets}} switch. This is typically used to regenerate all the initramfs images after a change of the global [[#Configuration]]:<br />
<br />
# mkinitcpio -P<br />
<br />
Users may create any number of initramfs images with a variety of different configurations. The desired image must be specified in the respective [[boot loader]] configuration file.<br />
<br />
=== Customized generation ===<br />
<br />
Users can generate an image using an alternative configuration file. For example, the following will generate an initial ramdisk image according to the directions in {{ic|/etc/mkinitcpio-custom.conf}} and save it as {{ic|/boot/initramfs-custom.img}}.<br />
<br />
# mkinitcpio --config /etc/mkinitcpio-custom.conf --generate /boot/initramfs-custom.img<br />
<br />
If generating an image for a kernel other than the one currently running, add the kernel release version to the command line. The installed kernel releases can be found in {{ic|/usr/lib/modules/}}, the syntax is consistent with the output of the command {{ic|uname -r}} for each kernel.<br />
<br />
# mkinitcpio --generate /boot/initramfs-custom2.img --kernel 5.7.12-arch1-1<br />
<br />
=== Unified kernel images ===<br />
<br />
As of version 31, ''mkinitpcio'' can also create [[unified kernel image]]s.<br />
<br />
== Configuration ==<br />
<br />
The primary configuration file for ''mkinitcpio'' is {{ic|/etc/mkinitcpio.conf}}. Additionally, preset definitions are provided by kernel packages in the {{ic|/etc/mkinitcpio.d}} directory (e.g. {{ic|/etc/mkinitcpio.d/linux.preset}}).<br />
<br />
Users can modify six variables within the configuration file, see {{man|5|mkinitcpio.conf}} for more details:<br />
<br />
; {{ic|MODULES}}: Kernel modules to be loaded before any boot hooks are run. <br />
; {{ic|BINARIES}}: Additional binaries to be included in the initramfs image.<br />
; {{ic|FILES}}: Additional files to be included in the initramfs image.<br />
; {{ic|HOOKS}}: Hooks are scripts that execute in the initial ramdisk.<br />
; {{ic|COMPRESSION}}: Used to compress the initramfs image.<br />
; {{ic|COMPRESSION_OPTIONS}}: Extra arguments to pass to the {{ic|COMPRESSION}} program. Usage of this setting is strongly discouraged. ''mkinitcpio'' will handle special requirements for compressors (e.g. passing {{ic|1=--check=crc32}} to xz), and misusage can easily lead to an unbootable system.<br />
<br />
{{Note|<br />
* Some hooks that may be required for your system like '''lvm2''', '''mdadm_udev''', and '''encrypt''' are '''NOT''' enabled by default. Read the [[#HOOKS]] section carefully for instructions.<br />
* Users with multiple hardware disk controllers that use the same node names but different kernel modules (e.g. two SCSI/SATA or two IDE controllers) should use [[persistent block device naming]] to ensure that the right devices are mounted. Otherwise, the root device location may change between boots, resulting in kernel panics.<br />
}}<br />
<br />
=== MODULES ===<br />
<br />
The {{ic|MODULES}} array is used to specify modules to load before anything else is done.<br />
<br />
Modules suffixed with a {{ic|?}} will not throw errors if they are not found. This might be useful for custom kernels that compile in modules which are listed explicitly in a hook or configuration file.<br />
<br />
{{Note|<br />
* If using '''reiser4''', it ''must'' be added to the {{ic|MODULES}} array.<br />
* When using the '''encrypt''' or '''sd-encrypt''' hook, the keyboard modules and/or filesystems needed to unlock the LUKS device during system boot need to be added to the {{ic|MODULES}} array when the target system differs from the one used to run ''mkinitcpio''. For example, if you use a keyfile on an ext2 file system but no ext2 file system is mounted at the time ''mkinitcpio'' runs, add {{ic|ext2}}. See [[dm-crypt/System configuration#cryptkey]] for more details.<br />
* If using a keyboard through a USB 3 hub and wish to use it to unlock a LUKS device, add {{ic|usbhid xhci_hcd}}.<br />
* If using displays connected to a docking station, you might need to add a module for your graphic card to make initrd output visible (e.g. {{ic|i915}} for most Intel cards).<br />
}}<br />
<br />
=== BINARIES and FILES ===<br />
<br />
These options allow users to add files to the image. Both {{ic|BINARIES}} and {{ic|FILES}} are added before hooks are run, and may be used to override files used or provided by a hook. {{ic|BINARIES}} are auto-located within a standard {{ic|PATH}} and are dependency-parsed, meaning any required libraries will also be added. {{ic|FILES}} are added ''as-is''. For example:<br />
<br />
FILES=(/etc/modprobe.d/modprobe.conf)<br />
<br />
BINARIES=(kexec)<br />
<br />
Note that as both {{ic|BINARIES}} and {{ic|FILES}} are [[Bash]] arrays, multiple entries can be added delimited with spaces.<br />
<br />
=== HOOKS ===<br />
<br />
The {{ic|HOOKS}} array is the most important setting in the file. Hooks are small scripts which describe what will be added to the image. For some hooks, they will also contain a runtime component which provides additional behavior, such as starting a daemon, or assembling a stacked block device. Hooks are referred to by their name, and executed in the order they exist in the {{ic|HOOKS}} array of the configuration file.<br />
<br />
The default {{ic|HOOKS}} setting should be sufficient for most simple, single disk setups. For root devices which are stacked or multi-block devices such as [[LVM]], [[RAID]], or [[dm-crypt]], see the respective wiki pages for further necessary configuration.<br />
<br />
==== Build hooks ====<br />
<br />
Build hooks are found in {{ic|/usr/lib/initcpio/install/}}, custom build hooks can be placed in {{ic|/etc/initcpio/install/}}. These files are sourced by the bash shell during runtime of ''mkinitcpio'' and should contain two functions: {{ic|build}} and {{ic|help}}. The {{ic|build}} function describes the modules, files, and binaries which will be added to the image. An API, documented by {{man|8|mkinitcpio}}, serves to facilitate the addition of these items. The {{ic|help}} function outputs a description of what the hook accomplishes.<br />
<br />
For a list of all available hooks:<br />
<br />
$ mkinitcpio -L<br />
<br />
Use ''mkinitcpio'''s {{ic|-H}}/{{ic|--hookhelp}} option to output help for a specific hook, for example:<br />
<br />
$ mkinitcpio -H udev<br />
<br />
==== Runtime hooks ====<br />
<br />
Runtime hooks are found in {{ic|/usr/lib/initcpio/hooks/}}, custom runtime hooks can be placed in {{ic|/etc/initcpio/hooks/}}. For any runtime hook, there should always be a build hook of the same name, which calls {{ic|add_runscript}} to add the runtime hook to the image. These files are sourced by the busybox ash shell during early userspace. With the exception of cleanup hooks, they will always be run in the order listed in the {{ic|HOOKS}} setting. Runtime hooks may contain several functions:<br />
<br />
{{ic|run_earlyhook}}: Functions of this name will be run once the API file systems have been mounted and the kernel command line has been parsed. This is generally where additional daemons, such as udev, which are needed for the early boot process are started from.<br />
<br />
{{ic|run_hook}}: Functions of this name are run shortly after the early hooks. This is the most common hook point, and operations such as assembly of stacked block devices should take place here.<br />
<br />
{{ic|run_latehook}}: Functions of this name are run after the root device has been mounted. This should be used, sparingly, for further setup of the root device, or for mounting other file systems, such as {{ic|/usr}}.<br />
<br />
{{ic|run_cleanuphook}}: Functions of this name are run as late as possible, and in the reverse order of how they are listed in the {{ic|HOOKS}} array in the configuration file. These hooks should be used for any last minute cleanup, such as shutting down any daemons started by an early hook.<br />
<br />
{{Note|Runtime hooks are only used by busybox init. '''systemd''' hook triggers a systemd based init, which does not run any runtime hooks but uses systemd units instead.}}<br />
<br />
==== Common hooks ====<br />
<br />
A table of common hooks and how they affect image creation and runtime follows. Note that this table is not complete, as packages can provide custom hooks.<br />
<br />
{{Expansion|Add info about {{ic|hostdata}}, {{ic|memdisk}}, {{ic|sleep}} and {{ic|strip}}, find out if {{ic|dmraid}}, etc. work/are needed for systemd based initramfs.|section=Improvements for the Common hooks table and section about systemd hook}}<br />
<br />
{| class="wikitable"<br />
! busybox init !! systemd init !! [[#Build hooks|Build hook]] !! [[#Runtime hooks|Runtime hook]] (busybox init only)<br />
|-<br />
|colspan="2" {{C|'''base'''}} || Sets up all initial directories and installs base utilities and libraries. Always keep this hook as the first hook unless you know what you are doing, as it provides critical busybox init when not using '''systemd''' hook. <br/>Optional when using the '''systemd''' hook as it only provides a busybox recovery shell. {{Note|The recovery shell is not usable since the root account in the initramfs is [https://github.com/archlinux/svntogit-packages/commit/776743d220cbb56e9abca2cc8bcef3a0ab7c8d0a locked]. See {{Bug|70408}}.}}<br />
| {{-}}<br />
|-<br />
| {{C|'''udev'''}} ||rowspan="3" {{C|'''systemd'''}} || Adds udevd, udevadm, and a small subset of udev rules to your image. || Starts the udev daemon and processes uevents from the kernel; creating device nodes. As it simplifies the boot process by not requiring the user to explicitly specify necessary modules, using it is recommended.<br />
|-<br />
| {{C|'''usr'''}} || Adds support for {{ic|/usr}} on a separate partition. See [[#/usr as a separate partition]] for details. || Mounts the {{ic|/usr}} partition after the real root has been mounted.<br />
|-<br />
|-<br />
| {{C|'''resume'''}} || {{-}} || Tries to resume from the "suspend to disk" state. See [[Hibernation]] for further configuration.<br />
|-<br />
| {{C|'''btrfs'''}} || {{Grey|–}} || Sets the required modules to enable [[Btrfs]] for using multiple devices with Btrfs. You need to have {{Pkg|btrfs-progs}} installed to use this. This hook is not required for using Btrfs on a single device. || Runs {{ic|btrfs device scan}} to assemble a multi-device Btrfs root file system when '''udev''' hook or '''systemd''' hook is not present. The {{Pkg|btrfs-progs}} package is required for this hook.<br />
|-<br />
|colspan="2" {{C|'''autodetect'''}} || Shrinks your initramfs to a smaller size by creating a whitelist of modules from a scan of sysfs. Be sure to verify included modules are correct and none are missing. This hook must be run before other subsystem hooks in order to take advantage of auto-detection. Any hooks placed before 'autodetect' will be installed in full. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''modconf'''}} || Includes modprobe configuration files from {{ic|/etc/modprobe.d/}} and {{ic|/usr/lib/modprobe.d/}}. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''kms'''}} || Adds all GPU modules to provide [[Kernel mode setting#Early KMS start|early KMS start]].|| {{-}}<br />
|-<br />
|colspan="2" {{C|'''block'''}} || Adds all block device modules, formerly separately provided by the ''fw'', ''mmc'', ''pata'', ''sata'', ''scsi'', ''usb'', and ''virtio'' hooks. || {{-}}<br />
|-<br />
| {{C|'''net'''}} || {{Grey|''not implemented''}} || Adds the necessary modules for a network device. You must have {{Pkg|mkinitcpio-nfs-utils}} installed to use this, see [[#Using net]] for details. || Provides handling for an NFS-based root file system.<br />
|-<br />
| {{C|'''dmraid'''}} || {{Grey|''?''}} || Provides support for fakeRAID root devices. You must have {{Pkg|dmraid}} installed to use this. Note that it is preferred to use [[mdadm]] with the '''mdadm_udev''' hook with fakeRAID if your controller supports it. See [[#Using RAID]] for details. || Locates and assembles fakeRAID block devices using {{ic|dmraid}}.<br />
|-<br />
|colspan="2" {{C|'''mdadm_udev'''}} || Provides support for assembling RAID arrays via udev. You must have {{Pkg|mdadm}} installed to use this. If you use this hook with a FakeRAID array, it is recommended to include {{ic|mdmon}} in {{ic|BINARIES}}. See [[#Using RAID]] for details. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''keyboard'''}} || Adds the necessary modules for keyboard devices. Use this if you have an USB or serial keyboard and need it in early userspace (either for entering encryption passphrases or for use in an interactive shell). As a side effect, modules for some non-keyboard input devices might be added too, but this should not be relied on. Supersedes old ''usbinput'' hook.<br />
<br />
{{Note|For systems that are booted with different hardware configurations (e.g. laptops with external keyboard vs. internal keyboard or [[Wikipedia:Headless computer|headless systems]]), this hook needs to be placed before '''autodetect''' in order to be able to use the keyboard at boot time, for example to unlock an encrypted device when using the {{ic|encrypt}} hook.}}<br />
<br />
| {{-}}<br />
|-<br />
| {{C|'''keymap'''}} ||rowspan="2" {{C|'''sd-vconsole'''}} || Adds the specified [[Linux console/Keyboard configuration#Persistent configuration|keymap(s)]] from {{ic|/etc/vconsole.conf}} to the initramfs. If you use [[dm-crypt/Encrypting an entire system|system encryption]], especially full-disk encryption, make sure you add it before the {{ic|1=encrypt}} hook. || Loads the specified keymap(s) from {{ic|/etc/vconsole.conf}} during early userspace.<br />
|-<br />
| {{C|'''consolefont'''}} || Adds the specified [[Linux console#Persistent configuration|console font]] from {{ic|/etc/vconsole.conf}} to the initramfs. || Loads the specified console font from {{ic|/etc/vconsole.conf}} during early userspace.<br />
|-<br />
| {{C|'''encrypt'''}} || {{C|'''sd-encrypt'''}} || Adds the {{ic|dm_crypt}} kernel module and the {{ic|cryptsetup}} tool to the image. You must have {{Pkg|cryptsetup}} installed to use this. {{Note|Take notice of the remarks for the ''keyboard'' hook above to unlock an encrypted device during boot, and/or the filesystem remarks in [[#MODULES]] when you use a file to unlock.}} || Detects and unlocks an encrypted root partition. See [[#Runtime customization]] for further configuration.<br />
For '''sd-encrypt''' see [[dm-crypt/System configuration#Using systemd-cryptsetup-generator]].<br />
|-<br />
|colspan="2" {{C|'''lvm2'''}} || Adds the device mapper kernel module and the {{ic|lvm}} tool to the image. You must have {{Pkg|lvm2}} installed to use this. This is necessary if you have your root file system on [[LVM]]. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''fsck'''}} || Adds the fsck binary and file system-specific helpers to allow running fsck against your root device (and {{ic|/usr}} if separate) prior to mounting. If added after the '''autodetect''' hook, only the helper specific to your root file system will be added. Usage of this hook is '''strongly''' recommended, and it is required with a separate {{ic|/usr}} partition. It is highly recommended that if you include this hook that you also include any necessary modules to ensure your keyboard will work in early userspace. <br/>The use of this hook requires the {{ic|rw}} parameter to be set on the [[kernel command line]] ([https://bbs.archlinux.org/viewtopic.php?pid=1307895#p1307895 discussion]). See [[fsck#Boot time checking]] for more details. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''filesystems'''}} || This includes necessary file system modules into your image. This hook is '''required''' unless you specify your file system modules in {{ic|MODULES}}. || {{-}}<br />
|-<br />
|}<br />
<br />
=== COMPRESSION ===<br />
<br />
The kernel supports several formats for compression of the initramfs: {{Pkg|gzip}}, {{Pkg|bzip2}}, lzma, {{Pkg|xz}}, {{Pkg|lzo}}, {{Pkg|lz4}} and {{Pkg|zstd}}. mkinitcpio uses zstd compressed images by default, note that the zstd compression runs in multi-threading mode (with the {{ic|-T0}} option which spawns as many threads as detected cores).<br />
<br />
The provided {{ic|mkinitcpio.conf}} has the various {{ic|COMPRESSION}} options commented out. Uncomment one if you wish to switch to another compression method and make sure you have the corresponding compression utility installed. If none is specified, the zstd default method is used. If you wish to create an uncompressed image, specify {{ic|1=COMPRESSION='''cat'''}} in the configuration file or use {{ic|-z cat}} on the command line.<br />
<br />
{{Tip|With a compression ratio typically around 2.5 on the image in its high compression mode ({{ic|-9}}), lz4 achieves the fastest decompression speed at the cost of a slower single-threaded compression. For a slightly better compression, lzo is still fast to decompress. zstd offers a versatile solution, with multi-threaded compression and a wide range of compression levels through its options — see {{man|1|zstd|Operation modifiers}}. xz achieves the smallest size with a reduction factor around 5 in its high compression preset ({{ic|-9}}), at the cost of a much slower decompression speed.}}<br />
<br />
=== COMPRESSION_OPTIONS ===<br />
<br />
These are additional flags passed to the program specified by {{ic|COMPRESSION}}, such as:<br />
<br />
COMPRESSION_OPTIONS=(-9)<br />
<br />
{{Note|This option can be left empty; ''mkinitcpio'' will ensure that any supported compression method has the necessary flags to produce a working image. Misuse of this option may lead to an '''unbootable system''' if the kernel is unable to unpack the resultant archive.}}<br />
<br />
With the current default zstd, to save space for custom kernels (especially with a dual-boot setup and original Windows EFI partition), the {{ic|--long}} option is very effective. However, systems with limited RAM may not be able to decompress initramfs using this option. The {{ic|-v}} option may also be desired to see details during the initramfs generation. E.g.:<br />
<br />
COMPRESSION_OPTIONS=(-v -5 --long)<br />
<br />
== Runtime customization ==<br />
<br />
{{Expansion|Which options work with the {{ic|systemd}} hook and which are {{ic|base}}-only?}}<br />
<br />
Runtime configuration options can be passed to {{ic|init}} and certain hooks via the kernel command line. Kernel command-line parameters are often supplied by the bootloader. The options discussed below can be appended to the kernel command line to alter default behavior. See [[Kernel parameters]] and [[Arch boot process]] for more information.<br />
<br />
=== init from base hook ===<br />
<br />
; {{ic|root}}: This is the most important parameter specified on the kernel command line, as it determines what device will be mounted as your proper root device. ''mkinitcpio'' is flexible enough to allow a wide variety of formats, for example: {{bc|1=<nowiki><br />
root=/dev/sda1 # /dev node<br />
root=LABEL=CorsairF80 # label<br />
root=UUID=ea1c4959-406c-45d0-a144-912f4e86b207 # UUID<br />
root=PARTUUID=14420948-2cea-4de7-b042-40f67c618660 # GPT partition UUID</nowiki><br />
}} {{Note|The following boot parameters alter the default behavior of {{ic|init}} in the initramfs environment. See {{ic|/usr/lib/initcpio/init}} for details. They will not work when {{ic|systemd}} hook is being used since the {{ic|init}} from {{ic|base}} hook is replaced.}}<br />
<br />
; {{ic|break}}: If {{ic|break}} or {{ic|1=break=premount}} is specified, {{ic|init}} pauses the boot process (after loading hooks, but before mounting the root file system) and launches an interactive shell which can be used for troubleshooting purposes. This shell can be launched after the root has been mounted by specifying {{ic|1=break=postmount}}. Normal boot continues after exiting from the shell.<br />
<br />
; {{ic|disablehooks}}: Disable hooks at runtime by adding {{ic|1=disablehooks=hook1[,hook2,...]}}. For example: {{bc|1=disablehooks=resume}}<br />
<br />
; {{ic|earlymodules}}: Alter the order in which modules are loaded by specifying modules to load early via {{ic|1=earlymodules=mod1[,mod2,...]}}. (This may be used, for example, to ensure the correct ordering of multiple network interfaces.)<br />
<br />
See [[Boot debugging]] and {{man|8|mkinitcpio}} for other parameters.<br />
<br />
=== Using RAID ===<br />
<br />
See [[RAID#Configure mkinitcpio]].<br />
<br />
=== Using net ===<br />
<br />
{{Note|NFSv4 is not yet supported {{Bug|28287}}.}}<br />
<br />
'''Required packages'''<br />
<br />
{{ic|net}} requires the {{Pkg|mkinitcpio-nfs-utils}} package.<br />
<br />
'''Kernel parameters''' <br />
<br />
Comprehensive and up-to-date information can be found in the official [https://docs.kernel.org/admin-guide/nfs/nfsroot.html kernel documentation].<br />
<br />
'''ip='''<br />
<br />
This parameter tells the kernel how to configure IP addresses of devices and also how to set up the IP routing table. It can take up to nine arguments separated by colons: {{ic|1=ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:<dns0-ip>:<dns1-ip>:<ntp0-ip>}}.<br />
<br />
If this parameter is missing from the kernel command line, all fields are assumed to be empty, and the defaults mentioned in the [https://docs.kernel.org/admin-guide/nfs/nfsroot.html kernel documentation] apply. In general this means that the kernel tries to configure everything using autoconfiguration.<br />
<br />
The {{ic|<autoconf>}} parameter can appear alone as the value to the {{ic|ip}} parameter (without all the {{ic|:}} characters before). If the value is {{ic|1=ip=off}} or {{ic|1=ip=none}}, no autoconfiguration will take place, otherwise autoconfiguration will take place. The most common way to use this is {{ic|1=ip=dhcp}}.<br />
<br />
For parameters explanation, see the [https://docs.kernel.org/admin-guide/nfs/nfsroot.html kernel documentation].<br />
<br />
Examples:<br />
<br />
ip=127.0.0.1:::::lo:none --> Enable the loopback interface.<br />
ip=192.168.1.1:::::eth2:none --> Enable static eth2 interface.<br />
ip=:::::eth0:dhcp --> Enable dhcp protocol for eth0 configuration.<br />
<br />
{{Note|Make sure to use kernel device names (e.g. {{ic|eth0}}) for the {{ic|<device>}} parameter, the persistent names (e.g. {{ic|enp2s0}}) will not work. See [[Network configuration#Network interfaces]] for details.}}<br />
<br />
'''BOOTIF='''<br />
<br />
If you have multiple network cards, this parameter can include the MAC address of the interface you are booting from. This is often useful as interface numbering may change, or in conjunction with pxelinux IPAPPEND 2 or IPAPPEND 3 option. If not given, {{ic|eth0}} will be used.<br />
<br />
Example:<br />
<br />
BOOTIF=01-A1-B2-C3-D4-E5-F6 # Note the prepended "01-" and capital letters.<br />
<br />
'''nfsroot='''<br />
<br />
If the {{ic|nfsroot}} parameter is NOT given on the command line, the default {{ic|/tftpboot/%s}} will be used.<br />
<br />
nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]<br />
<br />
Run {{ic|mkinitcpio -H net}} for parameter explanation.<br />
<br />
=== Using LVM ===<br />
<br />
If your root device is on [[LVM]], see [[Install Arch Linux on LVM#Adding mkinitcpio hooks]].<br />
<br />
=== Using encrypted root ===<br />
<br />
If using an [[dm-crypt/Encrypting an entire system|encrypted root]] see [[dm-crypt/System configuration#mkinitcpio]] for detailed information on which hooks to include.<br />
<br />
=== /usr as a separate partition ===<br />
<br />
If you keep {{ic|/usr}} as a separate partition, you must adhere to the following requirements:<br />
<br />
* Add the {{ic|fsck}} hook, mark {{ic|/usr}} with a {{ic|passno}} of {{ic|2}} in {{ic|/etc/fstab}} to run the check on the partition at startup. While recommended for everyone, it is mandatory if you want your {{ic|/usr}} partition to be fsck'ed at boot-up. Without this hook, {{ic|/usr}} will never be fsck'd.<br />
* If not using the systemd hook, add the {{ic|usr}} hook. This will mount the {{ic|/usr}} partition after root is mounted.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Extracting the image ===<br />
<br />
If you are curious about what is inside the initramfs image, you can extract it and poke at the files inside of it. <br />
<br />
The initramfs image is an SVR4 CPIO archive, generated via the {{ic|find}} and {{ic|bsdcpio}} commands, optionally compressed with a compression scheme understood by the kernel. For more information on the compression schemes, see [[#COMPRESSION]].<br />
<br />
''mkinitcpio'' includes a utility called {{man|1|lsinitcpio}} which will list and/or extract the contents of initramfs images.<br />
<br />
You can list the files in the image with:<br />
<br />
# lsinitcpio /boot/initramfs-linux.img<br />
<br />
And to extract them all in the current directory:<br />
<br />
# lsinitcpio -x /boot/initramfs-linux.img<br />
<br />
You can also get a more human-friendly listing of the important parts in the image:<br />
<br />
# lsinitcpio -a /boot/initramfs-linux.img<br />
<br />
=== Recompressing a modified extracted image ===<br />
<br />
Invoke the {{ic|build_image}} function of the {{ic|/usr/bin/mkinitcpio}} script with parameters<br />
<br />
build_image ''outfile'' ''compression''<br />
<br />
It can be done by creating a new script with the contents of the {{ic|build_image}} function and running it with the above parameters.<br />
This will compress the contents present in the current directory in a file named {{ic|''outfile''}}.<br />
<br />
{{Warning|It is a good idea to rename the automatically generated {{ic|/boot/initramfs-linux.img}} before you overwrite it, so you can easily undo your changes. Be prepared for making a mistake that prevents your system from booting. If this happens, you will need to boot through the fallback, or a boot CD, to restore your original, run ''mkinitcpio'' to overwrite your changes, or fix them yourself and recompress the image.}}<br />
<br />
=== "/dev must be mounted" when it already is ===<br />
<br />
The test used by ''mkinitcpio'' to determine if {{ic|/dev}} is mounted is to see if {{ic|/dev/fd/}} is there. If everything else looks fine, it can be "created" manually by:<br />
<br />
# ln -s /proc/self/fd /dev/<br />
<br />
(Obviously, {{ic|/proc}} must be mounted as well. ''mkinitcpio'' requires that anyway, and that is the next thing it will check.)<br />
<br />
=== Possibly missing firmware for module XXXX ===<br />
<br />
When initramfs are being rebuilt after a kernel update, you might get warnings:<br />
<br />
==> WARNING: Possibly missing firmware for module: ''module_name''<br />
<br />
If these messages appear when generating a ''default'' initramfs image, then, as the warning says, installing additional firmware may be required. Most common firmware files can be acquired by [[install]]ing the {{Pkg|linux-firmware}} package. For other packages providing firmware see the table below or try searching for the module name in the [[official repositories]] or [[AUR]].<br />
<br />
Otherwise, if the messages only appear when generating the ''fallback'' initramfs image you have the following options:<br />
<br />
* You can safely ignore the warnings, if you know that you do not use the affected hardware.<br />
* If you want to suppress the warnings, you can install the missing firmware. The meta-package {{AUR|mkinitcpio-firmware}} contains most optional firmwares. Alternatively, manually install the needed packages:<br />
:{| class="wikitable"<br />
|-<br />
! Module !! Package<br />
|-<br />
| aic94xx || {{AUR|aic94xx-firmware}}<br />
|-<br />
| bfa || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| bnx2x || {{Pkg|linux-firmware-bnx2x}}<br />
|-<br />
| liquidio || {{Pkg|linux-firmware-liquidio}}<br />
|-<br />
| mlxsw_spectrum || {{Pkg|linux-firmware-mellanox}}<br />
|-<br />
| nfp || {{Pkg|linux-firmware-nfp}}<br />
|-<br />
| qat_4xxx || Firmware is not yet available.<br />
|-<br />
| qed || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| qla1280 || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| qla2xxx || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| wd719x || {{AUR|wd719x-firmware}}<br />
|-<br />
| xhci_pci || {{AUR|upd72020x-fw}}<br />
|}<br />
* If you want to get rid of the warnings, but do not want to waste your system space on unneeded firmware packages, you can disable fallback initramfs generation altogether:<br />
*# Change {{ic|1=PRESETS=('default' 'fallback')}} line to {{ic|1=PRESETS=('default')}} in all ''.preset'' files in {{ic|/etc/mkinitcpio.d/}}.<br />
*# Remove fallback initramfs images: {{ic|# rm /boot/*-fallback.img}}.<br />
*# Regenerate your bootloader config (e.g. for [[GRUB]]: {{ic|# grub-mkconfig -o /boot/grub/grub.cfg}}).<br />
:{{Warning|Disabling fallback initramfs generation will deprive you of another option to boot into the system in case a default initramfs fails. Before proceeding, make sure you have a bootable [[USB flash installation medium|installation medium]] for rescue purposes on hand.}}<br />
<br />
=== No PS/2 controller found ===<br />
<br />
On some motherboards (mostly ancient ones, but also a few new ones), the i8042 controller cannot be automatically detected. It is rare, but some people will surely be without keyboard. You can detect this situation in advance. If you have a PS/2 port and get {{ic|i8042: PNP: No PS/2 controller found. Probing ports directly}} message, add '''atkbd''' to the {{ic|MODULES}} array.<br />
<br />
=== Standard rescue procedures ===<br />
<br />
With an improper initial ram-disk a system often is unbootable. So follow a system rescue procedure like below:<br />
<br />
==== Boot succeeds on one machine and fails on another ====<br />
<br />
''mkinitcpio'''s {{ic|autodetect}} hook filters unneeded [[kernel modules]] in the primary initramfs scanning {{ic|/sys}} and the modules loaded at the time it is run. If you transfer your {{ic|/boot}} directory to another machine and the boot sequence fails during early userspace, it may be because the new hardware is not detected due to missing kernel modules. Note that USB 2.0 and 3.0 need different kernel modules. <br />
<br />
To fix, first try choosing the [[#Image creation and activation|fallback]] image from your [[bootloader]], as it is not filtered by {{ic|autodetect}}. Once booted, run ''mkinitcpio'' on the new machine to rebuild the primary image with the correct modules. If the fallback image fails, try booting into an Arch Linux live CD/USB, chroot into the installation, and run ''mkinitcpio'' on the new machine. As a last resort, try [[#MODULES|manually]] adding modules to the initramfs.<br />
<br />
== See also ==<br />
<br />
* Linux Kernel documentation on [https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html#what-is-rootfs initramfs, "What is rootfs?"]<br />
* Linux Kernel documentation on [https://docs.kernel.org/admin-guide/initrd.html initrd]<br />
* Wikipedia article on [[wikipedia:initrd|initrd]]</div>Jwh7https://wiki.archlinux.org/index.php?title=EFI_system_partition&diff=754808EFI system partition2022-10-25T18:09:39Z<p>Jwh7: /* Mount the partition */ Mention zstd's --long option to greatly reduce initramfs size</p>
<hr />
<div>[[Category:Boot process]]<br />
[[es:EFI system partition]]<br />
[[fr:EFI system partition]]<br />
[[ja:EFI システムパーティション]]<br />
[[pt:EFI system partition]]<br />
[[ru:EFI system partition]]<br />
[[zh-hans:EFI system partition]]<br />
{{Related articles start}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related|Boot loader}}<br />
{{Related articles end}}<br />
The [[Wikipedia:EFI system partition|EFI system partition]] (also called ESP) is an OS independent partition that acts as the storage place for the EFI bootloaders, applications and drivers to be launched by the UEFI firmware. It is mandatory for UEFI boot. <br />
<br />
== Check for an existing partition ==<br />
<br />
If you are installing Arch Linux on an UEFI-capable computer with an installed operating system, like [[Dual boot with Windows|Windows]] 10 for example, it is very likely that you already have an EFI system partition.<br />
<br />
To find out the disk partition scheme and the system partition, use [[fdisk]] as root on the disk you want to boot from:<br />
<br />
# fdisk -l /dev/sd''x''<br />
<br />
The command returns:<br />
<br />
* The disk's partition table: it indicates {{ic|Disklabel type: gpt}} if the partition table is [[GPT]] or {{ic|Disklabel type: dos}} if it is [[MBR]].<br />
* The list of partitions on the disk: Look for the EFI system partition in the list, it is usually at least 100 MiB in size and has the type {{ic|EFI System}} or {{ic|EFI (FAT-12/16/32)}}. To confirm this is the ESP, [[mount]] it and check whether it contains a directory named {{ic|EFI}}, if it does this is definitely the ESP.<br />
<br />
{{Tip|To find out whether it is a FAT12, FAT16 or FAT32 file system, follow [[FAT#Detecting FAT type]].}}<br />
<br />
{{Warning|When dual-booting, avoid reformatting the ESP, as it may contain files required to boot other operating systems.}}<br />
<br />
If you found an existing EFI system partition, simply proceed to [[#Mount the partition]]. If you did not find one, you will need to create it, proceed to [[#Create the partition]].<br />
<br />
== Create the partition ==<br />
<br />
The following two sections show how to create an EFI system partition (ESP).<br />
<br />
{{Warning|The EFI system partition must be a physical partition in the main partition table of the disk, not under LVM or software RAID etc.}}<br />
<br />
The partition size should provide adequate space for storing boot loaders and other files required for booting.<br />
<br />
To prevent interoperability issues with other operating systems[https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/configure-uefigpt-based-hard-drive-partitions#diskpartitionrules][https://superuser.com/questions/1310927/what-is-the-absolute-minimum-size-a-uefi-partition-can-be/1310938] it is recommend to make it at least 300 MiB. For early and/or buggy UEFI implementations the size of at least 512 MiB might be needed.[https://www.rodsbooks.com/efi-bootloaders/principles.html] If none of these are relevant issues, the partition size can be as small as 2 MiB, in which case it could house nothing more than a boot loader.<br />
<br />
=== GPT partitioned disks ===<br />
<br />
EFI system partition on a [[GUID Partition Table]] is identified by the [[Wikipedia:GUID Partition Table#Partition type GUIDs|partition type GUID]] {{ic|C12A7328-F81F-11D2-BA4B-00A0C93EC93B}}.<br />
<br />
'''Choose one''' of the following methods to create an ESP for a GPT partitioned disk:<br />
<br />
* [[fdisk]]: Create a partition with partition type {{ic|EFI System}}.<br />
* [[gdisk]]: Create a partition with partition type {{ic|EF00}}.<br />
* [[GNU Parted]]: Create a partition with {{ic|fat32}} as the file system type and set the {{ic|esp}} flag on it.<br />
<br />
After creating the partition, it should be formatted with a file system. Proceed to the [[#Format the partition]] section below.<br />
<br />
=== MBR partitioned disks ===<br />
<br />
{{Note|<br />
* It is recommended to use [[GPT]] since some firmwares might not support UEFI/MBR booting due to it not being supported by [[Dual boot with Windows|Windows Setup]].<br />
* ''bootctl'' does not support installing [[systemd-boot]] to an MBR partitioned disk; see [https://github.com/systemd/systemd/issues/1125 systemd issue 1125].<br />
<br />
See also [[Partitioning#Choosing between GPT and MBR]] for the advantages of GPT in general.<br />
}}<br />
<br />
EFI system partition on a [[Master Boot Record]] partition table is identified by the [[Wikipedia:Partition type|partition type ID]] {{ic|EF}}.<br />
<br />
'''Choose one''' of the following methods to create an ESP for a MBR partitioned disk:<br />
<br />
* [[fdisk]]: Create a primary partition with partition type {{ic|EFI (FAT-12/16/32)}}.<br />
* [[GNU Parted]]: Create a primary partition with {{ic|fat32}} as the file system type and set the {{ic|esp}} flag on it.<br />
<br />
After creating the partition, it should be formatted with a file system. Proceed to the [[#Format the partition]] section below.<br />
<br />
== Format the partition ==<br />
<br />
The UEFI specification mandates support for the FAT12, FAT16, and FAT32 file systems (see [https://uefi.org/sites/default/files/resources/UEFI_Spec_2_9_2021_03_18.pdf#G17.1019485 UEFI specification version 2.9, section 13.3.1.1]), but any conformant vendor can optionally add support for additional file systems; for example, the firmware in Apple [[Mac]]s supports the HFS+ file system.<br />
<br />
To prevent potential issues with other operating systems and since the UEFI specification says that UEFI "encompasses the use of FAT32 for a system partition, and FAT12 or FAT16 for removable media"[https://uefi.org/sites/default/files/resources/UEFI_Spec_2_9_2021_03_18.pdf#G17.1345080], it is recommended to use [[FAT32]]. Use the {{man|8|mkfs.fat}} utility from {{Pkg|dosfstools}}:<br />
<br />
# mkfs.fat -F 32 /dev/sd''xY''<br />
<br />
If you get the message {{ic|WARNING: Not enough clusters for a 32 bit FAT!}}, reduce cluster size with {{ic|mkfs.fat -s2 -F32 ...}} or {{ic|-s1}}; otherwise the partition may be unreadable by UEFI. See {{man|8|mkfs.fat}} for supported cluster sizes.<br />
<br />
For partitions smaller than 32 MiB using FAT32 may not be possible. In which case, format it to FAT16 or even FAT12. For example, a 2 MiB ESP will only be able to support FAT12:<br />
<br />
# mkfs.fat -F 12 /dev/sd''xY''<br />
<br />
== Mount the partition ==<br />
<br />
The kernels, initramfs files, and, in most cases, the processor's [[microcode]], need to be accessible by the [[boot loader]] or UEFI itself to successfully boot the system. Thus if you want to keep the setup simple, your boot loader choice limits the available mount points for EFI system partition.<br />
<br />
=== Typical mount points ===<br />
<br />
The simplest scenarios for mounting the EFI system partition are:<br />
<br />
* [[mount]] ESP to {{ic|/boot}}. This is the most straightforward method.<br />
** This facilitates system maintenance, as {{ic|/boot}} is the default path where [[microcode]] packages place the CPU microcode initramfs files, and where [[mkinitcpio]] places [[kernel]]s and [[initramfs]] images.<br />
** To save EFI partition space (e.g. for [[dual boot]]), use zstd for [[mkinitcpio]] (the default) with the '--long' [[Mkinitcpio#COMPRESSION_OPTIONS|compression option]]. <br />
** This ensures that the above files are accessible to most [[boot loader]]s, as not all of them can access files on other volumes.<br />
* [[mount]] ESP to {{ic|/efi}}.<br />
** This can be useful for [[unified kernel image]]s or [[boot loader]]s that have file system drivers capable of accessing the kernel(s) and files that are stored elsewhere (typically [[Partitioning#/boot|/boot]]).<br />
** Only the EFI binaries (the boot loader (and optionally drivers) and/or the unified kernel image) will be stored on the ESP, which saves storage space.<br />
* [[mount]] ESP to {{ic|/efi}} and additionally mount an "Extended Boot Loader Partition" (XBOOTLDR) to {{ic|/boot}}. This can be useful when a previously created ESP is too small to hold multiple boot loaders and/or kernels but the ESP cannot be easily resized (such as when installing Linux after Windows to [[dual boot]]). This method is supported by at least [[systemd-boot#Installation using XBOOTLDR|systemd-boot]].<br />
<br />
{{Tip|<br />
* {{ic|/efi}} is a replacement[https://github.com/systemd/systemd/pull/3757#issuecomment-234290236] for the historical and now discouraged ESP mountpoint {{ic|/boot/efi}}.<br />
* The {{ic|/efi}} directory is not available by default, you will need to first create it with {{man|1|mkdir}} before mounting the ESP to it.<br />
}}<br />
<br />
=== Alternative mount points ===<br />
<br />
If you do not use one of the simple methods from [[#Typical mount points]], you will need to copy your boot files to ESP (referred to hereafter as {{ic|''esp''}}).<br />
<br />
# mkdir -p ''esp''/EFI/arch<br />
# cp -a /boot/vmlinuz-linux ''esp''/EFI/arch/<br />
# cp -a /boot/initramfs-linux.img ''esp''/EFI/arch/<br />
# cp -a /boot/initramfs-linux-fallback.img ''esp''/EFI/arch/<br />
<br />
{{Note|You may also need to copy the [[Microcode]] to the boot-entry location.}}<br />
<br />
Furthermore, you will need to keep the files on the ESP up-to-date with later kernel updates. Failure to do so could result in an unbootable system. The following sections discuss several mechanisms for automating it.<br />
<br />
{{Accuracy|{{man|8|systemd-gpt-auto-generator}} uses {{ic|/efi}} as the default mount point if available, {{ic|/boot}} otherwise.}}<br />
{{Note|If ESP is not mounted to {{ic|/boot}}, make sure to not rely on the [[fstab#Automount with systemd|systemd automount mechanism]] (including that of {{man|8|systemd-gpt-auto-generator}}). Always have it mounted manually prior to any system or kernel update, otherwise you may not be able to mount it after the update, locking you in the currently running kernel with no ability to update the copy of kernel on ESP.<br />
<br />
Alternatively [[Kernel module#systemd|preload the required kernel modules on boot]], e.g.:<br />
<br />
{{hc|/etc/modules-load.d/vfat.conf|<br />
vfat<br />
nls_cp437<br />
nls_ascii<br />
}}<br />
<br />
}}<br />
<br />
==== Using bind mount ====<br />
<br />
Instead of mounting the ESP itself to {{ic|/boot}}, you can mount a directory of the ESP to {{ic|/boot}} using a bind [[mount]] (see {{man|8|mount}}). This allows [[pacman]] to update the kernel directly while keeping the ESP organized to your liking.<br />
<br />
{{Note|1=This requires a [[FAT#Kernel configuration|kernel]] and [[bootloader]] compatible with FAT32. This is not an issue for a regular Arch install, but could be problematic for other distributions (namely those that require symlinks in {{ic|/boot/}}). See the forum post [https://bbs.archlinux.org/viewtopic.php?pid=1331867#p1331867].}}<br />
<br />
Just like in [[#Alternative mount points]], copy all boot files to a directory on your ESP, but mount the ESP '''outside''' {{ic|/boot}}. Then bind mount the directory:<br />
<br />
# mount --bind ''esp''/EFI/arch /boot<br />
<br />
After verifying success, edit your [[Fstab]] to make the changes persistent:<br />
<br />
{{hc|/etc/fstab|<br />
''esp''/EFI/arch /boot none defaults,bind 0 0<br />
}}<br />
<br />
==== Using systemd ====<br />
<br />
[[Systemd]] features event triggered tasks. In this particular case, the ability to detect a change in path is used to sync the EFISTUB kernel and initramfs files when they are updated in {{ic|/boot/}}. The file watched for changes is {{ic|initramfs-linux-fallback.img}} since this is the last file built by mkinitcpio, to make sure all files have been built before starting the copy. The ''systemd'' path and service files to be created are:<br />
<br />
{{hc|/etc/systemd/system/efistub-update.path|2=<br />
[Unit]<br />
Description=Copy EFISTUB Kernel to EFI system partition<br />
<br />
[Path]<br />
PathChanged=/boot/initramfs-linux-fallback.img<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
WantedBy=system-update.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/efistub-update.service|2=<br />
[Unit]<br />
Description=Copy EFISTUB Kernel to EFI system partition<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/cp -af /boot/vmlinuz-linux ''esp''/EFI/arch/<br />
ExecStart=/usr/bin/cp -af /boot/initramfs-linux.img ''esp''/EFI/arch/<br />
ExecStart=/usr/bin/cp -af /boot/initramfs-linux-fallback.img ''esp''/EFI/arch/<br />
}}<br />
<br />
Then [[enable]] and [[start]] {{ic|efistub-update.path}}.<br />
<br />
{{Tip|For [[Secure Boot]] with your own keys, you can set up the service to also sign the image using {{Pkg|sbsigntools}}:<br />
<br />
{{bc|1=ExecStart=/usr/bin/sbsign --key ''/path/to/db.key'' --cert ''/path/to/db.crt'' --output ''esp''/EFI/arch/vmlinuz-linux /boot/vmlinuz-linux}}<br />
<br />
}}<br />
<br />
==== Using filesystem events ====<br />
<br />
[[Autostarting#On filesystem events|Filesystem events]] can be used to run a script syncing the EFISTUB Kernel after kernel updates. An example with [[incron]] follows.<br />
<br />
{{hc|/usr/local/bin/efistub-update|<br />
#!/bin/sh<br />
cp -af /boot/vmlinuz-linux ''esp''/EFI/arch/<br />
cp -af /boot/initramfs-linux.img ''esp''/EFI/arch/<br />
cp -af /boot/initramfs-linux-fallback.img ''esp''/EFI/arch/<br />
}}<br />
<br />
{{Note|The first parameter {{ic|/boot/initramfs-linux-fallback.img}} is the file to watch. The second parameter {{ic|IN_CLOSE_WRITE}} is the action to watch for. The third parameter {{ic|/usr/local/bin/efistub-update}} is the script to execute.}}<br />
<br />
{{hc|/etc/incron.d/efistub-update.conf|<br />
/boot/initramfs-linux-fallback.img IN_CLOSE_WRITE /usr/local/bin/efistub-update<br />
}}<br />
<br />
In order to use this method, [[enable]] the {{ic|incrond.service}}.<br />
<br />
==== Using mkinitcpio hook ====<br />
<br />
Mkinitcpio can generate a hook that does not need a system level daemon to function. It spawns a background process which waits for the generation of {{ic|vmlinuz}}, {{ic|initramfs-linux.img}}, and {{ic|initramfs-linux-fallback.img}} before copying the files.<br />
<br />
Add {{ic|efistub-update}} to the list of hooks in {{ic|/etc/mkinitcpio.conf}}.<br />
<br />
{{hc|/etc/initcpio/install/efistub-update|2=<br />
#!/usr/bin/env bash<br />
build() {<br />
/usr/local/bin/efistub-copy $$ &<br />
}<br />
<br />
help() {<br />
cat <<HELPEOF<br />
This hook waits for mkinitcpio to finish and copies the finished ramdisk and kernel to the ESP<br />
HELPEOF<br />
}<br />
}}<br />
<br />
{{hc|/usr/local/bin/efistub-copy|<br />
#!/bin/sh<br />
<br />
if [ "$1" -gt 0 ]<br />
then<br />
while [ -e /proc/"$1" ]<br />
do<br />
sleep .5<br />
done<br />
fi<br />
<br />
rsync -a /boot/ ''esp''/<br />
<br />
echo "Synced /boot with ESP"<br />
}}<br />
<br />
==== Using mkinitcpio preset ====<br />
<br />
As the presets in {{ic|/etc/mkinitcpio.d/}} support shell scripting, the kernel and initramfs can be copied by just editing the presets.<br />
<br />
===== Replacing the above mkinitcpio hook =====<br />
<br />
Edit the file {{ic|/etc/mkinitcpio.d/linux.preset}}:<br />
<br />
{{hc|/etc/mkinitcpio.d/linux.preset|2=<br />
# mkinitcpio preset file for the 'linux' package<br />
<br />
# Directory to copy the kernel, the initramfs...<br />
ESP_DIR="''esp''/EFI/arch"<br />
<br />
ALL_config="/etc/mkinitcpio.conf"<br />
ALL_kver="${ESP_DIR}/vmlinuz-linux"<br />
cp -af /boot/vmlinuz-linux "${ESP_DIR}/"<br />
<nowiki>[[ -e /boot/intel-ucode.img ]] && cp -af /boot/intel-ucode.img "${ESP_DIR}/"<br />
[[ -e /boot/amd-ucode.img ]] && cp -af /boot/amd-ucode.img "${ESP_DIR}/"</nowiki><br />
<br />
PRESETS=('default' 'fallback')<br />
<br />
#default_config="/etc/mkinitcpio.conf"<br />
default_image="${ESP_DIR}/initramfs-linux.img"<br />
default_options=""<br />
<br />
#fallback_config="/etc/mkinitcpio.conf"<br />
fallback_image="${ESP_DIR}/initramfs-linux-fallback.img"<br />
fallback_options="-S autodetect"<br />
}}<br />
To test that, just run:<br />
<br />
# rm /boot/initramfs-linux-fallback.img /boot/initramfs-linux.img<br />
# mkinitcpio -p linux<br />
<br />
===== Another example =====<br />
<br />
{{hc|/etc/mkinitcpio.d/linux.preset|2=<br />
ESP_DIR="''esp''/EFI/arch"<br />
cp -f "/boot/vmlinuz-linux$suffix" "$ESP_DIR/"<br />
ALL_config="/etc/mkinitcpio.conf"<br />
ALL_kver="$ESP_DIR/vmlinuz-linux$suffix"<br />
PRESETS=('default')<br />
default_config="/etc/mkinitcpio.conf"<br />
default_image="$ESP_DIR/initramfs-linux$suffix.img"<br />
}}<br />
<br />
{{hc|/etc/mkinitcpio.d/linux-zen.preset|2=<br />
suffix='-zen'<br />
source /etc/mkinitcpio.d/linux.preset<br />
}}<br />
<br />
==== Using pacman hook ====<br />
<br />
A last option relies on the [[pacman hooks]] that are run at the end of the transaction.<br />
<br />
The first file is a hook that monitors the relevant files, and it is run if they were modified in the former transaction.<br />
<br />
{{hc|/etc/pacman.d/hooks/999-kernel-efi-copy.hook|2=<br />
[Trigger]<br />
Type = Path<br />
Operation = Install<br />
Operation = Upgrade<br />
Target = usr/lib/modules/*/vmlinuz<br />
Target = usr/lib/initcpio/*<br />
Target = boot/*-ucode.img<br />
<br />
[Action]<br />
Description = Copying linux and initramfs to EFI directory...<br />
When = PostTransaction<br />
Exec = /usr/local/bin/kernel-efi-copy.sh<br />
}}<br />
<br />
The second file is the script itself. Create the file and make it [[executable]]:<br />
<br />
{{hc|/usr/local/bin/kernel-efi-copy.sh|2=<br />
#!/bin/sh<br />
#<br />
# Copy kernel and initramfs images to EFI directory<br />
#<br />
<br />
ESP_DIR="''esp''/EFI/arch"<br />
<br />
for file in /boot/vmlinuz*<br />
do<br />
cp -af "$file" "$ESP_DIR/$(basename "$file").efi"<br />
[ $? -ne 0 ] && exit 1<br />
done<br />
<br />
for file in /boot/initramfs*<br />
do<br />
cp -af "$file" "$ESP_DIR/"<br />
[ $? -ne 0 ] && exit 1<br />
done<br />
<br />
[ -e /boot/intel-ucode.img ] && cp -af /boot/intel-ucode.img "$ESP_DIR/"<br />
[ -e /boot/amd-ucode.img ] && cp -af /boot/amd-ucode.img "$ESP_DIR/"<br />
<br />
exit 0<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== ESP on software RAID1 ===<br />
<br />
It is possible to make the ESP part of a RAID1 array, but doing so brings the risk of data corruption, and further considerations need to be taken when creating the ESP. See [https://bbs.archlinux.org/viewtopic.php?pid=1398710#p1398710] and [https://bbs.archlinux.org/viewtopic.php?pid=1390741#p1390741] for details and [https://outflux.net/blog/archives/2018/04/19/uefi-booting-and-raid1/ UEFI booting and RAID1] for an in-depth guide with a solution.<br />
<br />
The key part is to use {{ic|--metadata 1.0}} in order to keep the RAID metadata at the end of the partition, otherwise the firmware will not be able to access it:<br />
<br />
# mdadm --create --verbose --level=1 '''--metadata=1.0''' --raid-devices=2 /dev/md/ESP /dev/sda''X'' /dev/sdb''Y''<br />
<br />
=== Firmware does not see the EFI directory ===<br />
<br />
If you give the FAT file system a [[Persistent block device naming#by-label|volume name (i.e. file system label)]], be sure to name it something other than {{ic|EFI}}. That can trigger a bug in some firmwares (due to the volume name matching the EFI directory name) that will cause the firmware to act like the EFI directory does not exist.<br />
<br />
== See also ==<br />
<br />
* [https://blog.uncooperative.org/uefi/linux/shim/efi%20system%20partition/2014/02/06/the-efi-system-partition.html The EFI system partition and the default boot behavior]<br />
* [https://ramsdenj.com/2016/04/15/multi-boot-linux-with-one-boot-partition.html Multi Boot Linux With One Boot Partition | John Ramsden]</div>Jwh7https://wiki.archlinux.org/index.php?title=Dual_boot_with_Windows&diff=754806Dual boot with Windows2022-10-25T17:57:04Z<p>Jwh7: /* UEFI systems */ Mention space-saving option for dual-boot EFI partition, and clarify the section</p>
<hr />
<div>[[Category:Boot process]]<br />
[[Category:Installation process]]<br />
[[fr:Dual boot with Windows]]<br />
[[ja:Windows と Arch のデュアルブート]]<br />
[[pt:Dual boot with Windows]]<br />
[[zh-hans:Dual boot with Windows]]<br />
This is an article detailing different methods of Arch/Windows coexistence.<br />
<br />
== Important information ==<br />
<br />
=== Windows UEFI vs BIOS limitations ===<br />
<br />
Microsoft imposes limitations on which firmware boot mode and partitioning style can be supported based on the version of Windows used:<br />
<br />
{{Note|The following points only list configurations supported by the [[Wikipedia:Windows Setup|Windows Setup]] even though Windows itself may still work on these unsupported configurations. A good example of this is Windows 11 which still works on a BIOS/MBR configuration once the Windows Setup check is bypassed.}}<br />
<br />
* '''Windows XP''' both '''x86 32-bit''' and '''x86_64''' (also called x64) (RTM and all Service Packs) versions do not support booting in [[UEFI]] mode (IA32 or x86_64) from any disk ([[MBR]] or [[GPT]]) OR in BIOS mode from GPT disk. They support only BIOS boot and only from MBR disk.<br />
* '''Windows Vista''' or '''7''' '''x86 32-bit''' (RTM and all Service Packs) versions support booting in BIOS mode from MBR disks only, not from GPT disks. They do not support x86_64 UEFI or IA32 (x86 32-bit) UEFI boot. They support only BIOS boot and only from MBR disk.<br />
* '''Windows Vista RTM x86_64''' (only RTM) version support booting in BIOS mode from MBR disks only, not from GPT disks. It does not support x86_64 UEFI or IA32 (x86 32-bit) UEFI boot. It supports only BIOS boot and only from MBR disk.<br />
* '''Windows Vista''' (SP1 and above, not RTM) and '''Windows 7''' '''x86_64''' versions support booting in x86_64 UEFI mode from GPT disk only, OR in BIOS mode from MBR disk only. They do not support IA32 (x86 32-bit) UEFI boot from GPT/MBR disk, x86_64 UEFI boot from MBR disk, or BIOS boot from GPT disk.<br />
* '''Windows 8/8.1''' and '''10''' '''x86 32-bit''' support booting in IA32 UEFI mode from GPT disk only, OR in BIOS mode from MBR disk only. They do not support x86_64 UEFI boot from GPT/MBR disk, x86_64 UEFI boot from MBR disk, or BIOS boot from GPT disk. On market, the only systems known to ship with IA32 (U)EFI are some old Intel Macs (pre-2010 models?) and Intel Atom System-on-Chip (Clover trail and Bay Trail) Windows Tablets, which boot ONLY in IA32 UEFI mode and ONLY from GPT disk.<br />
* '''Windows 8/8.1''' and '''10''' '''x86_64''' versions support booting in x86_64 UEFI mode from GPT disk only, OR in BIOS mode from MBR disk only. They do not support IA32 UEFI boot, x86_64 UEFI boot from MBR disk, or BIOS boot from GPT disk.<br />
* '''Windows 11''' only supports '''x86_64''' and a boot in UEFI mode from GPT disk. <br />
<br />
In case of pre-installed Systems:<br />
<br />
* All systems pre-installed with Windows XP, Vista or 7 32-bit, irrespective of Service Pack level, bitness, edition (SKU) or presence of UEFI support in firmware, boot in BIOS/MBR mode by default.<br />
* MOST of the systems pre-installed with Windows 7 x86_64, irrespective of Service Pack level, bitness or edition (SKU), boot in BIOS/MBR mode by default. Very few recent systems pre-installed with Windows 7 are known to boot in x86_64 UEFI/GPT mode by default.<br />
* ALL systems pre-installed with Windows 8/8.1, 10 and 11 boot in UEFI/GPT mode. Up to Windows 10, the firmware bitness matches the bitness of Windows, ie. x86_64 Windows boot in x86_64 UEFI mode and 32-bit Windows boot in IA32 UEFI mode.<br />
<br />
The best way to detect the boot mode of Windows is to do the following[https://www.eightforums.com/tutorials/29504-bios-mode-see-if-windows-boot-uefi-legacy-mode.html]:<br />
<br />
* Boot into Windows<br />
* Press {{ic|Win+R}} keys to start the Run dialog<br />
* In the Run dialog type {{ic|msinfo32.exe}} and press Enter<br />
* In the '''System Information''' windows, select ''System Summary'' on the left and check the value of '''BIOS mode''' item on the right<br />
* If the value is {{ic|UEFI}}, Windows boots in UEFI/GPT mode. If the value is {{ic|Legacy}}, Windows boots in BIOS/MBR mode.<br />
<br />
In general, Windows forces type of partitioning depending on the firmware mode used, i.e. if Windows is booted in UEFI mode, it can be installed only to a GPT disk. If Windows is booted in Legacy BIOS mode, it can be installed only to an MBR disk. This is a limitation enforced by Windows Setup, and as of April 2014 there is no officially (Microsoft) supported way of installing Windows in UEFI/MBR or BIOS/GPT configuration. Thus Windows only supports either UEFI/GPT boot or BIOS/MBR configuration.<br />
<br />
{{Tip|Windows 10 version 1703 and newer supports converting from BIOS/MBR to UEFI/GPT using [https://docs.microsoft.com/en-us/windows/deployment/mbr-to-gpt MBR2GPT.EXE].}}<br />
<br />
Such a limitation is not enforced by the Linux kernel, but can depend on which [[boot loader]] is used and/or how the boot loader is configured. The Windows limitation should be considered if the user wishes to boot Windows and Linux from the same disk, since installation procedure of boot loader depends on the firmware type and disk [[partitioning]] configuration. In case where Windows and Linux dual boot from the same disk, it is advisable to follow the method used by Windows, ie. either go for UEFI/GPT boot or BIOS/MBR boot. See https://support.microsoft.com/kb/2581408 for more information.<br />
<br />
=== Install media limitations ===<br />
<br />
Intel Atom System-on-Chip Tablets (Clover trail and Bay Trail) provide only IA32 UEFI firmware without Legacy BIOS (CSM) support (unlike most of the x86_64 UEFI systems), due to Microsoft Connected Standby Guidelines for OEMs. Due to lack of Legacy BIOS support in these systems, and the lack of 32-bit UEFI boot in Arch Official Install ISO ({{Bug|53182}}), the official install media cannot boot on these systems. See [[Unified Extensible Firmware Interface#UEFI firmware bitness]] for more information and available workarounds.<br />
<br />
=== Bootloader UEFI vs BIOS limitations ===<br />
<br />
Most of the linux bootloaders installed for one firmware type cannot launch or chainload bootloaders of the other firmware type. That is, if Arch is installed in UEFI/GPT or UEFI/MBR mode in one disk and Windows is installed in BIOS/MBR mode in another disk, the UEFI bootloader used by Arch cannot chainload the BIOS installed Windows in the other disk. Similarly if Arch is installed in BIOS/MBR or BIOS/GPT mode in one disk and Windows is installed in UEFI/GPT in another disk , the BIOS bootloader used by Arch cannot chainload UEFI installed Windows in the other disk. <br />
<br />
The only exceptions to this are [[GRUB]] in Apple Macs in which GRUB in UEFI mode can boot BIOS installed OS via {{ic|appleloader}} command (does not work in non-Apple systems), and [[rEFInd]] which technically supports booting legacy BIOS OS from UEFI systems, but [https://rodsbooks.com/refind/using.html#legacy does not always work in non-Apple UEFI systems] as per its author Rod Smith. <br />
<br />
However if Arch is installed in BIOS/GPT in one disk and Windows is installed in BIOS/MBR mode in another disk, then the BIOS boot loader used by Arch CAN boot the Windows in the other disk, if the boot loader itself has the ability to chainload from another disk. <br />
<br />
{{Note|To dual-boot with Windows on same disk, Arch should follow the same firmware boot mode and partitioning combination used by the Windows installation.}}<br />
<br />
[[Wikipedia:Windows Setup|Windows Setup]] creates a 100 MiB [[EFI system partition]] (except for [[Advanced Format]] 4K native drives where it creates a 300 MiB ESP), so multiple [[kernel]] usage is limited. Workarounds include:<br />
<br />
* Mount ESP to {{ic|/efi}} and use a [[boot loader]] that has file system drivers and is capable of launching kernels that reside on other partitions.<br />
* Expand the EFI system partition, typically either by decreasing the Recovery partition size or moving the Windows partition ('''UUIDs will change''').<br />
* Backup and delete unneeded fonts in {{ic|''esp''/EFI/Microsoft/Boot/Fonts/}} [https://support.microsoft.com/en-us/help/3086249/we-couldn-t-update-system-reserved-partition-error-installing-windows].<br />
* Backup and delete unneeded language directories in {{ic|''esp''/EFI/Microsoft/Boot/}} (e.g. to only keep {{ic|en-US}}).<br />
<br />
=== UEFI Secure Boot ===<br />
<br />
All pre-installed Windows 8/8.1, 10 and 11 systems by default boot in UEFI/GPT mode and have UEFI Secure Boot enabled by default. This is mandated by Microsoft for all OEM pre-installed systems.<br />
<br />
Arch Linux install media does not support Secure Boot yet. See [[Secure Boot#Booting an installation medium]]. <br />
<br />
It is advisable to disable UEFI Secure Boot in the firmware setup manually before attempting to boot Arch Linux. Windows 8/8.1, 10 and 11 SHOULD continue to boot fine even if Secure boot is disabled. The only issue with regards to disabling UEFI Secure Boot support is that it requires physical access to the system to disable secure boot option in the firmware setup, as Microsoft has explicitly forbidden presence of any method to remotely or programmatically (from within OS) disable secure boot in all Windows 8/8.1 and above pre-installed systems<br />
<br />
{{Note|<br />
* If Windows used Bitlocker and stored the key in the TPM for automatic unlock on boot, it fails to boot when Secure Boot is disabled, instead showing a Bitlocker recovery screen. This is not permanent however, and you can easily boot Windows again by simply re-enabling Secure Boot.<br />
* On Windows 11, disabling Secure Boot prevents Windows Hello, WSM (Windows Subsystem for Android) and Windows Updates from working}}<br />
<br />
=== Fast Startup and hibernation ===<br />
<br />
There are two OSs that can be hibernated, you can hibernate Windows and boot Linux (or another OS), or you can hibernate Linux and boot Windows, or hibernate both OSs.<br />
<br />
{{Warning|Data loss can occur if Windows hibernates and you dual boot into another OS and make changes to files on a filesystem (such as NTFS) that can be read and written to by Windows and Linux, and that has been mounted by Windows [https://superuser.com/questions/39532/hibernating-and-booting-into-another-os-will-my-filesystems-be-corrupted/136814#136814]. Similarly, data loss can occur if Linux hibernates, and you dual boot into another OS etc. Windows may hibernate even when you press shutdown, see section [[#Windows settings]].}}<br />
<br />
For the same reason, if you share one EFI System Partition between Windows and Linux, then the EFI System Partition may be damaged if you hibernate (or shutdown with Fast Startup enabled) Windows and then start Linux, or hibernate Linux and then start Windows.<br />
<br />
{{Pkg|ntfs-3g}} added a [https://sourceforge.net/p/ntfs-3g/ntfs-3g/ci/559270a8f67c77a7ce51246c23d2b2837bcff0c9/ safe-guard] to prevent read-write mounting of hibernated NTFS filesystems, but the NTFS driver within the Linux kernel has no such safeguard.<br />
<br />
Windows cannot read filesystems such as ext4 by default that are commonly used for Linux. These filesystems do not have to be considered, unless you install a Windows driver for them.<br />
<br />
==== Windows settings ====<br />
<br />
Fast Startup is a feature in Windows 8 and above that hibernates the computer rather than actually shutting it down to speed up boot times.<br />
<br />
There are multiple options regarding the Windows settings for Fast Startup and hibernation that are covered in the next sections.<br />
* disable Fast Startup and disable hibernation<br />
* disable Fast Startup and enable hibernation<br />
* enable Fast Startup and enable hibernation<br />
<br />
The procedure of disabling Fast Startup is described in the tutorials for [https://www.eightforums.com/tutorials/6320-fast-startup-turn-off-windows-8-a.html Windows 8], [https://www.tenforums.com/tutorials/4189-turn-off-fast-startup-windows-10-a.html Windows 10] and [https://www.elevenforum.com/t/turn-on-or-off-fast-startup-in-windows-11.1212/ Windows 11]. In any case if you disable a setting, make sure to disable the setting and then shut down Windows, before installing Linux; note that rebooting is not sufficient.<br />
<br />
===== Disable Fast Startup and disable hibernation =====<br />
<br />
This is the safest option, and recommended if you are unsure about the issue, as it requires the least amount of user awareness when rebooting from one OS into the other. You may share the same EFI System Partition between Windows and Linux.<br />
<br />
===== Disable Fast Startup and enable hibernation =====<br />
<br />
This option requires user awareness when rebooting from one OS into the other.<br />
If you want to start Linux while Windows is hibernated, which is a common use case, then<br />
* you must use a separate EFI System Partition (ESP) for Windows and Linux, and ensure that Windows does not mount the ESP used for Linux. As there can only be one ESP per drive, the ESP used for Linux must be located on a separate drive than the ESP used for Windows. In this case Windows and Linux can still be installed on the same drive in different partitions, if you place the ESP used by linux on another drive than the Linux root partition.<br />
* you can not read-write mount any filesystem in Linux, that is mounted by Windows while Windows is hibernated. You should be extremely careful about this, and also consider [[Automount]] behaviour.<br />
* If you shut down Windows fully, rather than hibernating, then you can read-write mount the filesystem.<br />
<br />
{{Note|You can avoid this issue for a drive by mounting a drive as an external drive in Windows and ejecting the drive in Windows before hibernating.}}<br />
<br />
===== Enable Fast Startup and enable hibernation =====<br />
<br />
The same considerations apply as in case "Disable Fast Startup and enable hibernation", but since Windows can not be shut down fully, only hibernated, you can never read-write mount any filesystem that was mounted by Windows while Windows is hibernated.<br />
<br />
{{Note|Windows updates may re-enable Fast Startup, as reported in [https://tedstechshack.com/2017/07/03/warning-multi-booting-uefi-system-windows-10-fast-startup-doubt-reboot/].}}<br />
<br />
=== Windows filenames limitations ===<br />
<br />
Windows is limited to filepaths being shorter than [https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#maximum-path-length-limitation 260 characters].<br />
<br />
Windows also puts [https://msdn.microsoft.com/en-us/library/aa365247(VS.85).aspx#naming_conventions certain characters off limits] in filenames for reasons that run all the way back to DOS:<br />
<br />
* {{ic|<}} (less than)<br />
* {{ic|>}} (greater than)<br />
* {{ic|:}} (colon)<br />
* {{ic|"}} (double quote)<br />
* {{ic|/}} (forward slash)<br />
* {{ic|\}} (backslash)<br />
* {{ic|{{!}}}} (vertical bar or pipe)<br />
* {{ic|?}} (question mark)<br />
* {{ic|*}} (asterisk)<br />
<br />
These are limitations of Windows and not NTFS: any other OS using the NTFS partition will be fine. Windows will fail to detect these files and running {{ic|chkdsk}} will most likely cause them to be deleted. This can lead to potential data-loss.<br />
<br />
[[NTFS-3G]] applies Windows restrictions to new file names through the {{ic|windows_names}} option: {{man|8|ntfs-3g|Windows_Filename_Compatibility}} (see [[fstab]]).<br />
<br />
== Installation ==<br />
<br />
The recommended way to setup a Linux/Windows dual booting system is to first install Windows, only using part of the disk for its partitions. When you have finished the Windows setup, boot into the Linux install environment where you can create and resize partitions for Linux while leaving the existing Windows partitions untouched. The Windows installation will create the [[EFI system partition]] which can be used by your Linux [[boot loader]].<br />
<br />
=== Windows before Linux ===<br />
<br />
==== BIOS systems ====<br />
<br />
===== Using a Linux boot loader =====<br />
<br />
You may use any multi-boot supporting BIOS [[boot loader]].<br />
<br />
===== Using the Windows Vista/7/8/8.1 boot loader =====<br />
<br />
This section explains how to : install a linux bootloader on a partition instead of the MBR ; copy this bootloader to a partition readable by the windows bootloader ; use the windows bootloader to start said copy of the linux bootloader. <br />
<br />
{{Note|Some documents state that the partition being loaded by the Windows boot loader must be a primary partition but usage of an extended partition has been documented as working.}}<br />
<br />
* When installing the boot loader, install it on your {{ic|/boot}} partition rather than the MBR. For details on doing this with GRUB, see [[GRUB/Tips and tricks#Install to partition or partitionless disk]], for Syslinux, see the note at [[Syslinux#Manual install]], for LILO see [[LILO#Install to partition or partitionless disk]].<br />
<br />
* Make a copy of the VBR: {{bc|1=dd if=/dev/''disk'' of=''/path/to/''linux.bin bs=512 count=1}} where {{ic|/dev/''disk''}} is the path of the partition on which your bootloader is installed and {{ic|/path/to/}} is the mounted filesystem on which you want the copy to be readable by the Windows bootloader. <br />
<br />
* On Windows, the linux.bin file should now be accessible. Run '''cmd''' with administrator privileges (navigate to ''Start > All Programs > Accessories'', right-click on ''Command Prompt'' and select ''Run as administrator''): {{bc|bcdedit /create /d "Linux" /application BOOTSECTOR}} BCDEdit will return a [[wikipedia:Universally_unique_identifier|UUID]] for this entry. This will be refered to as {{ic|''UUID''}} in the remaining steps. {{bc|1=bcdedit /set ''UUID'' device partition=c: (or the drive letter on which linux.bin is kept)<nowiki> <br />
</nowiki>bcdedit /set ''UUID'' path ''\path\to\''linux.bin<nowiki> <br />
</nowiki>bcdedit /displayorder ''UUID'' /addlast<nowiki> <br />
</nowiki>bcdedit /timeout 30}}<br />
<br />
On reboot, both Windows and Linux should now show up in the Windows bootloader. <br />
<br />
{{Note|On some hardware, the Windows boot loader is used to start another OS with a second power button (e.g. Dell Precision M4500).}}<br />
<br />
For more details, see https://www.iceflatline.com/2009/09/how-to-dual-boot-windows-7-and-linux-using-bcdedit/<br />
<br />
==== UEFI systems ====<br />
<br />
If you already have Windows installed, it will already have created some partitions on a [[GPT]]-formatted disk:<br />
<br />
* a [[Wikipedia:Windows Recovery Environment|Windows Recovery Environment]] partition, generally of size 499 MiB, containing the files required to boot Windows (i.e. the equivalent of Linux's {{ic|/boot}}),<br />
* an [[EFI system partition]] with a [[FAT32]] filesystem,<br />
* a [[Wikipedia:Microsoft Reserved Partition|Microsoft Reserved Partition]], generally of size 128 MiB,<br />
* a Microsoft basic data partition with a NTFS filesystem, which corresponds to {{ic|C:}},<br />
* potentially system recovery and backup partitions and/or secondary data partitions (corresponding often to {{ic|D:}} and above).<br />
<br />
Using the Disk Management utility in Windows, check how the partitions are labelled and which type gets reported. This will help you understand which partitions are essential to Windows, and which others you might repurpose. The Windows Disk Management utility can also be used to shrink Windows (NTFS) partitions to free up disk space for additional partitions for Linux.<br />
<br />
{{Warning|The first 4 partitions in the above list are essential, do not delete them.}}<br />
<br />
You can then proceed with [[partitioning]], depending on your needs. The boot loader needs to support chainloading other EFI applications to do dual boot Windows / Linux. An additional EFI system partition should not be created, as it may [https://support.microsoft.com/en-us/help/2879602/unable-to-boot-if-more-than-one-efi-system-partition-is-present prevent Windows from booting].<br />
<br />
{{Note|It only appears when Linux is installed on the second hard disk and a new EFI system partition is created on the second hard disk.}}<br />
<br />
Simply [[EFI system partition#Mount the partition|mount the existing partition]]. To save EFI partition space, especially for multiple kernels, use zstd for initramfs generation (the default) with the '--long' [[Mkinitcpio#COMPRESSION_OPTIONS|compression option]]. The '-v' option may also be desired to see more details. <br />
<br />
{{Tip|[[rEFInd]] and [[systemd-boot]] will autodetect ''Windows Boot Manager'' ({{ic|\EFI\Microsoft\Boot\bootmgfw.efi}}) and show it in their boot menu automatically. For [[GRUB]] follow either [[GRUB#Windows installed in UEFI/GPT mode]] to add boot menu entry manually or [[GRUB#Detecting other operating systems]] for a generated configuration file.}}<br />
<br />
Computers that come with newer versions of Windows often have [[Secure Boot]] enabled. You will need to take extra steps to either disable Secure Boot or to make your installation media compatible with secure boot (see above and in the linked page).<br />
<br />
=== Linux before Windows ===<br />
<br />
Even though the recommended way to setup a Linux/Windows dual booting system is to first install Windows, it can be done the other way around. In contrast to installing Windows before Linux, you will have to set aside a partition for Windows, say 40GB or larger, in advance. Or have some unpartitioned disk space, or create and resize partitions for Windows from within the Linux installation, before launching the Windows installation.<br />
<br />
==== UEFI firmware ====<br />
<br />
Windows will use the already existing [[EFI system partition]]. In contrast to what was [[#UEFI systems|stated earlier]], it is unclear if a single partition for Windows, without the Windows Recovery Environment and without Microsoft Reserved Partition, will not do.<br />
<br />
Follows an outline, assuming [[Secure Boot]] is disabled in the firmware.<br />
<br />
# Boot into windows installation. Watch to let it use only the intended partition, but otherwise let it do its work as if there is no Linux installation.<br />
# Follow the [[#Fast Startup and hibernation]] section.<br />
# Fix the ability to load Linux at start up, perhaps by following [[#Cannot boot Linux after installing Windows]]. It was already mentioned in [[#UEFI systems]] that some Linux boot managers will autodetect ''Windows Boot Manager''. Even though newer Windows installations have an advanced restart option, from which you can boot into Linux, it is advised to have other means to boot into Linux, such as an arch installation media or a live CD.<br />
<br />
===== Windows 10 with GRUB =====<br />
<br />
The following assumes [[GRUB]] is used as a boot loader (although the process is likely similar for other boot loaders) and that Windows 10 will be installed on a GPT block device with an existing EFI system partition (see the "System partition" section in the [https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/configure-uefigpt-based-hard-drive-partitions Microsoft documentation] for more information).<br />
<br />
Create with program {{ic|gdisk}} on the block device the following three new partitions. See [https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/configure-uefigpt-based-hard-drive-partitions] for more precise partition sizes.<br />
<br />
{| class="wikitable"<br />
! Min size !! Code !! Name !! File system<br />
|-<br />
| 16 MB || 0C01 || Microsoft reserved || N/A<br />
|-<br />
| ~40 GB || 0700 || Microsoft basic data || NTFS<br />
|-<br />
| 300 MB || 2700 || Windows RE || NTFS<br />
|-<br />
|}<br />
<br />
Create NTFS file systems on the new Microsoft basic data and Windows RE (recovery) partitions using the ''mkntfs'' program from package {{Pkg|ntfs-3g}}.<br />
<br />
Reboot the system into a Windows 10 installation media. When prompted to install select the custom install option and install Windows on the Microsoft basic data partition created earlier. This should also install Microsoft EFI files in the EFI partition.<br />
<br />
After installation (set up of and logging into Windows not required), reboot into Linux and [[GRUB#Generate the main configuration file|generate a GRUB configuration]] for the Windows boot manager to be available in the GRUB menu on next boot.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Couldn't create a new partition or locate an existing one ====<br />
<br />
See [[#Windows UEFI vs BIOS limitations]].<br />
<br />
==== Cannot boot Linux after installing Windows ====<br />
<br />
See [[Unified Extensible Firmware Interface#Windows changes boot order]].<br />
<br />
==== Restoring a Windows boot record ====<br />
<br />
By convention (and for ease of installation), Windows is usually installed on the first partition and installs its partition table and reference to its bootloader to the first sector of that partition. If you accidentally install a bootloader like GRUB to the Windows partition or damage the boot record in some other way, you will need to use a utility to repair it. Microsoft includes a boot sector fix utility {{Ic|FIXBOOT}} and an MBR fix utility called {{Ic|FIXMBR}} on their recovery discs, or sometimes on their install discs. Using this method, you can fix the reference on the boot sector of the first partition to the bootloader file and fix the reference on the MBR to the first partition, respectively. After doing this you will have to [[GRUB#Installation|reinstall GRUB]] to the MBR as was originally intended (that is, the GRUB bootloader can be assigned to chainload the Windows bootloader).<br />
<br />
If you wish to revert back to using Windows, you can use the {{Ic|FIXBOOT}} command which chains from the MBR to the boot sector of the first partition to restore normal, automatic loading of the Windows operating system.<br />
<br />
Of note, there is a Linux utility called {{Ic|ms-sys}} (package {{AUR|ms-sys}} in AUR) that can install MBR's. However, this utility is only currently capable of writing new MBRs (all OS's and file systems supported) and boot sectors (a.k.a. boot record; equivalent to using {{Ic|FIXBOOT}}) for FAT file systems. Most LiveCDs do not have this utility by default, so it will need to be installed first, or you can look at a rescue CD that does have it, such as [https://partedmagic.com/ Parted Magic].<br />
<br />
First, write the partition info (table) again by:<br />
<br />
# ms-sys --partition /dev/sda1<br />
<br />
Next, write a Windows 2000/XP/2003 MBR:<br />
<br />
# ms-sys --mbr /dev/sda # Read options for different versions<br />
<br />
Then, write the new boot sector (boot record):<br />
<br />
# ms-sys -(1-6) # Read options to discover the correct FAT record type<br />
<br />
{{Ic|ms-sys}} can also write Windows 98, ME, Vista, and 7 MBRs as well, see {{Ic|ms-sys -h}}.<br />
<br />
==== The EFI system partition created by Windows Setup is too small ====<br />
<br />
[[Wikipedia:Windows Setup|Windows Setup]] creates a 100 MiB [[EFI system partition]] (except for [[Advanced Format]] 4K native drives where it creates a 300 MiB ESP). This is generally too small to fit everything you need. You can try different tools to resize this partition, but there are usually other partitions in the way, making it, at the very least, difficult. One option is to use the Arch install media to create a single [[EFI system partition]] of your preferred size '''before''' you install Windows on the drive. Windows Setup will use the EFI system partition you made instead of creating its own.<br />
<br />
== Time standard ==<br />
<br />
* Recommended: Set both Arch Linux and Windows to use UTC, following [[System time#UTC in Microsoft Windows]]. Some versions of Windows revert the hardware clock back to ''localtime'' if they are set to synchronize the time online. This issue appears to be fixed in Windows 10.<br />
* Not recommended: Set Arch Linux to ''localtime'' and disable all [[System time#Time synchronization|time synchronization daemons]]. This will let Windows take care of hardware clock corrections and you will need to remember to boot into Windows at least two times a year (in Spring and Autumn) when [[Wikipedia:Daylight saving time|DST]] kicks in. So please do not ask on the forums why the clock is one hour behind or ahead if you usually go for days or weeks without booting into Windows.<br />
<br />
== Bluetooth pairing ==<br />
<br />
When it comes to pairing Bluetooth devices with both the Linux and Windows installation, both systems have the same MAC address, but will use different link keys generated during the pairing process. This results in the device being unable to connect to one installation, after it has been paired with the other. To allow a device to connect to either installation without re-pairing, follow [[Bluetooth#Dual boot pairing]].<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=140049 Booting Windows from a desktop shortcut]<br />
* [https://github.com/kaipee/grub-reboot2win One-time boot into Windows partition from desktop shortcut]<br />
* [https://github.com/ValdikSS/windows2usb Windows 7/8/8.1/10 ISO to Flash Drive burning utility for Linux (MBR/GPT, BIOS/UEFI, FAT32/NTFS)]</div>Jwh7https://wiki.archlinux.org/index.php?title=Mkinitcpio&diff=754804Mkinitcpio2022-10-25T17:40:29Z<p>Jwh7: /* COMPRESSION_OPTIONS */ Mention zstd's --long option</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Initramfs]]<br />
[[Category:Kernel]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[de:Mkinitcpio]]<br />
[[fr:Mkinitcpio]]<br />
[[ja:Mkinitcpio]]<br />
[[pt:Mkinitcpio]]<br />
[[ru:Mkinitcpio]]<br />
[[zh-hans:Mkinitcpio]]<br />
{{Related articles start}}<br />
{{Related|Booster}}<br />
{{Related|Boot debugging}}<br />
{{Related|dracut}}<br />
{{Related|Kernel modules}}<br />
{{Related|mkinitcpio/Minimal initramfs}}<br />
{{Related|systemd}}<br />
{{Related articles end}}<br />
[https://github.com/archlinux/mkinitcpio mkinitcpio] is a Bash script used to create an [[Wikipedia:Initial ramdisk|initial ramdisk]] environment. From the {{man|8|mkinitcpio}} man page:<br />
<br />
:The initial ramdisk is in essence a very small environment (early userspace) which loads various kernel modules and sets up necessary things before handing over control to {{ic|init}}. This makes it possible to have, for example, encrypted root file systems and root file systems on a software RAID array. ''mkinitcpio'' allows for easy extension with custom hooks, has autodetection at runtime, and many other features.<br />
<br />
Traditionally, the kernel was responsible for all hardware detection and initialization tasks early in the [[boot process]] before mounting the root file system and passing control to {{ic|init}}. However, as technology advances, these tasks have become increasingly complex. <br />
<br />
Nowadays, the root file system may be on a wide range of hardware, from SCSI to SATA to USB drives, controlled by a variety of drive controllers from different manufacturers. Additionally, the root file system may be encrypted or compressed; within a software RAID array or a logical volume group. The simple way to handle that complexity is to pass management into userspace: an initial ramdisk. See also: [https://web.archive.org/web/20150430223035/http://archlinux.me/brain0/2010/02/13/early-userspace-in-arch-linux/ /dev/brain0 » Blog Archive » Early Userspace in Arch Linux].<br />
<br />
''mkinitcpio'' has been developed by the Arch Linux developers and from community contributions. See the [https://github.com/archlinux/mkinitcpio public Git repository].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mkinitcpio}} package, which is a dependency of the {{Pkg|linux}} package, so most users will already have it installed.<br />
<br />
Advanced users may wish to install the latest development version of ''mkinitcpio'' from Git with the {{AUR|mkinitcpio-git}} package.<br />
<br />
{{Note|It is '''highly''' recommended that you follow the [https://lists.archlinux.org/mailman3/lists/arch-projects.lists.archlinux.org/ arch-projects mailing list] if you use ''mkinitcpio'' from Git!}}<br />
<br />
== Image creation and activation ==<br />
<br />
=== Automated generation ===<br />
<br />
Every time a kernel is installed or upgraded, a [[pacman hook]] automatically generates a ''.preset'' file saved in {{ic|/etc/mkinitcpio.d/}}. For example {{ic|linux.preset}} for the official stable {{Pkg|linux}} kernel package. A preset is simply a list of information required to create initial ramdisk images, instead of manually specifying the various parameters and the location of the output files.<br />
By default, it contains the instructions to create two images:<br />
<br />
# the ''default'' ramdisk image created following the directives specified in the mkinitcpio [[#Configuration]], and<br />
# the ''fallback'' ramdisk image, same as above except that the ''autodetect'' hook is skipped during creation, thus including a full range of modules which supports most systems.<br />
<br />
After creating the preset, the pacman hook calls the ''mkinitcpio'' script which generates the two images, using the information provided in the preset.<br />
<br />
{{Note|''.preset'' files are used to automatically regenerate the initramfs after a kernel update; be careful when editing them.}}<br />
<br />
=== Manual generation ===<br />
<br />
To run the script manually, refer to the {{man|8|mkinitcpio}} manual page for instructions. In particular, to (re-)generate the preset provided by a kernel package, use the {{ic|-p}}/{{ic|--preset}} option followed by the preset to utilize. For example, for the {{Pkg|linux}} package, use the command:<br />
<br />
# mkinitcpio -p linux<br />
<br />
To (re-)generate all existing presets, use the {{ic|-P}}/{{ic|--allpresets}} switch. This is typically used to regenerate all the initramfs images after a change of the global [[#Configuration]]:<br />
<br />
# mkinitcpio -P<br />
<br />
Users may create any number of initramfs images with a variety of different configurations. The desired image must be specified in the respective [[boot loader]] configuration file.<br />
<br />
=== Customized generation ===<br />
<br />
Users can generate an image using an alternative configuration file. For example, the following will generate an initial ramdisk image according to the directions in {{ic|/etc/mkinitcpio-custom.conf}} and save it as {{ic|/boot/initramfs-custom.img}}.<br />
<br />
# mkinitcpio --config /etc/mkinitcpio-custom.conf --generate /boot/initramfs-custom.img<br />
<br />
If generating an image for a kernel other than the one currently running, add the kernel release version to the command line. The installed kernel releases can be found in {{ic|/usr/lib/modules/}}, the syntax is consistent with the output of the command {{ic|uname -r}} for each kernel.<br />
<br />
# mkinitcpio --generate /boot/initramfs-custom2.img --kernel 5.7.12-arch1-1<br />
<br />
=== Unified kernel images ===<br />
<br />
As of version 31, ''mkinitpcio'' can also create [[unified kernel image]]s.<br />
<br />
== Configuration ==<br />
<br />
The primary configuration file for ''mkinitcpio'' is {{ic|/etc/mkinitcpio.conf}}. Additionally, preset definitions are provided by kernel packages in the {{ic|/etc/mkinitcpio.d}} directory (e.g. {{ic|/etc/mkinitcpio.d/linux.preset}}).<br />
<br />
Users can modify six variables within the configuration file, see {{man|5|mkinitcpio.conf}} for more details:<br />
<br />
; {{ic|MODULES}}: Kernel modules to be loaded before any boot hooks are run. <br />
; {{ic|BINARIES}}: Additional binaries to be included in the initramfs image.<br />
; {{ic|FILES}}: Additional files to be included in the initramfs image.<br />
; {{ic|HOOKS}}: Hooks are scripts that execute in the initial ramdisk.<br />
; {{ic|COMPRESSION}}: Used to compress the initramfs image.<br />
; {{ic|COMPRESSION_OPTIONS}}: Extra arguments to pass to the {{ic|COMPRESSION}} program. Usage of this setting is strongly discouraged. ''mkinitcpio'' will handle special requirements for compressors (e.g. passing {{ic|1=--check=crc32}} to xz), and misusage can easily lead to an unbootable system.<br />
<br />
{{Note|<br />
* Some hooks that may be required for your system like '''lvm2''', '''mdadm_udev''', and '''encrypt''' are '''NOT''' enabled by default. Read the [[#HOOKS]] section carefully for instructions.<br />
* Users with multiple hardware disk controllers that use the same node names but different kernel modules (e.g. two SCSI/SATA or two IDE controllers) should use [[persistent block device naming]] to ensure that the right devices are mounted. Otherwise, the root device location may change between boots, resulting in kernel panics.<br />
}}<br />
<br />
=== MODULES ===<br />
<br />
The {{ic|MODULES}} array is used to specify modules to load before anything else is done.<br />
<br />
Modules suffixed with a {{ic|?}} will not throw errors if they are not found. This might be useful for custom kernels that compile in modules which are listed explicitly in a hook or configuration file.<br />
<br />
{{Note|<br />
* If using '''reiser4''', it ''must'' be added to the {{ic|MODULES}} array.<br />
* When using the '''encrypt''' or '''sd-encrypt''' hook, the keyboard modules and/or filesystems needed to unlock the LUKS device during system boot need to be added to the {{ic|MODULES}} array when the target system differs from the one used to run ''mkinitcpio''. For example, if you use a keyfile on an ext2 file system but no ext2 file system is mounted at the time ''mkinitcpio'' runs, add {{ic|ext2}}. See [[dm-crypt/System configuration#cryptkey]] for more details.<br />
* If using a keyboard through a USB 3 hub and wish to use it to unlock a LUKS device, add {{ic|usbhid xhci_hcd}}.<br />
* If using displays connected to a docking station, you might need to add a module for your graphic card to make initrd output visible (e.g. {{ic|i915}} for most Intel cards).<br />
}}<br />
<br />
=== BINARIES and FILES ===<br />
<br />
These options allow users to add files to the image. Both {{ic|BINARIES}} and {{ic|FILES}} are added before hooks are run, and may be used to override files used or provided by a hook. {{ic|BINARIES}} are auto-located within a standard {{ic|PATH}} and are dependency-parsed, meaning any required libraries will also be added. {{ic|FILES}} are added ''as-is''. For example:<br />
<br />
FILES=(/etc/modprobe.d/modprobe.conf)<br />
<br />
BINARIES=(kexec)<br />
<br />
Note that as both {{ic|BINARIES}} and {{ic|FILES}} are [[Bash]] arrays, multiple entries can be added delimited with spaces.<br />
<br />
=== HOOKS ===<br />
<br />
The {{ic|HOOKS}} array is the most important setting in the file. Hooks are small scripts which describe what will be added to the image. For some hooks, they will also contain a runtime component which provides additional behavior, such as starting a daemon, or assembling a stacked block device. Hooks are referred to by their name, and executed in the order they exist in the {{ic|HOOKS}} array of the configuration file.<br />
<br />
The default {{ic|HOOKS}} setting should be sufficient for most simple, single disk setups. For root devices which are stacked or multi-block devices such as [[LVM]], [[RAID]], or [[dm-crypt]], see the respective wiki pages for further necessary configuration.<br />
<br />
==== Build hooks ====<br />
<br />
Build hooks are found in {{ic|/usr/lib/initcpio/install/}}, custom build hooks can be placed in {{ic|/etc/initcpio/install/}}. These files are sourced by the bash shell during runtime of ''mkinitcpio'' and should contain two functions: {{ic|build}} and {{ic|help}}. The {{ic|build}} function describes the modules, files, and binaries which will be added to the image. An API, documented by {{man|8|mkinitcpio}}, serves to facilitate the addition of these items. The {{ic|help}} function outputs a description of what the hook accomplishes.<br />
<br />
For a list of all available hooks:<br />
<br />
$ mkinitcpio -L<br />
<br />
Use ''mkinitcpio'''s {{ic|-H}}/{{ic|--hookhelp}} option to output help for a specific hook, for example:<br />
<br />
$ mkinitcpio -H udev<br />
<br />
==== Runtime hooks ====<br />
<br />
Runtime hooks are found in {{ic|/usr/lib/initcpio/hooks/}}, custom runtime hooks can be placed in {{ic|/etc/initcpio/hooks/}}. For any runtime hook, there should always be a build hook of the same name, which calls {{ic|add_runscript}} to add the runtime hook to the image. These files are sourced by the busybox ash shell during early userspace. With the exception of cleanup hooks, they will always be run in the order listed in the {{ic|HOOKS}} setting. Runtime hooks may contain several functions:<br />
<br />
{{ic|run_earlyhook}}: Functions of this name will be run once the API file systems have been mounted and the kernel command line has been parsed. This is generally where additional daemons, such as udev, which are needed for the early boot process are started from.<br />
<br />
{{ic|run_hook}}: Functions of this name are run shortly after the early hooks. This is the most common hook point, and operations such as assembly of stacked block devices should take place here.<br />
<br />
{{ic|run_latehook}}: Functions of this name are run after the root device has been mounted. This should be used, sparingly, for further setup of the root device, or for mounting other file systems, such as {{ic|/usr}}.<br />
<br />
{{ic|run_cleanuphook}}: Functions of this name are run as late as possible, and in the reverse order of how they are listed in the {{ic|HOOKS}} array in the configuration file. These hooks should be used for any last minute cleanup, such as shutting down any daemons started by an early hook.<br />
<br />
{{Note|Runtime hooks are only used by busybox init. '''systemd''' hook triggers a systemd based init, which does not run any runtime hooks but uses systemd units instead.}}<br />
<br />
==== Common hooks ====<br />
<br />
A table of common hooks and how they affect image creation and runtime follows. Note that this table is not complete, as packages can provide custom hooks.<br />
<br />
{{Expansion|Add info about {{ic|hostdata}}, {{ic|memdisk}}, {{ic|sleep}} and {{ic|strip}}, find out if {{ic|dmraid}}, etc. work/are needed for systemd based initramfs.|section=Improvements for the Common hooks table and section about systemd hook}}<br />
<br />
{| class="wikitable"<br />
! busybox init !! systemd init !! [[#Build hooks|Build hook]] !! [[#Runtime hooks|Runtime hook]] (busybox init only)<br />
|-<br />
|colspan="2" {{C|'''base'''}} || Sets up all initial directories and installs base utilities and libraries. Always keep this hook as the first hook unless you know what you are doing, as it provides critical busybox init when not using '''systemd''' hook. <br/>Optional when using the '''systemd''' hook as it only provides a busybox recovery shell. {{Note|The recovery shell is not usable since the root account in the initramfs is [https://github.com/archlinux/svntogit-packages/commit/776743d220cbb56e9abca2cc8bcef3a0ab7c8d0a locked]. See {{Bug|70408}}.}}<br />
| {{-}}<br />
|-<br />
| {{C|'''udev'''}} ||rowspan="3" {{C|'''systemd'''}} || Adds udevd, udevadm, and a small subset of udev rules to your image. || Starts the udev daemon and processes uevents from the kernel; creating device nodes. As it simplifies the boot process by not requiring the user to explicitly specify necessary modules, using it is recommended.<br />
|-<br />
| {{C|'''usr'''}} || Adds support for {{ic|/usr}} on a separate partition. See [[#/usr as a separate partition]] for details. || Mounts the {{ic|/usr}} partition after the real root has been mounted.<br />
|-<br />
|-<br />
| {{C|'''resume'''}} || {{-}} || Tries to resume from the "suspend to disk" state. See [[Hibernation]] for further configuration.<br />
|-<br />
| {{C|'''btrfs'''}} || {{Grey|–}} || Sets the required modules to enable [[Btrfs]] for using multiple devices with Btrfs. You need to have {{Pkg|btrfs-progs}} installed to use this. This hook is not required for using Btrfs on a single device. || Runs {{ic|btrfs device scan}} to assemble a multi-device Btrfs root file system when '''udev''' hook or '''systemd''' hook is not present. The {{Pkg|btrfs-progs}} package is required for this hook.<br />
|-<br />
|colspan="2" {{C|'''autodetect'''}} || Shrinks your initramfs to a smaller size by creating a whitelist of modules from a scan of sysfs. Be sure to verify included modules are correct and none are missing. This hook must be run before other subsystem hooks in order to take advantage of auto-detection. Any hooks placed before 'autodetect' will be installed in full. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''modconf'''}} || Includes modprobe configuration files from {{ic|/etc/modprobe.d/}} and {{ic|/usr/lib/modprobe.d/}}. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''kms'''}} || Adds all GPU modules to provide [[Kernel mode setting#Early KMS start|early KMS start]].|| {{-}}<br />
|-<br />
|colspan="2" {{C|'''block'''}} || Adds all block device modules, formerly separately provided by the ''fw'', ''mmc'', ''pata'', ''sata'', ''scsi'', ''usb'', and ''virtio'' hooks. || {{-}}<br />
|-<br />
| {{C|'''net'''}} || {{Grey|''not implemented''}} || Adds the necessary modules for a network device. You must have {{Pkg|mkinitcpio-nfs-utils}} installed to use this, see [[#Using net]] for details. || Provides handling for an NFS-based root file system.<br />
|-<br />
| {{C|'''dmraid'''}} || {{Grey|''?''}} || Provides support for fakeRAID root devices. You must have {{Pkg|dmraid}} installed to use this. Note that it is preferred to use [[mdadm]] with the '''mdadm_udev''' hook with fakeRAID if your controller supports it. See [[#Using RAID]] for details. || Locates and assembles fakeRAID block devices using {{ic|dmraid}}.<br />
|-<br />
|colspan="2" {{C|'''mdadm_udev'''}} || Provides support for assembling RAID arrays via udev. You must have {{Pkg|mdadm}} installed to use this. If you use this hook with a FakeRAID array, it is recommended to include {{ic|mdmon}} in {{ic|BINARIES}}. See [[#Using RAID]] for details. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''keyboard'''}} || Adds the necessary modules for keyboard devices. Use this if you have an USB or serial keyboard and need it in early userspace (either for entering encryption passphrases or for use in an interactive shell). As a side effect, modules for some non-keyboard input devices might be added too, but this should not be relied on. Supersedes old ''usbinput'' hook.<br />
<br />
{{Note|For systems that are booted with different hardware configurations (e.g. laptops with external keyboard vs. internal keyboard or [[Wikipedia:Headless computer|headless systems]]), this hook needs to be placed before '''autodetect''' in order to be able to use the keyboard at boot time, for example to unlock an encrypted device when using the {{ic|encrypt}} hook.}}<br />
<br />
| {{-}}<br />
|-<br />
| {{C|'''keymap'''}} ||rowspan="2" {{C|'''sd-vconsole'''}} || Adds the specified [[Linux console/Keyboard configuration#Persistent configuration|keymap(s)]] from {{ic|/etc/vconsole.conf}} to the initramfs. If you use [[dm-crypt/Encrypting an entire system|system encryption]], especially full-disk encryption, make sure you add it before the {{ic|1=encrypt}} hook. || Loads the specified keymap(s) from {{ic|/etc/vconsole.conf}} during early userspace.<br />
|-<br />
| {{C|'''consolefont'''}} || Adds the specified [[Linux console#Persistent configuration|console font]] from {{ic|/etc/vconsole.conf}} to the initramfs. || Loads the specified console font from {{ic|/etc/vconsole.conf}} during early userspace.<br />
|-<br />
| {{C|'''encrypt'''}} || {{C|'''sd-encrypt'''}} || Adds the {{ic|dm_crypt}} kernel module and the {{ic|cryptsetup}} tool to the image. You must have {{Pkg|cryptsetup}} installed to use this. {{Note|Take notice of the remarks for the ''keyboard'' hook above to unlock an encrypted device during boot, and/or the filesystem remarks in [[#MODULES]] when you use a file to unlock.}} || Detects and unlocks an encrypted root partition. See [[#Runtime customization]] for further configuration.<br />
For '''sd-encrypt''' see [[dm-crypt/System configuration#Using systemd-cryptsetup-generator]].<br />
|-<br />
|colspan="2" {{C|'''lvm2'''}} || Adds the device mapper kernel module and the {{ic|lvm}} tool to the image. You must have {{Pkg|lvm2}} installed to use this. This is necessary if you have your root file system on [[LVM]]. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''fsck'''}} || Adds the fsck binary and file system-specific helpers to allow running fsck against your root device (and {{ic|/usr}} if separate) prior to mounting. If added after the '''autodetect''' hook, only the helper specific to your root file system will be added. Usage of this hook is '''strongly''' recommended, and it is required with a separate {{ic|/usr}} partition. It is highly recommended that if you include this hook that you also include any necessary modules to ensure your keyboard will work in early userspace. <br/>The use of this hook requires the {{ic|rw}} parameter to be set on the [[kernel command line]] ([https://bbs.archlinux.org/viewtopic.php?pid=1307895#p1307895 discussion]). See [[fsck#Boot time checking]] for more details. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''filesystems'''}} || This includes necessary file system modules into your image. This hook is '''required''' unless you specify your file system modules in {{ic|MODULES}}. || {{-}}<br />
|-<br />
|}<br />
<br />
=== COMPRESSION ===<br />
<br />
The kernel supports several formats for compression of the initramfs: {{Pkg|gzip}}, {{Pkg|bzip2}}, lzma, {{Pkg|xz}}, {{Pkg|lzo}}, {{Pkg|lz4}} and {{Pkg|zstd}}. mkinitcpio uses zstd compressed images by default, note that the zstd compression runs in multi-threading mode (with the {{ic|-T0}} option which spawns as many threads as detected cores).<br />
<br />
The provided {{ic|mkinitcpio.conf}} has the various {{ic|COMPRESSION}} options commented out. Uncomment one if you wish to switch to another compression method and make sure you have the corresponding compression utility installed. If none is specified, the zstd default method is used. If you wish to create an uncompressed image, specify {{ic|1=COMPRESSION='''cat'''}} in the configuration file or use {{ic|-z cat}} on the command line.<br />
<br />
{{Tip|With a compression ratio typically around 2.5 on the image in its high compression mode ({{ic|-9}}), lz4 achieves the fastest decompression speed at the cost of a slower single-threaded compression. For a slightly better compression, lzo is still fast to decompress. zstd offers a versatile solution, with multi-threaded compression and a wide range of compression levels through its options — see {{man|1|zstd|Operation modifiers}}. xz achieves the smallest size with a reduction factor around 5 in its high compression preset ({{ic|-9}}), at the cost of a much slower decompression speed.}}<br />
<br />
=== COMPRESSION_OPTIONS ===<br />
<br />
These are additional flags passed to the program specified by {{ic|COMPRESSION}}, such as:<br />
COMPRESSION_OPTIONS=(-9)<br />
With the current default zstd, to save space for custom kernels (especially with a dual-boot setup and original Windows EFI partition), the '--long' option is very effective. The '-v' option may also be desired to see details during the initramfs generation. E.g.:<br />
COMPRESSION_OPTIONS=(-v -5 --long)<br />
{{Note|This option can be left empty; ''mkinitcpio'' will ensure that any supported compression method has the necessary flags to produce a working image. Misuse of this option may lead to an '''unbootable system''' if the kernel is unable to unpack the resultant archive.}}<br />
<br />
== Runtime customization ==<br />
<br />
{{Expansion|Which options work with the {{ic|systemd}} hook and which are {{ic|base}}-only?}}<br />
<br />
Runtime configuration options can be passed to {{ic|init}} and certain hooks via the kernel command line. Kernel command-line parameters are often supplied by the bootloader. The options discussed below can be appended to the kernel command line to alter default behavior. See [[Kernel parameters]] and [[Arch boot process]] for more information.<br />
<br />
=== init from base hook ===<br />
<br />
; {{ic|root}}: This is the most important parameter specified on the kernel command line, as it determines what device will be mounted as your proper root device. ''mkinitcpio'' is flexible enough to allow a wide variety of formats, for example: {{bc|1=<nowiki><br />
root=/dev/sda1 # /dev node<br />
root=LABEL=CorsairF80 # label<br />
root=UUID=ea1c4959-406c-45d0-a144-912f4e86b207 # UUID<br />
root=PARTUUID=14420948-2cea-4de7-b042-40f67c618660 # GPT partition UUID</nowiki><br />
}} {{Note|The following boot parameters alter the default behavior of {{ic|init}} in the initramfs environment. See {{ic|/usr/lib/initcpio/init}} for details. They will not work when {{ic|systemd}} hook is being used since the {{ic|init}} from {{ic|base}} hook is replaced.}}<br />
<br />
; {{ic|break}}: If {{ic|break}} or {{ic|1=break=premount}} is specified, {{ic|init}} pauses the boot process (after loading hooks, but before mounting the root file system) and launches an interactive shell which can be used for troubleshooting purposes. This shell can be launched after the root has been mounted by specifying {{ic|1=break=postmount}}. Normal boot continues after exiting from the shell.<br />
<br />
; {{ic|disablehooks}}: Disable hooks at runtime by adding {{ic|1=disablehooks=hook1[,hook2,...]}}. For example: {{bc|1=disablehooks=resume}}<br />
<br />
; {{ic|earlymodules}}: Alter the order in which modules are loaded by specifying modules to load early via {{ic|1=earlymodules=mod1[,mod2,...]}}. (This may be used, for example, to ensure the correct ordering of multiple network interfaces.)<br />
<br />
See [[Boot debugging]] and {{man|8|mkinitcpio}} for other parameters.<br />
<br />
=== Using RAID ===<br />
<br />
See [[RAID#Configure mkinitcpio]].<br />
<br />
=== Using net ===<br />
<br />
{{Note|NFSv4 is not yet supported {{Bug|28287}}.}}<br />
<br />
'''Required packages'''<br />
<br />
{{ic|net}} requires the {{Pkg|mkinitcpio-nfs-utils}} package.<br />
<br />
'''Kernel parameters''' <br />
<br />
Comprehensive and up-to-date information can be found in the official [https://docs.kernel.org/admin-guide/nfs/nfsroot.html kernel documentation].<br />
<br />
'''ip='''<br />
<br />
This parameter tells the kernel how to configure IP addresses of devices and also how to set up the IP routing table. It can take up to nine arguments separated by colons: {{ic|1=ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:<dns0-ip>:<dns1-ip>:<ntp0-ip>}}.<br />
<br />
If this parameter is missing from the kernel command line, all fields are assumed to be empty, and the defaults mentioned in the [https://docs.kernel.org/admin-guide/nfs/nfsroot.html kernel documentation] apply. In general this means that the kernel tries to configure everything using autoconfiguration.<br />
<br />
The {{ic|<autoconf>}} parameter can appear alone as the value to the {{ic|ip}} parameter (without all the {{ic|:}} characters before). If the value is {{ic|1=ip=off}} or {{ic|1=ip=none}}, no autoconfiguration will take place, otherwise autoconfiguration will take place. The most common way to use this is {{ic|1=ip=dhcp}}.<br />
<br />
For parameters explanation, see the [https://docs.kernel.org/admin-guide/nfs/nfsroot.html kernel documentation].<br />
<br />
Examples:<br />
<br />
ip=127.0.0.1:::::lo:none --> Enable the loopback interface.<br />
ip=192.168.1.1:::::eth2:none --> Enable static eth2 interface.<br />
ip=:::::eth0:dhcp --> Enable dhcp protocol for eth0 configuration.<br />
<br />
{{Note|Make sure to use kernel device names (e.g. {{ic|eth0}}) for the {{ic|<device>}} parameter, the persistent names (e.g. {{ic|enp2s0}}) will not work. See [[Network configuration#Network interfaces]] for details.}}<br />
<br />
'''BOOTIF='''<br />
<br />
If you have multiple network cards, this parameter can include the MAC address of the interface you are booting from. This is often useful as interface numbering may change, or in conjunction with pxelinux IPAPPEND 2 or IPAPPEND 3 option. If not given, {{ic|eth0}} will be used.<br />
<br />
Example:<br />
<br />
BOOTIF=01-A1-B2-C3-D4-E5-F6 # Note the prepended "01-" and capital letters.<br />
<br />
'''nfsroot='''<br />
<br />
If the {{ic|nfsroot}} parameter is NOT given on the command line, the default {{ic|/tftpboot/%s}} will be used.<br />
<br />
nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]<br />
<br />
Run {{ic|mkinitcpio -H net}} for parameter explanation.<br />
<br />
=== Using LVM ===<br />
<br />
If your root device is on [[LVM]], see [[Install Arch Linux on LVM#Adding mkinitcpio hooks]].<br />
<br />
=== Using encrypted root ===<br />
<br />
If using an [[dm-crypt/Encrypting an entire system|encrypted root]] see [[dm-crypt/System configuration#mkinitcpio]] for detailed information on which hooks to include.<br />
<br />
=== /usr as a separate partition ===<br />
<br />
If you keep {{ic|/usr}} as a separate partition, you must adhere to the following requirements:<br />
<br />
* Add the {{ic|fsck}} hook, mark {{ic|/usr}} with a {{ic|passno}} of {{ic|2}} in {{ic|/etc/fstab}} to run the check on the partition at startup. While recommended for everyone, it is mandatory if you want your {{ic|/usr}} partition to be fsck'ed at boot-up. Without this hook, {{ic|/usr}} will never be fsck'd.<br />
* If not using the systemd hook, add the {{ic|usr}} hook. This will mount the {{ic|/usr}} partition after root is mounted.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Extracting the image ===<br />
<br />
If you are curious about what is inside the initramfs image, you can extract it and poke at the files inside of it. <br />
<br />
The initramfs image is an SVR4 CPIO archive, generated via the {{ic|find}} and {{ic|bsdcpio}} commands, optionally compressed with a compression scheme understood by the kernel. For more information on the compression schemes, see [[#COMPRESSION]].<br />
<br />
''mkinitcpio'' includes a utility called {{man|1|lsinitcpio}} which will list and/or extract the contents of initramfs images.<br />
<br />
You can list the files in the image with:<br />
<br />
# lsinitcpio /boot/initramfs-linux.img<br />
<br />
And to extract them all in the current directory:<br />
<br />
# lsinitcpio -x /boot/initramfs-linux.img<br />
<br />
You can also get a more human-friendly listing of the important parts in the image:<br />
<br />
# lsinitcpio -a /boot/initramfs-linux.img<br />
<br />
=== Recompressing a modified extracted image ===<br />
<br />
Invoke the {{ic|build_image}} function of the {{ic|/usr/bin/mkinitcpio}} script with parameters<br />
<br />
build_image ''outfile'' ''compression''<br />
<br />
It can be done by creating a new script with the contents of the {{ic|build_image}} function and running it with the above parameters.<br />
This will compress the contents present in the current directory in a file named {{ic|''outfile''}}.<br />
<br />
{{Warning|It is a good idea to rename the automatically generated {{ic|/boot/initramfs-linux.img}} before you overwrite it, so you can easily undo your changes. Be prepared for making a mistake that prevents your system from booting. If this happens, you will need to boot through the fallback, or a boot CD, to restore your original, run ''mkinitcpio'' to overwrite your changes, or fix them yourself and recompress the image.}}<br />
<br />
=== "/dev must be mounted" when it already is ===<br />
<br />
The test used by ''mkinitcpio'' to determine if {{ic|/dev}} is mounted is to see if {{ic|/dev/fd/}} is there. If everything else looks fine, it can be "created" manually by:<br />
<br />
# ln -s /proc/self/fd /dev/<br />
<br />
(Obviously, {{ic|/proc}} must be mounted as well. ''mkinitcpio'' requires that anyway, and that is the next thing it will check.)<br />
<br />
=== Possibly missing firmware for module XXXX ===<br />
<br />
When initramfs are being rebuilt after a kernel update, you might get warnings:<br />
<br />
==> WARNING: Possibly missing firmware for module: ''module_name''<br />
<br />
If these messages appear when generating a ''default'' initramfs image, then, as the warning says, installing additional firmware may be required. Most common firmware files can be acquired by [[install]]ing the {{Pkg|linux-firmware}} package. For other packages providing firmware see the table below or try searching for the module name in the [[official repositories]] or [[AUR]].<br />
<br />
Otherwise, if the messages only appear when generating the ''fallback'' initramfs image you have the following options:<br />
<br />
* You can safely ignore the warnings, if you know that you do not use the affected hardware.<br />
* If you want to suppress the warnings, you can install the missing firmware. The meta-package {{AUR|mkinitcpio-firmware}} contains most optional firmwares. Alternatively, manually install the needed packages:<br />
:{| class="wikitable"<br />
|-<br />
! Module !! Package<br />
|-<br />
| aic94xx || {{AUR|aic94xx-firmware}}<br />
|-<br />
| bfa || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| bnx2x || {{Pkg|linux-firmware-bnx2x}}<br />
|-<br />
| liquidio || {{Pkg|linux-firmware-liquidio}}<br />
|-<br />
| mlxsw_spectrum || {{Pkg|linux-firmware-mellanox}}<br />
|-<br />
| nfp || {{Pkg|linux-firmware-nfp}}<br />
|-<br />
| qat_4xxx || Firmware is not yet available.<br />
|-<br />
| qed || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| qla1280 || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| qla2xxx || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| wd719x || {{AUR|wd719x-firmware}}<br />
|-<br />
| xhci_pci || {{AUR|upd72020x-fw}}<br />
|}<br />
* If you want to get rid of the warnings, but do not want to waste your system space on unneeded firmware packages, you can disable fallback initramfs generation altogether:<br />
*# Change {{ic|1=PRESETS=('default' 'fallback')}} line to {{ic|1=PRESETS=('default')}} in all ''.preset'' files in {{ic|/etc/mkinitcpio.d/}}.<br />
*# Remove fallback initramfs images: {{ic|# rm /boot/*-fallback.img}}.<br />
*# Regenerate your bootloader config (e.g. for [[GRUB]]: {{ic|# grub-mkconfig -o /boot/grub/grub.cfg}}).<br />
:{{Warning|Disabling fallback initramfs generation will deprive you of another option to boot into the system in case a default initramfs fails. Before proceeding, make sure you have a bootable [[USB flash installation medium|installation medium]] for rescue purposes on hand.}}<br />
<br />
=== No PS/2 controller found ===<br />
<br />
On some motherboards (mostly ancient ones, but also a few new ones), the i8042 controller cannot be automatically detected. It is rare, but some people will surely be without keyboard. You can detect this situation in advance. If you have a PS/2 port and get {{ic|i8042: PNP: No PS/2 controller found. Probing ports directly}} message, add '''atkbd''' to the {{ic|MODULES}} array.<br />
<br />
=== Standard rescue procedures ===<br />
<br />
With an improper initial ram-disk a system often is unbootable. So follow a system rescue procedure like below:<br />
<br />
==== Boot succeeds on one machine and fails on another ====<br />
<br />
''mkinitcpio'''s {{ic|autodetect}} hook filters unneeded [[kernel modules]] in the primary initramfs scanning {{ic|/sys}} and the modules loaded at the time it is run. If you transfer your {{ic|/boot}} directory to another machine and the boot sequence fails during early userspace, it may be because the new hardware is not detected due to missing kernel modules. Note that USB 2.0 and 3.0 need different kernel modules. <br />
<br />
To fix, first try choosing the [[#Image creation and activation|fallback]] image from your [[bootloader]], as it is not filtered by {{ic|autodetect}}. Once booted, run ''mkinitcpio'' on the new machine to rebuild the primary image with the correct modules. If the fallback image fails, try booting into an Arch Linux live CD/USB, chroot into the installation, and run ''mkinitcpio'' on the new machine. As a last resort, try [[#MODULES|manually]] adding modules to the initramfs.<br />
<br />
== See also ==<br />
<br />
* Linux Kernel documentation on [https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html#what-is-rootfs initramfs, "What is rootfs?"]<br />
* Linux Kernel documentation on [https://docs.kernel.org/admin-guide/initrd.html initrd]<br />
* Wikipedia article on [[wikipedia:initrd|initrd]]</div>Jwh7https://wiki.archlinux.org/index.php?title=Wine&diff=715236Wine2022-02-02T21:52:10Z<p>Jwh7: /* Keyboard input not working */ more options</p>
<hr />
<div>[[Category:Emulation]]<br />
[[Category:Gaming]]<br />
[[de:Wine]]<br />
[[fr:Wine]]<br />
[[ja:Wine]]<br />
[[ru:Wine]]<br />
[[zh-hans:Wine]]<br />
{{Related articles start}}<br />
{{Related|CrossOver}}<br />
{{Related|Deepin-wine}}<br />
{{Related|Wine package guidelines}}<br />
{{Related articles end}}<br />
[[Wikipedia:Wine (software)|Wine]] is a ''compatibility layer'' capable of running Microsoft Windows applications on Unix-like operating systems. Programs running in Wine act as native programs would, without the performance/memory penalties of an emulator.<br />
<br />
{{Warning|<br />
* Wine is not isolated from your system.<br />
* If you can access a file or resource with your user account, programs running in Wine can too. See [[#Running Wine under a separate user account]] and [[Security#Sandboxing applications]] for possible precautions.<br />
* Wine can also run Malware (see [https://wiki.winehq.org/FAQ#Is_Wine_malware-compatible.3F Wine FAQ on Malware compatibility])}}<br />
<br />
== Installation ==<br />
<br />
Wine can be installed by enabling the [[multilib]] repository and [[install]]ing the {{Pkg|wine}} (stable) or {{Pkg|wine-staging}} (testing) package. [https://wine-staging.com/ Wine Staging] is a patched version of [https://www.winehq.org/ Wine], which contains bug fixes and features that have not been integrated into the stable or development branch yet. <br />
<br />
See also [[#Graphics drivers]] and [[#Sound]] for additional requirements.<br />
<br />
Consider installing {{pkg|wine-gecko}} and {{pkg|wine-mono}} for applications that depend on Internet Explorer and .NET, respectively. These packages are not strictly required as Wine will download the relevant files as needed. However, having the files downloaded in advance allows you to work off-line and makes it so Wine does not download the files for each Wine prefix needing them.<br />
<br />
=== Third-party applications ===<br />
<br />
These have their own communities and websites, and are '''not supported''' by the main Wine community. See [https://wiki.winehq.org/Third_Party_Applications Wine Wiki] for more details.<br />
<br />
* {{App|[[CrossOver]]|Paid, commercialized version of Wine which provides more comprehensive end-user support.|https://www.codeweavers.com|{{AUR|crossover}}}}<br />
* {{App|exe-thumbnailer|Generates thumbnails for Windows executable files (.exe, .lnk, .msi, and .dll).|https://github.com/exe-thumbnailer/exe-thumbnailer|{{AUR|exe-thumbnailer}}}}<br />
* {{App|[[Wikipedia:Lutris|Lutris]]|Gaming launcher for all types of games, including Wine games (with prefix management), native Linux games and emulators.|https://lutris.net|{{Pkg|lutris}}}}<br />
* {{App|[[Wikipedia:PlayOnLinux|PlayOnLinux]]|Graphical prefix manager for Wine. Contains scripts to assist with program installation and configuration.|https://www.playonlinux.com|{{Pkg|playonlinux}}}}<br />
* {{App|Proton|Compatibility tool made for [[Steam]] based on Wine and additional components. See [https://www.protondb.com/ ProtonDB] for compatibility list.|https://github.com/ValveSoftware/Proton|{{AUR|proton}}}}<br />
* {{App|PyWinery|Simple graphical prefix manager for Wine.|https://github.com/ergoithz/pywinery|{{AUR|pywinery}}}}<br />
* {{App|Q4Wine|Graphical prefix manager for Wine. Can export [[Qt]] themes into the Wine configuration for better integration.|https://sourceforge.net/projects/q4wine/|{{AUR|q4wine}}{{Broken package link|package not found}}}}<br />
* {{App|Bottles|Graphical prefix and runners manager for Wine based on GTK.|https://usebottles.com/|{{AUR|bottles}}}}<br />
<br />
== Configuration ==<br />
<br />
Configuring Wine is typically accomplished using:<br />
<br />
* [https://wiki.winehq.org/Winecfg winecfg] is a GUI configuration tool for Wine, which can be started by running {{ic|winecfg}}.<br />
* [https://wiki.winehq.org/Regedit regedit] is Wine's registry editing tool, which can be started by running {{ic|regedit}}. See WineHQ's article on [https://wiki.winehq.org/Useful_Registry_Keys Useful Registry Keys].<br />
* [https://wiki.winehq.org/Control control] is Wine's implementation of the Windows Control Panel, which can be started by running {{ic|wine control}}.<br />
* See WineHQ's [https://wiki.winehq.org/List_of_Commands List of Commands] for the full list.<br />
<br />
=== WINEPREFIX ===<br />
<br />
By default, Wine stores its configuration files and installed Windows programs in {{ic|~/.wine}}. This directory is commonly called a "Wine prefix" or "Wine bottle". It is created/updated automatically whenever you run a Windows program or one of Wine's bundled programs such as ''winecfg''. The prefix directory also contains a tree which your Windows programs will see as {{ic|C:}} (the C-drive).<br />
<br />
You can override the location Wine uses for a prefix with the {{ic|WINEPREFIX}} [[environment variable]]. This is useful if you want to use separate configurations for different Windows programs. The first time a program is run with a new Wine prefix, Wine will automatically create a directory with a bare C-drive and registry.<br />
<br />
For example, if you run one program with {{ic|1= $ env WINEPREFIX=~/.win-a wine program-a.exe}}, and another with {{ic|1= $ env WINEPREFIX=~/.win-b wine program-b.exe}}, the two programs will each have a separate C-drive and separate registries.<br />
<br />
{{Note|Wine prefixes are not [[Wikipedia:Sandbox (computer security)|sandboxes]]! Programs running under Wine can still access the rest of the system! (for example, {{ic|Z:}} is mapped to {{ic|/}}, regardless of the Wine prefix).}}<br />
<br />
To create a default prefix without running a Windows program or other GUI tool you can use:<br />
<br />
$ env WINEPREFIX=~/.customprefix wineboot -u<br />
<br />
=== WINEARCH ===<br />
<br />
Wine will start a 64-bit environment by default. You can change this behavior using the {{ic|WINEARCH}} [[environment variable]]. Rename your {{ic|~/.wine}} directory and create a new Wine environment by running {{ic|1=$ WINEARCH=win32 winecfg}}. This will get you a 32-bit Wine environment. Not setting {{ic|WINEARCH}} will get you a 64-bit one.<br />
<br />
You can combine this with {{ic|WINEPREFIX}} to make a separate {{ic|win32}} and {{ic|win64}} environment:<br />
<br />
$ WINEARCH=win32 WINEPREFIX=~/win32 winecfg<br />
$ WINEPREFIX=~/win64 winecfg<br />
<br />
You can also use {{ic|WINEARCH}} in combination with other Wine programs, such as ''winetricks'' (using Steam as an example):<br />
<br />
WINEARCH=win32 WINEPREFIX=~/.local/share/wineprefixes/steam winetricks steam<br />
<br />
In order to see the architecture of an existing prefix you can check its registry file. The command below reads the system registry of the {{ic|~/.wine}} prefix and returns {{ic|1=#arch=win32}} or {{ic|1=#arch=win64}} depending on the architecture type:<br />
<br />
$ grep '#arch' ~/.wine/system.reg<br />
<br />
=== Graphics drivers ===<br />
<br />
You need to install the 32-bit version of your graphics driver. Please install the package that is listed in the ''OpenGL (multilib)'' column in the table in [[Xorg#Driver installation]].<br />
<br />
A good sign that your drivers are inadequate or not properly configured is when Wine reports the following in your terminal window:<br />
<br />
Direct rendering is disabled, most likely your OpenGL drivers have not been installed correctly<br />
<br />
{{Note|You might need to restart X after having installed the correct library.}}<br />
<br />
=== Sound ===<br />
<br />
By default sound issues may arise when running Wine applications. Ensure only one sound device is selected in ''winecfg''.<br />
<br />
Install the correct packages for the audio driver you want to use:<br />
<br />
* For [[ALSA]] install {{Pkg|lib32-alsa-lib}} and {{Pkg|lib32-alsa-plugins}}<br />
* For [[PulseAudio]] install {{Pkg|lib32-libpulse}} <br />
* For [[PipeWire]] install either {{Pkg|pipewire-pulse}} and {{Pkg|lib32-libpulse}} or {{Pkg|pipewire-alsa}} and {{Pkg|lib32-alsa-lib}} + {{Pkg|lib32-alsa-plugins}}<br />
* For [[OSS]] install {{Pkg|lib32-alsa-oss}}<br />
<br />
Additional packages: <br />
<br />
* Games that use advanced sound systems (''e.g.'' TESV: Skyrim) may additionally require installations of {{Pkg|lib32-openal}}.<br />
<br />
If ''winecfg'' '''still''' fails to detect the audio driver (Selected driver: (none)), [https://wiki.winehq.org/Wine_User's_Guide#Using_Regedit configure it via the registry]. For example, in a case where the microphone was not working in a 32-bit Windows application on a 64-bit stock install of wine-1.9.7, this provided full access to the sound hardware (sound playback and mic): open ''regedit'', look for the key HKEY_CURRENT_USER → Software → Wine → Drivers, and add a string called ''Audio'' and give it the value ''alsa''. Also, it may help to [[#WINEARCH|recreate the prefix]].<br />
<br />
==== MIDI support ====<br />
<br />
[[MIDI]] was a quite popular system for video games music in the 90's. If you are trying out old games, it is not uncommon that the music will not play out of the box.<br />
Wine has excellent MIDI support. However you first need to make it work on your host system, as explained in [[MIDI]]. Last but not least you need to make sure Wine will use the correct MIDI output.<br />
<br />
=== Other dependencies ===<br />
<br />
Some applications may require additional packages for the following purposes:<br />
<br />
* playing music: {{Pkg|lib32-mpg123}}<br />
* native image manipulation libraries: {{Pkg|lib32-giflib}} and {{Pkg|lib32-libpng}}<br />
* encryption support: {{Pkg|lib32-gnutls}}<br />
* 32-bit video codecs: {{Pkg|lib32-gst-plugins-base}}, {{Pkg|lib32-gst-plugins-good}}, {{Aur|lib32-gst-plugins-bad}} and {{Aur|lib32-gst-plugins-ugly}}<br />
* NTLM authentication: {{Pkg|samba}}<br />
<br />
=== Fonts ===<br />
<br />
If Wine applications are not showing easily readable fonts, you may not have any fonts installed. To easily link all of the system fonts so they are accessible from wine:<br />
<br />
$ cd ${WINEPREFIX:-~/.wine}/drive_c/windows/Fonts && for i in /usr/share/fonts/**/*.{ttf,otf}; do ln -s "$i" ; done<br />
<br />
Wine uses FreeType to render fonts, and FreeType's defaults changed a few releases ago. Try using this environment setting for wine programs:<br />
<br />
FREETYPE_PROPERTIES="truetype:interpreter-version=35"<br />
<br />
Another possibility is to install Microsoft's TrueType fonts into your wine prefix. See [[MS Fonts]]. If this does not help, try running {{ic|winetricks corefonts}} first, then {{ic|winetricks allfonts}} as a last resort.<br />
<br />
After running such programs, kill all Wine servers and run {{ic|winecfg}}. Fonts should be legible now.<br />
<br />
If the fonts look somehow smeared, import the following text file into the Wine registry with [https://wiki.winehq.org/FAQ#How_do_I_edit_the_Wine_registry.3F regedit]:<br />
<br />
Windows Registry Editor Version 5.00<br />
[HKEY_CURRENT_USER\Software\Wine\X11 Driver]<br />
"ClientSideWithRender"="N"<br />
<br />
For high resolution displays, you can adjust dpi values in winecfg.<br />
<br />
See also [[Font configuration#Applications without fontconfig support]].<br />
<br />
==== Enable font smoothing ====<br />
<br />
A good way to improve wine font rendering is to enable cleartype font smoothing.<br />
To enable "Subpixel smoothing (ClearType) RGB":<br />
<br />
{{bc|<nowiki><br />
cat << EOF > /tmp/fontsmoothing<br />
REGEDIT4<br />
<br />
[HKEY_CURRENT_USER\Control Panel\Desktop]<br />
"FontSmoothing"="2"<br />
"FontSmoothingOrientation"=dword:00000001<br />
"FontSmoothingType"=dword:00000002<br />
"FontSmoothingGamma"=dword:00000578<br />
EOF<br />
<br />
WINE=${WINE:-wine} WINEPREFIX=${WINEPREFIX:-$HOME/.wine} $WINE regedit /tmp/fontsmoothing 2> /dev/null<br />
</nowiki>}}<br />
<br />
For more information, check [https://askubuntu.com/a/219795 the original answer]<br />
<br />
=== Desktop launcher menus ===<br />
<br />
When a Windows application installer creates a shortcut Wine creates a [[.desktop]] file instead. The default locations for those files in Arch Linux are:<br />
<br />
* Desktop shortcuts are put in {{ic|~/Desktop}}<br />
* Start menu shortcuts are put in {{ic|~/.local/share/applications/wine/Programs/}}<br />
<br />
{{Note|1=Wine does not support installing Windows applications for all users, so it will not put ''.desktop'' files in {{ic|/usr/share/applications}}. See WineHQ bug [https://bugs.winehq.org/show_bug.cgi?id=11112 11112]}}<br />
<br />
{{Tip|If menu items were ''not'' created while installing software or have been lost, {{ic|wine winemenubuilder}} may be of some use.}}<br />
<br />
==== Creating menu entries for Wine utilities ====<br />
<br />
By default, installation of Wine does not create desktop menus/icons for the software which comes with Wine (e.g. for ''winecfg'', ''winebrowser'', etc). This can be achieved by installing {{AUR|wine-installer}} or {{AUR|wine-installer-git}} meta-package (the latter has no additional dependencies), otherwise these instructions will add entries for these applications.<br />
<br />
First, install a Windows program using Wine to create the base menu. After the base menu is created, you can create the following files in {{ic|~/.local/share/applications/wine/}}:<br />
<br />
{{hc|wine-browsedrive.desktop|2=<br />
[Desktop Entry]<br />
Name=Browse C: Drive<br />
Comment=Browse your virtual C: drive<br />
Exec=wine winebrowser c:<br />
Terminal=false<br />
Type=Application<br />
Icon=folder-wine<br />
Categories=Wine;<br />
}}<br />
<br />
{{hc|wine-uninstaller.desktop|2=<br />
[Desktop Entry]<br />
Name=Uninstall Wine Software<br />
Comment=Uninstall Windows applications for Wine<br />
Exec=wine uninstaller<br />
Terminal=false<br />
Type=Application<br />
Icon=wine-uninstaller<br />
Categories=Wine;<br />
}}<br />
<br />
{{hc|wine-winecfg.desktop|2=<br />
[Desktop Entry]<br />
Name=Configure Wine<br />
Comment=Change application-specific and general Wine options<br />
Exec=winecfg<br />
Terminal=false<br />
Icon=wine-winecfg<br />
Type=Application<br />
Categories=Wine;<br />
}}<br />
<br />
And create the following file in {{ic|~/.config/menus/applications-merged/}}:<br />
<br />
{{hc|wine.menu|<nowiki><br />
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"<br />
"http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd"><br />
<Menu><br />
<Name>Applications</Name><br />
<Menu><br />
<Name>wine-wine</Name><br />
<Directory>wine-wine.directory</Directory><br />
<Include><br />
<Category>Wine</Category><br />
</Include><br />
</Menu><br />
</Menu><br />
</nowiki>}}<br />
<br />
If these settings produce a ugly/non-existent icon, it means that there are no icons for these launchers in the icon set that you have enabled. You should replace the icon settings with the explicit location of the icon that you want. Clicking the icon in the launcher's properties menu will have the same effect. A great icon set that supports these shortcuts is [https://www.gnome-look.org/content/show.php/GNOME-colors?content=82562 GNOME-colors].<br />
<br />
==== Removing menu entries ====<br />
<br />
Menu entries created by Wine are located in {{ic|~/.local/share/applications/wine/Programs/}}. Remove the program's ''.desktop'' entry to remove the application from the menu.<br />
<br />
In addition to remove unwanted extensions binding by Wine, execute the following commands (taken from the Wine website):<br />
<br />
$ rm ~/.local/share/mime/packages/x-wine*<br />
$ rm ~/.local/share/applications/wine-extension*<br />
$ rm ~/.local/share/icons/hicolor/*/*/application-x-wine-extension*<br />
$ rm ~/.local/share/mime/application/x-wine-extension*<br />
<br />
Sometimes you should also remove {{ic|wine-*.menu}} files from {{ic|/.config/menus/}} to completely remove items from wine submenu in kde.<br />
<br />
=== Appearance ===<br />
<br />
A similar to XP-looking theme can be [https://archive.org/download/zune-desktop-theme/ZuneDesktopTheme.msi downloaded]. To install it, see [https://wiki.winehq.org/Wine_User%27s_Guide#Running_.msi_files this upstream wiki article]. Lastly, use ''winecfg'' to select it.<br />
<br />
{{Note|The theme linked above can only be installed on 32-bit prefixes with Windows XP as the prefix version. To install it on 64-bit prefixes, you might want to create a temporary 32-bit prefix, install the theme and copy the {{ic|Zune}} folder and {{ic|Zune.theme}} files from {{ic|drive_c/Windows/Resources/Themes}} in that prefix to the same location in your usual prefix.}}<br />
<br />
Wine staging users may instead want to try enabling the option ''Enable GTK3 Theming'' under the Staging section of ''winecfg'' for a theme that matches the current GTK theme.<br />
<br />
=== Printing ===<br />
<br />
In order to use your installed printers (both local and network) with wine applications in ''win32 prefixes'' (e.g. MS Word), install the {{Pkg|lib32-libcups}} package, reboot wine (''wineboot'') and restart your wine application.<br />
<br />
=== Networking ===<br />
<br />
After installation, the {{pkg|lib32-gnutls}} package may need to be [[install]]ed for applications making TLS or HTTPS connections to work.<br />
<br />
For ICMP (ping), Wine may need the network access as described in the [https://wiki.winehq.org/FAQ#Failed_to_use_ICMP_.28network_ping.29.2C_this_requires_special_permissions WineHQ FAQ]:<br />
<br />
# setcap cap_net_raw+epi /usr/bin/wine-preloader<br />
<br />
If issues arise after this (such as an unhandled exception or privileged instruction), remove via:<br />
<br />
# setcap -r /usr/bin/wine-preloader<br />
<br />
== Usage ==<br />
<br />
{{Warning|Do not run or install Wine applications as root! See [https://wiki.winehq.org/FAQ#Should_I_run_Wine_as_root.3F Wine FAQ] for details.}}<br />
<br />
See [https://wiki.winehq.org/Wine_User%27s_Guide#Using_Wine Wine User's Guide] for general information on Wine usage.<br />
<br />
See [https://appdb.winehq.org/ Wine Application Database (AppDB)] for additional information on specific Windows applications in Wine.<br />
<br />
=== Wayland ===<br />
<br />
Currently Wine does not support Wayland directly, but you can use [[Wayland#XWayland|XWayland]] instead.<br />
<br />
There are some efforts to support Wayland though:<br />
<br />
* Experimental Wayland driver for Wine, which supports using OpenGL- and Windows GDI-applications. See [https://www.winehq.org/pipermail/wine-devel/2020-December/178575.html this] and [https://www.winehq.org/pipermail/wine-devel/2021-February/181325.html this] wine-devel maillist entries.<br />
* [https://github.com/varmd/wine-wayland wine-wayland]: a custom version of Wine, which supports Wayland via Vulkan (so it supports only: DirectX 9, 10 and 11 via [[#DXVK]] and Vulkan-compatible applications).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Wineconsole ===<br />
<br />
Often you may need to run ''.exe'''s to patch game files, for example a widescreen mod for an old game, and running the ''.exe'' normally through Wine might yield nothing happening. In this case, you can open a terminal and run the following command:<br />
<br />
$ wineconsole cmd<br />
<br />
Then navigate to the directory and run the ''.exe'' file from there.<br />
<br />
=== Winetricks ===<br />
<br />
[https://wiki.winehq.org/Winetricks Winetricks] is a script to allow one to install base requirements needed to run Windows programs. Installable components include DirectX 9.x, MSXML (required by Microsoft Office 2007 and Internet Explorer), Visual Runtime libraries and many more.<br />
<br />
[[Install]] the {{pkg|winetricks}} package (or alternatively {{AUR|winetricks-git}}). Then run it with:<br />
$ winetricks<br />
<br />
For using GUI you should [[install]] the {{pkg|zenity}}.<br />
<br />
=== Performance ===<br />
<br />
==== CSMT ====<br />
<br />
CSMT is a technology used by Wine to use a separate thread for the OpenGL calls to improve performance noticeably. Since Wine 3.2, CSMT is enabled by default. However, CSMT support needs to be enabled manually for Wine versions lower than 3.2. For vanilla Wine run {{ic|wine regedit}} and set the DWORD value for ''HKEY_CURRENT_USER -> Software > Wine > Direct3D > csmt'' to 0x01 (enabled). For wine-staging run {{ic|winecfg}} and enable it in the staging tab.<br />
<br />
Note that CSMT may actually hurt performance for some applications - if this is the case, disable it by creating/setting the registry value to 0x00 (disabled).<br />
<br />
Further information:<br />
*[https://www.phoronix.com/forums/showthread.php?93967-Wine-s-Big-Command-Stream-D3D-Patch-Set-Updated/page3&s=7775d7c3d4fa698089d5492bb7b1a435 Phoronix Forum discussion] with the CSMT developer Stefan Dösinger<br />
<br />
==== Force OpenGL mode in games ====<br />
<br />
Some games might have an OpenGL mode which ''may'' perform better than their default DirectX mode. While the steps to enable OpenGL rendering is ''application specific'', many games accept the {{Ic|-opengl}} parameter.<br />
<br />
$ wine ''/path/to/3d_game.exe'' -opengl<br />
<br />
You should of course refer to your application's documentation and Wine's [https://appdb.winehq.org AppDB] for such application specific information.<br />
<br />
==== DXVK ====<br />
<br />
[https://github.com/doitsujin/dxvk DXVK] is a promising new implementation for DirectX 9, 10 & 11 over Vulkan. This should allow for greater performance, and in some cases, even better compatibility. Battlefield 1 for example, only runs under DXVK. On the other hand, DXVK does not support all Wine games (yet).<br />
<br />
To use it, install {{aur|dxvk-bin}}. Then run the following command to activate it in your Wineprefix (by default {{ic|~/.wine}}):<br />
$ WINEPREFIX=''your-prefix'' setup_dxvk install<br />
<br />
{{Note|For Wine versions below 3.5 you need to configure Vulkan support manually, following the instructions at [https://github.com/roderickc/wine-vulkan GitHub].}}<br />
<br />
{{Warning|DXVK overrides the DirectX 10 and 11 DLLs, which may be considered cheating in online multiplayer games, and may get your account '''banned'''. Use at your own risk!}}<br />
<br />
==== Gallium Nine ====<br />
<br />
With the open-source gallium-based drivers (mostly AMD and Intel cards) there is a [https://wiki.ixit.cz/d3d9 Gallium Direct3D state tracker] that aims to provide nearly-native performance for DirectX 9. In most cases it has less visual glitches than the upstream wine and doubles the performances. It consumes much less CPU time than CSMT.<br />
<br />
Install {{Pkg|wine-nine}} to use it. This is a standalone package that can be installed with any Wine version. Use {{ic|wine ninewinecfg}} to check if it is enabled.<br />
<br />
For older Intel graphics (gen4-7: GMA 3000, GMA 4500, HD 2000-5000; year 2006-2014) Crocus Gallium driver should be used instead of i965 since Mesa 21.2. [[Export]] the following environment variable before running Wine: <br />
<br />
MESA_LOADER_DRIVER_OVERRIDE=crocus<br />
<br />
=== Unregister existing Wine file associations ===<br />
<br />
By default, Wine takes over as the default application for a lot of formats. Some (e.g. {{ic|vbs}} or {{ic|chm}}) are Windows-specific, and opening them with Wine can be a convenience. However, having other formats (e.g. {{ic|gif}}, {{ic|jpeg}}, {{ic|txt}}, {{ic|js}}) open in Wine's bare-bones simulations of Internet Explorer and Notepad can be annoying.<br />
<br />
Wine's file associations are set in {{ic|~/.local/share/applications/}} as {{ic|wine-extension-''extension''.desktop}} files. Delete the files corresponding to the extensions you want to unregister. Or, to remove all wine extensions:<br />
<br />
$ rm -f ~/.local/share/applications/wine-extension*.desktop<br />
$ rm -f ~/.local/share/icons/hicolor/*/*/application-x-wine-extension*<br />
<br />
Next, remove the old cache:<br />
<br />
$ rm -f ~/.local/share/applications/mimeinfo.cache<br />
$ rm -f ~/.local/share/mime/packages/x-wine*<br />
$ rm -f ~/.local/share/mime/application/x-wine-extension*<br />
<br />
And, update the cache:<br />
<br />
$ update-desktop-database ~/.local/share/applications<br />
$ update-mime-database ~/.local/share/mime/<br />
<br />
Please note Wine will still create new file associations and even recreate the file associations if the application sets the file associations again.<br />
<br />
=== Prevent Wine from creating filetype associations ===<br />
<br />
{{Note|This has to be done for each WINEPREFIX which should not update file associations unless you opt to change {{ic|/usr/share/wine/wine.inf}} .}}<br />
This method prevents the creation of filetype associations but retains the creation of XDG .desktop files (that you might see e.g. in menus).<br />
<br />
If you want to stop wine from creating filetype associations via winecfg you have to uncheck the "Manage File Associations" checkbox under the Desktop Integration tab. See [https://wiki.winehq.org/FAQ#How_can_I_prevent_Wine_from_changing_the_filetype_associations_on_my_system_or_adding_unwanted_menu_entries.2Fdesktop_links.3F Wine FAQ]<br />
<br />
To make the same change via registry add the string {{ic|Enable}} with value {{ic|N}} under:<br />
<br />
HKEY_CURRENT_USER\Software\Wine\FileOpenAssociations<br />
<br />
''You might have to create the key {{ic|FileOpenAssociations}} first!''<br />
<br />
If you want to apply this by default for new WINEPREFIXES, edit {{ic|/usr/share/wine/wine.inf}} and add this line for example under the {{ic|[Services]}} section:<br />
HKCU,"Software\Wine\FileOpenAssociations","Enable",2,"N"<br />
<br />
To prevent a package upgrade from overriding the modified file, create a pacman hook to make the change automatically:<br />
<br />
{{hc|1=/etc/pacman.d/hooks/stop-wine-associations.hook|2=<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Upgrade<br />
Type = Path<br />
Target = usr/share/wine/wine.inf<br />
<br />
[Action]<br />
Description = Stopping Wine from hijacking file associations...<br />
When = PostTransaction<br />
<nowiki>Exec = /bin/sh -c '/usr/bin/grep -q "HKCU,\"Software\\\Wine\\\FileOpenAssociations\",\"Enable\",2,\"N\"" /usr/share/wine/wine.inf || /usr/bin/sed -i "s/\[Services\]/\[Services\]\nHKCU,\"Software\\\Wine\\\FileOpenAssociations\",\"Enable\",2,\"N\"/g" /usr/share/wine/wine.inf'</nowiki><br />
}}<br />
<br />
See [[Pacman#Hooks]]<br />
<br />
=== Execute Windows binaries with Wine implicitly ===<br />
<br />
The {{pkg|wine}} package installs a ''binfmt'' file which will allows you to run Windows programs directly, e.g. {{ic|''./myprogram.exe''}} will launch as if you had typed {{ic|wine ''./myprogram.exe''}}. Service starts by default on boot, if you have not rebooted after installing Wine you can [[start]] {{ic|systemd-binfmt.service}} to use it right away.<br />
<br />
{{Note|Make sure the Windows binary is [[executable]], otherwise the binary will not run.}}<br />
<br />
=== Dual Head with different resolutions ===<br />
<br />
If you have issues with dual-head setups and different display resolutions you are probably missing {{Pkg|lib32-libxrandr}}.<br />
<br />
Also installing {{Pkg|lib32-libxinerama}} might fix dual-head issues with wine (for example, unclickable buttons and menus of application in the right most or bottom most monitor, not redrawable interface of application in that zone, dragging mouse cursor state stucked after leaving application area).<br />
<br />
=== Burning optical media ===<br />
<br />
To burn CDs or DVDs, you will need to load the {{ic|sg}} [[kernel module]].<br />
<br />
=== Proper mounting of optical media images ===<br />
<br />
Some applications will check for the optical media to be in drive. They may check for data only, in which case it might be enough to configure the corresponding path as being a CD-ROM drive in ''winecfg''.<br />
However, other applications will look for a media name and/or a serial number, in which case the image has to be mounted with these special properties.<br />
<br />
Some virtual drive tools do not handle these metadata, like fuse-based virtual drives (Acetoneiso for instance). [[CDemu]] will handle it correctly.<br />
<br />
=== Show FPS overlay in games ===<br />
<br />
Wine features an embedded FPS monitor which works for all graphical applications if the environment variable {{ic|1=WINEDEBUG=fps}} is set. This will output the framerate to stdout. You can display the FPS on top of the window thanks to {{ic|osd_cat}} from the {{pkg|xosd}} package. See [https://gist.github.com/anonymous/844aefd70bb50bf72b35 winefps.sh] for a helper script.<br />
<br />
=== Running Wine under a separate user account ===<br />
<br />
It may be desirable to run Wine under a specifically created user account in order to reduce concerns about Windows applications having access to your home directory.<br />
<br />
First, create a [[user account]] for Wine:<br />
<br />
# useradd -m -s /bin/bash wineuser<br />
<br />
Now switch to another TTY and start your X WM or DE as you normally would or keep reading...<br />
<br />
{{Note|The following approach only works when enabling root for Xorg. See [[Xorg#Rootless Xorg]] for more information on how to execute the {{ic|xhost}} command under your main user.}}<br />
<br />
Afterwards, in order to open Wine applications using this new user account you need to add the new user to the X server permissions list:<br />
<br />
$ xhost +SI:localuser:wineuser<br />
<br />
Finally, you can run Wine via the following command, which uses {{ic|env}} to launch Wine with the environment variables it expects:<br />
<br />
$ sudo -u wineuser env HOME=/home/wineuser USER=wineuser USERNAME=wineuser LOGNAME=wineuser wine ''arguments''<br />
<br />
It is possible to automate the process of running Windows applications with Wine via this method by using a shell script as follows:<br />
{{hc|1=/usr/local/bin/runaswine|2=<br />
#!/bin/bash<br />
xhost +SI:localuser:wineuser<br />
sudo -u wineuser env HOME=/home/wineuser USER=wineuser USERNAME=wineuser LOGNAME=wineuser wine "$@"}}<br />
<br />
Wine applications can then be launched via:<br />
<br />
$ runaswine ''"C:\path\to\application.exe"''<br />
<br />
In order to not be asked for a password each time Wine is run as another user the following entry can be added to the sudoers file: {{ic|1=''mainuser'' ALL=(wineuser) NOPASSWD: ALL}}. See [[Sudo#Configuration]] for more information.<br />
<br />
It is recommended to run {{ic|winecfg}} as the Wine user and remove all bindings for directories outside the home directory of the Wine user in the "Desktop Integration" section of the configuration window so no program run with Wine has read access to any file outside the special user's home directory.<br />
<br />
Keep in mind that audio will probably be non-functional in Wine programs which are run this way if [[PulseAudio]] is used. See [[PulseAudio/Examples#Allowing multiple users to share a PulseAudio daemon]] for information about allowing the Wine user to access the PulseAudio daemon of the principal user.<br />
<br />
=== Temp directory on tmpfs ===<br />
<br />
To prevent Wine from writing its temporary files to a physical disk, one can define an alternative location, like ''tmpfs''. Remove Wine's default directory for temporary files and creating a symlink:<br />
<br />
$ rm -r ~/.wine/drive_c/users/$USER/Temp<br />
$ ln -s /tmp/ ~/.wine/drive_c/users/$USER/Temp<br />
<br />
=== Prevent installing Mono/Gecko ===<br />
<br />
If Gecko and/or Mono are not present on the system nor in the Wine prefix, Wine will prompt to download them from the internet. If you do not need Gecko and/or Mono, you might want to disable this dialog, by setting the {{ic|WINEDLLOVERRIDES}} [[environment variable]] to {{ic|1=mscoree=d;mshtml=d}}.<br />
<br />
=== Vulkan ===<br />
<br />
Vulkan support is included, since Wine 3.3. The default Wine Vulkan ICD loader works fine for most applications, but does not support advanced features, like Vulkan layers. To use these features, you have to install the official Vulkan SDK, see step 2-4 on the original Vulkan patches author's [https://github.com/roderickc/wine-vulkan GitHub page].<br />
<br />
{{Note|The Wine ICD loader was added in Wine 3.5, you need to install the official Vulkan SDK to use Vulkan in Wine 3.3 and 3.4}}<br />
<br />
=== Remove Wine file bindings ===<br />
<br />
For security reasons it may be useful to remove the preinstalled Wine bindings so Windows applications cannot be launched directly from a file manager or from the browser (Firefox offers to open EXE files directly with Wine!).<br />
If you want to do this, you may add the following to the {{ic|1= [options]}} section in {{ic|1= /etc/pacman.conf}}<br />
<br />
NoExtract = usr/lib/binfmt.d/wine.conf<br />
NoExtract = usr/share/applications/wine.desktop<br />
<br />
== Troubleshooting ==<br />
<br />
See [https://wiki.winehq.org/Wine_User%27s_Guide#Troubleshooting_.2F_Reporting_bugs Wine User's Guide] and [https://wiki.winehq.org/FAQ Wine FAQ] (especially its [https://wiki.winehq.org/FAQ#Troubleshooting Troubleshooting] section) for general tips.<br />
<br />
Also refer to the [https://appdb.winehq.org/ Wine AppDB] for an advice on specific applications.<br />
<br />
=== XWayland problems ===<br />
<br />
If you use Wine under [[Wayland#XWayland|XWayland]], you can activate the option for "Emulating a virtual desktop" in the Graphics Tab in winecfg, to avoid problems with:<br />
<br />
* flickering;<br />
* wrong window location;<br />
* wrong mouse cursor location and clicks;<br />
* keyboard detection.<br />
<br />
=== Keyboard input not working ===<br />
<br />
This could be caused by the window manager not switching focus. In the ''Graphics'' tab of ''winecfg'', disable the 'Allow the window manager...' options, or set windowed mode with 'Emulate a virtual desktop'.<br />
*Some suggest to toggle all the ''Window settings'', click ''Apply'', then change them back. If that does not work, try the above.<br />
<br />
If the keyboard does not work after unfocusing the application, try editing the registry:<br />
*Under ''HKEY_CURRENT_USER\Software\Wine\X11 Driver'', add a string value ''UseTakeFocus'' and set it to ''N''.<br />
*Alternatively, you can use winetricks to set the value.<br />
winetricks usetakefocus=n<br />
<br />
== See also ==<br />
<br />
* [https://www.winehq.org/ Wine Homepage]<br />
* [https://wiki.winehq.org/ Wine Wiki]<br />
* [https://appdb.winehq.org/ Wine Application Database (AppDB)] - Information about running specific Windows applications (Known issues, ratings, guides, etc tailored to specific applications)<br />
* [https://forum.winehq.org/ Wine Forums] - A great place to ask questions ''after'' you have looked through the FAQ and AppDB<br />
* [[Gentoo:Wine]]<br />
* [https://www.darlinghq.org/ Darling] - a similar project for MacOS software</div>Jwh7https://wiki.archlinux.org/index.php?title=Wine&diff=715235Wine2022-02-02T21:26:56Z<p>Jwh7: /* Keyboard input not working */ forgot Graphics tab detail</p>
<hr />
<div>[[Category:Emulation]]<br />
[[Category:Gaming]]<br />
[[de:Wine]]<br />
[[fr:Wine]]<br />
[[ja:Wine]]<br />
[[ru:Wine]]<br />
[[zh-hans:Wine]]<br />
{{Related articles start}}<br />
{{Related|CrossOver}}<br />
{{Related|Deepin-wine}}<br />
{{Related|Wine package guidelines}}<br />
{{Related articles end}}<br />
[[Wikipedia:Wine (software)|Wine]] is a ''compatibility layer'' capable of running Microsoft Windows applications on Unix-like operating systems. Programs running in Wine act as native programs would, without the performance/memory penalties of an emulator.<br />
<br />
{{Warning|<br />
* Wine is not isolated from your system.<br />
* If you can access a file or resource with your user account, programs running in Wine can too. See [[#Running Wine under a separate user account]] and [[Security#Sandboxing applications]] for possible precautions.<br />
* Wine can also run Malware (see [https://wiki.winehq.org/FAQ#Is_Wine_malware-compatible.3F Wine FAQ on Malware compatibility])}}<br />
<br />
== Installation ==<br />
<br />
Wine can be installed by enabling the [[multilib]] repository and [[install]]ing the {{Pkg|wine}} (stable) or {{Pkg|wine-staging}} (testing) package. [https://wine-staging.com/ Wine Staging] is a patched version of [https://www.winehq.org/ Wine], which contains bug fixes and features that have not been integrated into the stable or development branch yet. <br />
<br />
See also [[#Graphics drivers]] and [[#Sound]] for additional requirements.<br />
<br />
Consider installing {{pkg|wine-gecko}} and {{pkg|wine-mono}} for applications that depend on Internet Explorer and .NET, respectively. These packages are not strictly required as Wine will download the relevant files as needed. However, having the files downloaded in advance allows you to work off-line and makes it so Wine does not download the files for each Wine prefix needing them.<br />
<br />
=== Third-party applications ===<br />
<br />
These have their own communities and websites, and are '''not supported''' by the main Wine community. See [https://wiki.winehq.org/Third_Party_Applications Wine Wiki] for more details.<br />
<br />
* {{App|[[CrossOver]]|Paid, commercialized version of Wine which provides more comprehensive end-user support.|https://www.codeweavers.com|{{AUR|crossover}}}}<br />
* {{App|exe-thumbnailer|Generates thumbnails for Windows executable files (.exe, .lnk, .msi, and .dll).|https://github.com/exe-thumbnailer/exe-thumbnailer|{{AUR|exe-thumbnailer}}}}<br />
* {{App|[[Wikipedia:Lutris|Lutris]]|Gaming launcher for all types of games, including Wine games (with prefix management), native Linux games and emulators.|https://lutris.net|{{Pkg|lutris}}}}<br />
* {{App|[[Wikipedia:PlayOnLinux|PlayOnLinux]]|Graphical prefix manager for Wine. Contains scripts to assist with program installation and configuration.|https://www.playonlinux.com|{{Pkg|playonlinux}}}}<br />
* {{App|Proton|Compatibility tool made for [[Steam]] based on Wine and additional components. See [https://www.protondb.com/ ProtonDB] for compatibility list.|https://github.com/ValveSoftware/Proton|{{AUR|proton}}}}<br />
* {{App|PyWinery|Simple graphical prefix manager for Wine.|https://github.com/ergoithz/pywinery|{{AUR|pywinery}}}}<br />
* {{App|Q4Wine|Graphical prefix manager for Wine. Can export [[Qt]] themes into the Wine configuration for better integration.|https://sourceforge.net/projects/q4wine/|{{AUR|q4wine}}{{Broken package link|package not found}}}}<br />
* {{App|Bottles|Graphical prefix and runners manager for Wine based on GTK.|https://usebottles.com/|{{AUR|bottles}}}}<br />
<br />
== Configuration ==<br />
<br />
Configuring Wine is typically accomplished using:<br />
<br />
* [https://wiki.winehq.org/Winecfg winecfg] is a GUI configuration tool for Wine, which can be started by running {{ic|winecfg}}.<br />
* [https://wiki.winehq.org/Regedit regedit] is Wine's registry editing tool, which can be started by running {{ic|regedit}}. See WineHQ's article on [https://wiki.winehq.org/Useful_Registry_Keys Useful Registry Keys].<br />
* [https://wiki.winehq.org/Control control] is Wine's implementation of the Windows Control Panel, which can be started by running {{ic|wine control}}.<br />
* See WineHQ's [https://wiki.winehq.org/List_of_Commands List of Commands] for the full list.<br />
<br />
=== WINEPREFIX ===<br />
<br />
By default, Wine stores its configuration files and installed Windows programs in {{ic|~/.wine}}. This directory is commonly called a "Wine prefix" or "Wine bottle". It is created/updated automatically whenever you run a Windows program or one of Wine's bundled programs such as ''winecfg''. The prefix directory also contains a tree which your Windows programs will see as {{ic|C:}} (the C-drive).<br />
<br />
You can override the location Wine uses for a prefix with the {{ic|WINEPREFIX}} [[environment variable]]. This is useful if you want to use separate configurations for different Windows programs. The first time a program is run with a new Wine prefix, Wine will automatically create a directory with a bare C-drive and registry.<br />
<br />
For example, if you run one program with {{ic|1= $ env WINEPREFIX=~/.win-a wine program-a.exe}}, and another with {{ic|1= $ env WINEPREFIX=~/.win-b wine program-b.exe}}, the two programs will each have a separate C-drive and separate registries.<br />
<br />
{{Note|Wine prefixes are not [[Wikipedia:Sandbox (computer security)|sandboxes]]! Programs running under Wine can still access the rest of the system! (for example, {{ic|Z:}} is mapped to {{ic|/}}, regardless of the Wine prefix).}}<br />
<br />
To create a default prefix without running a Windows program or other GUI tool you can use:<br />
<br />
$ env WINEPREFIX=~/.customprefix wineboot -u<br />
<br />
=== WINEARCH ===<br />
<br />
Wine will start a 64-bit environment by default. You can change this behavior using the {{ic|WINEARCH}} [[environment variable]]. Rename your {{ic|~/.wine}} directory and create a new Wine environment by running {{ic|1=$ WINEARCH=win32 winecfg}}. This will get you a 32-bit Wine environment. Not setting {{ic|WINEARCH}} will get you a 64-bit one.<br />
<br />
You can combine this with {{ic|WINEPREFIX}} to make a separate {{ic|win32}} and {{ic|win64}} environment:<br />
<br />
$ WINEARCH=win32 WINEPREFIX=~/win32 winecfg<br />
$ WINEPREFIX=~/win64 winecfg<br />
<br />
You can also use {{ic|WINEARCH}} in combination with other Wine programs, such as ''winetricks'' (using Steam as an example):<br />
<br />
WINEARCH=win32 WINEPREFIX=~/.local/share/wineprefixes/steam winetricks steam<br />
<br />
In order to see the architecture of an existing prefix you can check its registry file. The command below reads the system registry of the {{ic|~/.wine}} prefix and returns {{ic|1=#arch=win32}} or {{ic|1=#arch=win64}} depending on the architecture type:<br />
<br />
$ grep '#arch' ~/.wine/system.reg<br />
<br />
=== Graphics drivers ===<br />
<br />
You need to install the 32-bit version of your graphics driver. Please install the package that is listed in the ''OpenGL (multilib)'' column in the table in [[Xorg#Driver installation]].<br />
<br />
A good sign that your drivers are inadequate or not properly configured is when Wine reports the following in your terminal window:<br />
<br />
Direct rendering is disabled, most likely your OpenGL drivers have not been installed correctly<br />
<br />
{{Note|You might need to restart X after having installed the correct library.}}<br />
<br />
=== Sound ===<br />
<br />
By default sound issues may arise when running Wine applications. Ensure only one sound device is selected in ''winecfg''.<br />
<br />
Install the correct packages for the audio driver you want to use:<br />
<br />
* For [[ALSA]] install {{Pkg|lib32-alsa-lib}} and {{Pkg|lib32-alsa-plugins}}<br />
* For [[PulseAudio]] install {{Pkg|lib32-libpulse}} <br />
* For [[PipeWire]] install either {{Pkg|pipewire-pulse}} and {{Pkg|lib32-libpulse}} or {{Pkg|pipewire-alsa}} and {{Pkg|lib32-alsa-lib}} + {{Pkg|lib32-alsa-plugins}}<br />
* For [[OSS]] install {{Pkg|lib32-alsa-oss}}<br />
<br />
Additional packages: <br />
<br />
* Games that use advanced sound systems (''e.g.'' TESV: Skyrim) may additionally require installations of {{Pkg|lib32-openal}}.<br />
<br />
If ''winecfg'' '''still''' fails to detect the audio driver (Selected driver: (none)), [https://wiki.winehq.org/Wine_User's_Guide#Using_Regedit configure it via the registry]. For example, in a case where the microphone was not working in a 32-bit Windows application on a 64-bit stock install of wine-1.9.7, this provided full access to the sound hardware (sound playback and mic): open ''regedit'', look for the key HKEY_CURRENT_USER → Software → Wine → Drivers, and add a string called ''Audio'' and give it the value ''alsa''. Also, it may help to [[#WINEARCH|recreate the prefix]].<br />
<br />
==== MIDI support ====<br />
<br />
[[MIDI]] was a quite popular system for video games music in the 90's. If you are trying out old games, it is not uncommon that the music will not play out of the box.<br />
Wine has excellent MIDI support. However you first need to make it work on your host system, as explained in [[MIDI]]. Last but not least you need to make sure Wine will use the correct MIDI output.<br />
<br />
=== Other dependencies ===<br />
<br />
Some applications may require additional packages for the following purposes:<br />
<br />
* playing music: {{Pkg|lib32-mpg123}}<br />
* native image manipulation libraries: {{Pkg|lib32-giflib}} and {{Pkg|lib32-libpng}}<br />
* encryption support: {{Pkg|lib32-gnutls}}<br />
* 32-bit video codecs: {{Pkg|lib32-gst-plugins-base}}, {{Pkg|lib32-gst-plugins-good}}, {{Aur|lib32-gst-plugins-bad}} and {{Aur|lib32-gst-plugins-ugly}}<br />
* NTLM authentication: {{Pkg|samba}}<br />
<br />
=== Fonts ===<br />
<br />
If Wine applications are not showing easily readable fonts, you may not have any fonts installed. To easily link all of the system fonts so they are accessible from wine:<br />
<br />
$ cd ${WINEPREFIX:-~/.wine}/drive_c/windows/Fonts && for i in /usr/share/fonts/**/*.{ttf,otf}; do ln -s "$i" ; done<br />
<br />
Wine uses FreeType to render fonts, and FreeType's defaults changed a few releases ago. Try using this environment setting for wine programs:<br />
<br />
FREETYPE_PROPERTIES="truetype:interpreter-version=35"<br />
<br />
Another possibility is to install Microsoft's TrueType fonts into your wine prefix. See [[MS Fonts]]. If this does not help, try running {{ic|winetricks corefonts}} first, then {{ic|winetricks allfonts}} as a last resort.<br />
<br />
After running such programs, kill all Wine servers and run {{ic|winecfg}}. Fonts should be legible now.<br />
<br />
If the fonts look somehow smeared, import the following text file into the Wine registry with [https://wiki.winehq.org/FAQ#How_do_I_edit_the_Wine_registry.3F regedit]:<br />
<br />
Windows Registry Editor Version 5.00<br />
[HKEY_CURRENT_USER\Software\Wine\X11 Driver]<br />
"ClientSideWithRender"="N"<br />
<br />
For high resolution displays, you can adjust dpi values in winecfg.<br />
<br />
See also [[Font configuration#Applications without fontconfig support]].<br />
<br />
==== Enable font smoothing ====<br />
<br />
A good way to improve wine font rendering is to enable cleartype font smoothing.<br />
To enable "Subpixel smoothing (ClearType) RGB":<br />
<br />
{{bc|<nowiki><br />
cat << EOF > /tmp/fontsmoothing<br />
REGEDIT4<br />
<br />
[HKEY_CURRENT_USER\Control Panel\Desktop]<br />
"FontSmoothing"="2"<br />
"FontSmoothingOrientation"=dword:00000001<br />
"FontSmoothingType"=dword:00000002<br />
"FontSmoothingGamma"=dword:00000578<br />
EOF<br />
<br />
WINE=${WINE:-wine} WINEPREFIX=${WINEPREFIX:-$HOME/.wine} $WINE regedit /tmp/fontsmoothing 2> /dev/null<br />
</nowiki>}}<br />
<br />
For more information, check [https://askubuntu.com/a/219795 the original answer]<br />
<br />
=== Desktop launcher menus ===<br />
<br />
When a Windows application installer creates a shortcut Wine creates a [[.desktop]] file instead. The default locations for those files in Arch Linux are:<br />
<br />
* Desktop shortcuts are put in {{ic|~/Desktop}}<br />
* Start menu shortcuts are put in {{ic|~/.local/share/applications/wine/Programs/}}<br />
<br />
{{Note|1=Wine does not support installing Windows applications for all users, so it will not put ''.desktop'' files in {{ic|/usr/share/applications}}. See WineHQ bug [https://bugs.winehq.org/show_bug.cgi?id=11112 11112]}}<br />
<br />
{{Tip|If menu items were ''not'' created while installing software or have been lost, {{ic|wine winemenubuilder}} may be of some use.}}<br />
<br />
==== Creating menu entries for Wine utilities ====<br />
<br />
By default, installation of Wine does not create desktop menus/icons for the software which comes with Wine (e.g. for ''winecfg'', ''winebrowser'', etc). This can be achieved by installing {{AUR|wine-installer}} or {{AUR|wine-installer-git}} meta-package (the latter has no additional dependencies), otherwise these instructions will add entries for these applications.<br />
<br />
First, install a Windows program using Wine to create the base menu. After the base menu is created, you can create the following files in {{ic|~/.local/share/applications/wine/}}:<br />
<br />
{{hc|wine-browsedrive.desktop|2=<br />
[Desktop Entry]<br />
Name=Browse C: Drive<br />
Comment=Browse your virtual C: drive<br />
Exec=wine winebrowser c:<br />
Terminal=false<br />
Type=Application<br />
Icon=folder-wine<br />
Categories=Wine;<br />
}}<br />
<br />
{{hc|wine-uninstaller.desktop|2=<br />
[Desktop Entry]<br />
Name=Uninstall Wine Software<br />
Comment=Uninstall Windows applications for Wine<br />
Exec=wine uninstaller<br />
Terminal=false<br />
Type=Application<br />
Icon=wine-uninstaller<br />
Categories=Wine;<br />
}}<br />
<br />
{{hc|wine-winecfg.desktop|2=<br />
[Desktop Entry]<br />
Name=Configure Wine<br />
Comment=Change application-specific and general Wine options<br />
Exec=winecfg<br />
Terminal=false<br />
Icon=wine-winecfg<br />
Type=Application<br />
Categories=Wine;<br />
}}<br />
<br />
And create the following file in {{ic|~/.config/menus/applications-merged/}}:<br />
<br />
{{hc|wine.menu|<nowiki><br />
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"<br />
"http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd"><br />
<Menu><br />
<Name>Applications</Name><br />
<Menu><br />
<Name>wine-wine</Name><br />
<Directory>wine-wine.directory</Directory><br />
<Include><br />
<Category>Wine</Category><br />
</Include><br />
</Menu><br />
</Menu><br />
</nowiki>}}<br />
<br />
If these settings produce a ugly/non-existent icon, it means that there are no icons for these launchers in the icon set that you have enabled. You should replace the icon settings with the explicit location of the icon that you want. Clicking the icon in the launcher's properties menu will have the same effect. A great icon set that supports these shortcuts is [https://www.gnome-look.org/content/show.php/GNOME-colors?content=82562 GNOME-colors].<br />
<br />
==== Removing menu entries ====<br />
<br />
Menu entries created by Wine are located in {{ic|~/.local/share/applications/wine/Programs/}}. Remove the program's ''.desktop'' entry to remove the application from the menu.<br />
<br />
In addition to remove unwanted extensions binding by Wine, execute the following commands (taken from the Wine website):<br />
<br />
$ rm ~/.local/share/mime/packages/x-wine*<br />
$ rm ~/.local/share/applications/wine-extension*<br />
$ rm ~/.local/share/icons/hicolor/*/*/application-x-wine-extension*<br />
$ rm ~/.local/share/mime/application/x-wine-extension*<br />
<br />
Sometimes you should also remove {{ic|wine-*.menu}} files from {{ic|/.config/menus/}} to completely remove items from wine submenu in kde.<br />
<br />
=== Appearance ===<br />
<br />
A similar to XP-looking theme can be [https://archive.org/download/zune-desktop-theme/ZuneDesktopTheme.msi downloaded]. To install it, see [https://wiki.winehq.org/Wine_User%27s_Guide#Running_.msi_files this upstream wiki article]. Lastly, use ''winecfg'' to select it.<br />
<br />
{{Note|The theme linked above can only be installed on 32-bit prefixes with Windows XP as the prefix version. To install it on 64-bit prefixes, you might want to create a temporary 32-bit prefix, install the theme and copy the {{ic|Zune}} folder and {{ic|Zune.theme}} files from {{ic|drive_c/Windows/Resources/Themes}} in that prefix to the same location in your usual prefix.}}<br />
<br />
Wine staging users may instead want to try enabling the option ''Enable GTK3 Theming'' under the Staging section of ''winecfg'' for a theme that matches the current GTK theme.<br />
<br />
=== Printing ===<br />
<br />
In order to use your installed printers (both local and network) with wine applications in ''win32 prefixes'' (e.g. MS Word), install the {{Pkg|lib32-libcups}} package, reboot wine (''wineboot'') and restart your wine application.<br />
<br />
=== Networking ===<br />
<br />
After installation, the {{pkg|lib32-gnutls}} package may need to be [[install]]ed for applications making TLS or HTTPS connections to work.<br />
<br />
For ICMP (ping), Wine may need the network access as described in the [https://wiki.winehq.org/FAQ#Failed_to_use_ICMP_.28network_ping.29.2C_this_requires_special_permissions WineHQ FAQ]:<br />
<br />
# setcap cap_net_raw+epi /usr/bin/wine-preloader<br />
<br />
If issues arise after this (such as an unhandled exception or privileged instruction), remove via:<br />
<br />
# setcap -r /usr/bin/wine-preloader<br />
<br />
== Usage ==<br />
<br />
{{Warning|Do not run or install Wine applications as root! See [https://wiki.winehq.org/FAQ#Should_I_run_Wine_as_root.3F Wine FAQ] for details.}}<br />
<br />
See [https://wiki.winehq.org/Wine_User%27s_Guide#Using_Wine Wine User's Guide] for general information on Wine usage.<br />
<br />
See [https://appdb.winehq.org/ Wine Application Database (AppDB)] for additional information on specific Windows applications in Wine.<br />
<br />
=== Wayland ===<br />
<br />
Currently Wine does not support Wayland directly, but you can use [[Wayland#XWayland|XWayland]] instead.<br />
<br />
There are some efforts to support Wayland though:<br />
<br />
* Experimental Wayland driver for Wine, which supports using OpenGL- and Windows GDI-applications. See [https://www.winehq.org/pipermail/wine-devel/2020-December/178575.html this] and [https://www.winehq.org/pipermail/wine-devel/2021-February/181325.html this] wine-devel maillist entries.<br />
* [https://github.com/varmd/wine-wayland wine-wayland]: a custom version of Wine, which supports Wayland via Vulkan (so it supports only: DirectX 9, 10 and 11 via [[#DXVK]] and Vulkan-compatible applications).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Wineconsole ===<br />
<br />
Often you may need to run ''.exe'''s to patch game files, for example a widescreen mod for an old game, and running the ''.exe'' normally through Wine might yield nothing happening. In this case, you can open a terminal and run the following command:<br />
<br />
$ wineconsole cmd<br />
<br />
Then navigate to the directory and run the ''.exe'' file from there.<br />
<br />
=== Winetricks ===<br />
<br />
[https://wiki.winehq.org/Winetricks Winetricks] is a script to allow one to install base requirements needed to run Windows programs. Installable components include DirectX 9.x, MSXML (required by Microsoft Office 2007 and Internet Explorer), Visual Runtime libraries and many more.<br />
<br />
[[Install]] the {{pkg|winetricks}} package (or alternatively {{AUR|winetricks-git}}). Then run it with:<br />
$ winetricks<br />
<br />
For using GUI you should [[install]] the {{pkg|zenity}}.<br />
<br />
=== Performance ===<br />
<br />
==== CSMT ====<br />
<br />
CSMT is a technology used by Wine to use a separate thread for the OpenGL calls to improve performance noticeably. Since Wine 3.2, CSMT is enabled by default. However, CSMT support needs to be enabled manually for Wine versions lower than 3.2. For vanilla Wine run {{ic|wine regedit}} and set the DWORD value for ''HKEY_CURRENT_USER -> Software > Wine > Direct3D > csmt'' to 0x01 (enabled). For wine-staging run {{ic|winecfg}} and enable it in the staging tab.<br />
<br />
Note that CSMT may actually hurt performance for some applications - if this is the case, disable it by creating/setting the registry value to 0x00 (disabled).<br />
<br />
Further information:<br />
*[https://www.phoronix.com/forums/showthread.php?93967-Wine-s-Big-Command-Stream-D3D-Patch-Set-Updated/page3&s=7775d7c3d4fa698089d5492bb7b1a435 Phoronix Forum discussion] with the CSMT developer Stefan Dösinger<br />
<br />
==== Force OpenGL mode in games ====<br />
<br />
Some games might have an OpenGL mode which ''may'' perform better than their default DirectX mode. While the steps to enable OpenGL rendering is ''application specific'', many games accept the {{Ic|-opengl}} parameter.<br />
<br />
$ wine ''/path/to/3d_game.exe'' -opengl<br />
<br />
You should of course refer to your application's documentation and Wine's [https://appdb.winehq.org AppDB] for such application specific information.<br />
<br />
==== DXVK ====<br />
<br />
[https://github.com/doitsujin/dxvk DXVK] is a promising new implementation for DirectX 9, 10 & 11 over Vulkan. This should allow for greater performance, and in some cases, even better compatibility. Battlefield 1 for example, only runs under DXVK. On the other hand, DXVK does not support all Wine games (yet).<br />
<br />
To use it, install {{aur|dxvk-bin}}. Then run the following command to activate it in your Wineprefix (by default {{ic|~/.wine}}):<br />
$ WINEPREFIX=''your-prefix'' setup_dxvk install<br />
<br />
{{Note|For Wine versions below 3.5 you need to configure Vulkan support manually, following the instructions at [https://github.com/roderickc/wine-vulkan GitHub].}}<br />
<br />
{{Warning|DXVK overrides the DirectX 10 and 11 DLLs, which may be considered cheating in online multiplayer games, and may get your account '''banned'''. Use at your own risk!}}<br />
<br />
==== Gallium Nine ====<br />
<br />
With the open-source gallium-based drivers (mostly AMD and Intel cards) there is a [https://wiki.ixit.cz/d3d9 Gallium Direct3D state tracker] that aims to provide nearly-native performance for DirectX 9. In most cases it has less visual glitches than the upstream wine and doubles the performances. It consumes much less CPU time than CSMT.<br />
<br />
Install {{Pkg|wine-nine}} to use it. This is a standalone package that can be installed with any Wine version. Use {{ic|wine ninewinecfg}} to check if it is enabled.<br />
<br />
For older Intel graphics (gen4-7: GMA 3000, GMA 4500, HD 2000-5000; year 2006-2014) Crocus Gallium driver should be used instead of i965 since Mesa 21.2. [[Export]] the following environment variable before running Wine: <br />
<br />
MESA_LOADER_DRIVER_OVERRIDE=crocus<br />
<br />
=== Unregister existing Wine file associations ===<br />
<br />
By default, Wine takes over as the default application for a lot of formats. Some (e.g. {{ic|vbs}} or {{ic|chm}}) are Windows-specific, and opening them with Wine can be a convenience. However, having other formats (e.g. {{ic|gif}}, {{ic|jpeg}}, {{ic|txt}}, {{ic|js}}) open in Wine's bare-bones simulations of Internet Explorer and Notepad can be annoying.<br />
<br />
Wine's file associations are set in {{ic|~/.local/share/applications/}} as {{ic|wine-extension-''extension''.desktop}} files. Delete the files corresponding to the extensions you want to unregister. Or, to remove all wine extensions:<br />
<br />
$ rm -f ~/.local/share/applications/wine-extension*.desktop<br />
$ rm -f ~/.local/share/icons/hicolor/*/*/application-x-wine-extension*<br />
<br />
Next, remove the old cache:<br />
<br />
$ rm -f ~/.local/share/applications/mimeinfo.cache<br />
$ rm -f ~/.local/share/mime/packages/x-wine*<br />
$ rm -f ~/.local/share/mime/application/x-wine-extension*<br />
<br />
And, update the cache:<br />
<br />
$ update-desktop-database ~/.local/share/applications<br />
$ update-mime-database ~/.local/share/mime/<br />
<br />
Please note Wine will still create new file associations and even recreate the file associations if the application sets the file associations again.<br />
<br />
=== Prevent Wine from creating filetype associations ===<br />
<br />
{{Note|This has to be done for each WINEPREFIX which should not update file associations unless you opt to change {{ic|/usr/share/wine/wine.inf}} .}}<br />
This method prevents the creation of filetype associations but retains the creation of XDG .desktop files (that you might see e.g. in menus).<br />
<br />
If you want to stop wine from creating filetype associations via winecfg you have to uncheck the "Manage File Associations" checkbox under the Desktop Integration tab. See [https://wiki.winehq.org/FAQ#How_can_I_prevent_Wine_from_changing_the_filetype_associations_on_my_system_or_adding_unwanted_menu_entries.2Fdesktop_links.3F Wine FAQ]<br />
<br />
To make the same change via registry add the string {{ic|Enable}} with value {{ic|N}} under:<br />
<br />
HKEY_CURRENT_USER\Software\Wine\FileOpenAssociations<br />
<br />
''You might have to create the key {{ic|FileOpenAssociations}} first!''<br />
<br />
If you want to apply this by default for new WINEPREFIXES, edit {{ic|/usr/share/wine/wine.inf}} and add this line for example under the {{ic|[Services]}} section:<br />
HKCU,"Software\Wine\FileOpenAssociations","Enable",2,"N"<br />
<br />
To prevent a package upgrade from overriding the modified file, create a pacman hook to make the change automatically:<br />
<br />
{{hc|1=/etc/pacman.d/hooks/stop-wine-associations.hook|2=<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Upgrade<br />
Type = Path<br />
Target = usr/share/wine/wine.inf<br />
<br />
[Action]<br />
Description = Stopping Wine from hijacking file associations...<br />
When = PostTransaction<br />
<nowiki>Exec = /bin/sh -c '/usr/bin/grep -q "HKCU,\"Software\\\Wine\\\FileOpenAssociations\",\"Enable\",2,\"N\"" /usr/share/wine/wine.inf || /usr/bin/sed -i "s/\[Services\]/\[Services\]\nHKCU,\"Software\\\Wine\\\FileOpenAssociations\",\"Enable\",2,\"N\"/g" /usr/share/wine/wine.inf'</nowiki><br />
}}<br />
<br />
See [[Pacman#Hooks]]<br />
<br />
=== Execute Windows binaries with Wine implicitly ===<br />
<br />
The {{pkg|wine}} package installs a ''binfmt'' file which will allows you to run Windows programs directly, e.g. {{ic|''./myprogram.exe''}} will launch as if you had typed {{ic|wine ''./myprogram.exe''}}. Service starts by default on boot, if you have not rebooted after installing Wine you can [[start]] {{ic|systemd-binfmt.service}} to use it right away.<br />
<br />
{{Note|Make sure the Windows binary is [[executable]], otherwise the binary will not run.}}<br />
<br />
=== Dual Head with different resolutions ===<br />
<br />
If you have issues with dual-head setups and different display resolutions you are probably missing {{Pkg|lib32-libxrandr}}.<br />
<br />
Also installing {{Pkg|lib32-libxinerama}} might fix dual-head issues with wine (for example, unclickable buttons and menus of application in the right most or bottom most monitor, not redrawable interface of application in that zone, dragging mouse cursor state stucked after leaving application area).<br />
<br />
=== Burning optical media ===<br />
<br />
To burn CDs or DVDs, you will need to load the {{ic|sg}} [[kernel module]].<br />
<br />
=== Proper mounting of optical media images ===<br />
<br />
Some applications will check for the optical media to be in drive. They may check for data only, in which case it might be enough to configure the corresponding path as being a CD-ROM drive in ''winecfg''.<br />
However, other applications will look for a media name and/or a serial number, in which case the image has to be mounted with these special properties.<br />
<br />
Some virtual drive tools do not handle these metadata, like fuse-based virtual drives (Acetoneiso for instance). [[CDemu]] will handle it correctly.<br />
<br />
=== Show FPS overlay in games ===<br />
<br />
Wine features an embedded FPS monitor which works for all graphical applications if the environment variable {{ic|1=WINEDEBUG=fps}} is set. This will output the framerate to stdout. You can display the FPS on top of the window thanks to {{ic|osd_cat}} from the {{pkg|xosd}} package. See [https://gist.github.com/anonymous/844aefd70bb50bf72b35 winefps.sh] for a helper script.<br />
<br />
=== Running Wine under a separate user account ===<br />
<br />
It may be desirable to run Wine under a specifically created user account in order to reduce concerns about Windows applications having access to your home directory.<br />
<br />
First, create a [[user account]] for Wine:<br />
<br />
# useradd -m -s /bin/bash wineuser<br />
<br />
Now switch to another TTY and start your X WM or DE as you normally would or keep reading...<br />
<br />
{{Note|The following approach only works when enabling root for Xorg. See [[Xorg#Rootless Xorg]] for more information on how to execute the {{ic|xhost}} command under your main user.}}<br />
<br />
Afterwards, in order to open Wine applications using this new user account you need to add the new user to the X server permissions list:<br />
<br />
$ xhost +SI:localuser:wineuser<br />
<br />
Finally, you can run Wine via the following command, which uses {{ic|env}} to launch Wine with the environment variables it expects:<br />
<br />
$ sudo -u wineuser env HOME=/home/wineuser USER=wineuser USERNAME=wineuser LOGNAME=wineuser wine ''arguments''<br />
<br />
It is possible to automate the process of running Windows applications with Wine via this method by using a shell script as follows:<br />
{{hc|1=/usr/local/bin/runaswine|2=<br />
#!/bin/bash<br />
xhost +SI:localuser:wineuser<br />
sudo -u wineuser env HOME=/home/wineuser USER=wineuser USERNAME=wineuser LOGNAME=wineuser wine "$@"}}<br />
<br />
Wine applications can then be launched via:<br />
<br />
$ runaswine ''"C:\path\to\application.exe"''<br />
<br />
In order to not be asked for a password each time Wine is run as another user the following entry can be added to the sudoers file: {{ic|1=''mainuser'' ALL=(wineuser) NOPASSWD: ALL}}. See [[Sudo#Configuration]] for more information.<br />
<br />
It is recommended to run {{ic|winecfg}} as the Wine user and remove all bindings for directories outside the home directory of the Wine user in the "Desktop Integration" section of the configuration window so no program run with Wine has read access to any file outside the special user's home directory.<br />
<br />
Keep in mind that audio will probably be non-functional in Wine programs which are run this way if [[PulseAudio]] is used. See [[PulseAudio/Examples#Allowing multiple users to share a PulseAudio daemon]] for information about allowing the Wine user to access the PulseAudio daemon of the principal user.<br />
<br />
=== Temp directory on tmpfs ===<br />
<br />
To prevent Wine from writing its temporary files to a physical disk, one can define an alternative location, like ''tmpfs''. Remove Wine's default directory for temporary files and creating a symlink:<br />
<br />
$ rm -r ~/.wine/drive_c/users/$USER/Temp<br />
$ ln -s /tmp/ ~/.wine/drive_c/users/$USER/Temp<br />
<br />
=== Prevent installing Mono/Gecko ===<br />
<br />
If Gecko and/or Mono are not present on the system nor in the Wine prefix, Wine will prompt to download them from the internet. If you do not need Gecko and/or Mono, you might want to disable this dialog, by setting the {{ic|WINEDLLOVERRIDES}} [[environment variable]] to {{ic|1=mscoree=d;mshtml=d}}.<br />
<br />
=== Vulkan ===<br />
<br />
Vulkan support is included, since Wine 3.3. The default Wine Vulkan ICD loader works fine for most applications, but does not support advanced features, like Vulkan layers. To use these features, you have to install the official Vulkan SDK, see step 2-4 on the original Vulkan patches author's [https://github.com/roderickc/wine-vulkan GitHub page].<br />
<br />
{{Note|The Wine ICD loader was added in Wine 3.5, you need to install the official Vulkan SDK to use Vulkan in Wine 3.3 and 3.4}}<br />
<br />
=== Remove Wine file bindings ===<br />
<br />
For security reasons it may be useful to remove the preinstalled Wine bindings so Windows applications cannot be launched directly from a file manager or from the browser (Firefox offers to open EXE files directly with Wine!).<br />
If you want to do this, you may add the following to the {{ic|1= [options]}} section in {{ic|1= /etc/pacman.conf}}<br />
<br />
NoExtract = usr/lib/binfmt.d/wine.conf<br />
NoExtract = usr/share/applications/wine.desktop<br />
<br />
== Troubleshooting ==<br />
<br />
See [https://wiki.winehq.org/Wine_User%27s_Guide#Troubleshooting_.2F_Reporting_bugs Wine User's Guide] and [https://wiki.winehq.org/FAQ Wine FAQ] (especially its [https://wiki.winehq.org/FAQ#Troubleshooting Troubleshooting] section) for general tips.<br />
<br />
Also refer to the [https://appdb.winehq.org/ Wine AppDB] for an advice on specific applications.<br />
<br />
=== XWayland problems ===<br />
<br />
If you use Wine under [[Wayland#XWayland|XWayland]], you can activate the option for "Emulating a virtual desktop" in the Graphics Tab in winecfg, to avoid problems with:<br />
<br />
* flickering;<br />
* wrong window location;<br />
* wrong mouse cursor location and clicks;<br />
* keyboard detection.<br />
<br />
=== Keyboard input not working ===<br />
<br />
Try toggling the ''Window settings'' in the ''Graphics'' tab of ''winecfg'', click ''Apply'' and then change them back. If that does not work, try changing individual settings.<br />
<br />
If the keyboard does not work after unfocusing the application, try editing the registry:<br />
Under ''HKEY_CURRENT_USER\Software\Wine\X11 Driver'', add a string value ''UseTakeFocus'' and set it to ''N''.<br />
<br />
Alternatively, you can use winetricks to set the value.<br />
winetricks usetakefocus=n<br />
<br />
== See also ==<br />
<br />
* [https://www.winehq.org/ Wine Homepage]<br />
* [https://wiki.winehq.org/ Wine Wiki]<br />
* [https://appdb.winehq.org/ Wine Application Database (AppDB)] - Information about running specific Windows applications (Known issues, ratings, guides, etc tailored to specific applications)<br />
* [https://forum.winehq.org/ Wine Forums] - A great place to ask questions ''after'' you have looked through the FAQ and AppDB<br />
* [[Gentoo:Wine]]<br />
* [https://www.darlinghq.org/ Darling] - a similar project for MacOS software</div>Jwh7https://wiki.archlinux.org/index.php?title=Wine&diff=715234Wine2022-02-02T21:25:21Z<p>Jwh7: /* Keyboard input not working */ Add winecfg fix</p>
<hr />
<div>[[Category:Emulation]]<br />
[[Category:Gaming]]<br />
[[de:Wine]]<br />
[[fr:Wine]]<br />
[[ja:Wine]]<br />
[[ru:Wine]]<br />
[[zh-hans:Wine]]<br />
{{Related articles start}}<br />
{{Related|CrossOver}}<br />
{{Related|Deepin-wine}}<br />
{{Related|Wine package guidelines}}<br />
{{Related articles end}}<br />
[[Wikipedia:Wine (software)|Wine]] is a ''compatibility layer'' capable of running Microsoft Windows applications on Unix-like operating systems. Programs running in Wine act as native programs would, without the performance/memory penalties of an emulator.<br />
<br />
{{Warning|<br />
* Wine is not isolated from your system.<br />
* If you can access a file or resource with your user account, programs running in Wine can too. See [[#Running Wine under a separate user account]] and [[Security#Sandboxing applications]] for possible precautions.<br />
* Wine can also run Malware (see [https://wiki.winehq.org/FAQ#Is_Wine_malware-compatible.3F Wine FAQ on Malware compatibility])}}<br />
<br />
== Installation ==<br />
<br />
Wine can be installed by enabling the [[multilib]] repository and [[install]]ing the {{Pkg|wine}} (stable) or {{Pkg|wine-staging}} (testing) package. [https://wine-staging.com/ Wine Staging] is a patched version of [https://www.winehq.org/ Wine], which contains bug fixes and features that have not been integrated into the stable or development branch yet. <br />
<br />
See also [[#Graphics drivers]] and [[#Sound]] for additional requirements.<br />
<br />
Consider installing {{pkg|wine-gecko}} and {{pkg|wine-mono}} for applications that depend on Internet Explorer and .NET, respectively. These packages are not strictly required as Wine will download the relevant files as needed. However, having the files downloaded in advance allows you to work off-line and makes it so Wine does not download the files for each Wine prefix needing them.<br />
<br />
=== Third-party applications ===<br />
<br />
These have their own communities and websites, and are '''not supported''' by the main Wine community. See [https://wiki.winehq.org/Third_Party_Applications Wine Wiki] for more details.<br />
<br />
* {{App|[[CrossOver]]|Paid, commercialized version of Wine which provides more comprehensive end-user support.|https://www.codeweavers.com|{{AUR|crossover}}}}<br />
* {{App|exe-thumbnailer|Generates thumbnails for Windows executable files (.exe, .lnk, .msi, and .dll).|https://github.com/exe-thumbnailer/exe-thumbnailer|{{AUR|exe-thumbnailer}}}}<br />
* {{App|[[Wikipedia:Lutris|Lutris]]|Gaming launcher for all types of games, including Wine games (with prefix management), native Linux games and emulators.|https://lutris.net|{{Pkg|lutris}}}}<br />
* {{App|[[Wikipedia:PlayOnLinux|PlayOnLinux]]|Graphical prefix manager for Wine. Contains scripts to assist with program installation and configuration.|https://www.playonlinux.com|{{Pkg|playonlinux}}}}<br />
* {{App|Proton|Compatibility tool made for [[Steam]] based on Wine and additional components. See [https://www.protondb.com/ ProtonDB] for compatibility list.|https://github.com/ValveSoftware/Proton|{{AUR|proton}}}}<br />
* {{App|PyWinery|Simple graphical prefix manager for Wine.|https://github.com/ergoithz/pywinery|{{AUR|pywinery}}}}<br />
* {{App|Q4Wine|Graphical prefix manager for Wine. Can export [[Qt]] themes into the Wine configuration for better integration.|https://sourceforge.net/projects/q4wine/|{{AUR|q4wine}}{{Broken package link|package not found}}}}<br />
* {{App|Bottles|Graphical prefix and runners manager for Wine based on GTK.|https://usebottles.com/|{{AUR|bottles}}}}<br />
<br />
== Configuration ==<br />
<br />
Configuring Wine is typically accomplished using:<br />
<br />
* [https://wiki.winehq.org/Winecfg winecfg] is a GUI configuration tool for Wine, which can be started by running {{ic|winecfg}}.<br />
* [https://wiki.winehq.org/Regedit regedit] is Wine's registry editing tool, which can be started by running {{ic|regedit}}. See WineHQ's article on [https://wiki.winehq.org/Useful_Registry_Keys Useful Registry Keys].<br />
* [https://wiki.winehq.org/Control control] is Wine's implementation of the Windows Control Panel, which can be started by running {{ic|wine control}}.<br />
* See WineHQ's [https://wiki.winehq.org/List_of_Commands List of Commands] for the full list.<br />
<br />
=== WINEPREFIX ===<br />
<br />
By default, Wine stores its configuration files and installed Windows programs in {{ic|~/.wine}}. This directory is commonly called a "Wine prefix" or "Wine bottle". It is created/updated automatically whenever you run a Windows program or one of Wine's bundled programs such as ''winecfg''. The prefix directory also contains a tree which your Windows programs will see as {{ic|C:}} (the C-drive).<br />
<br />
You can override the location Wine uses for a prefix with the {{ic|WINEPREFIX}} [[environment variable]]. This is useful if you want to use separate configurations for different Windows programs. The first time a program is run with a new Wine prefix, Wine will automatically create a directory with a bare C-drive and registry.<br />
<br />
For example, if you run one program with {{ic|1= $ env WINEPREFIX=~/.win-a wine program-a.exe}}, and another with {{ic|1= $ env WINEPREFIX=~/.win-b wine program-b.exe}}, the two programs will each have a separate C-drive and separate registries.<br />
<br />
{{Note|Wine prefixes are not [[Wikipedia:Sandbox (computer security)|sandboxes]]! Programs running under Wine can still access the rest of the system! (for example, {{ic|Z:}} is mapped to {{ic|/}}, regardless of the Wine prefix).}}<br />
<br />
To create a default prefix without running a Windows program or other GUI tool you can use:<br />
<br />
$ env WINEPREFIX=~/.customprefix wineboot -u<br />
<br />
=== WINEARCH ===<br />
<br />
Wine will start a 64-bit environment by default. You can change this behavior using the {{ic|WINEARCH}} [[environment variable]]. Rename your {{ic|~/.wine}} directory and create a new Wine environment by running {{ic|1=$ WINEARCH=win32 winecfg}}. This will get you a 32-bit Wine environment. Not setting {{ic|WINEARCH}} will get you a 64-bit one.<br />
<br />
You can combine this with {{ic|WINEPREFIX}} to make a separate {{ic|win32}} and {{ic|win64}} environment:<br />
<br />
$ WINEARCH=win32 WINEPREFIX=~/win32 winecfg<br />
$ WINEPREFIX=~/win64 winecfg<br />
<br />
You can also use {{ic|WINEARCH}} in combination with other Wine programs, such as ''winetricks'' (using Steam as an example):<br />
<br />
WINEARCH=win32 WINEPREFIX=~/.local/share/wineprefixes/steam winetricks steam<br />
<br />
In order to see the architecture of an existing prefix you can check its registry file. The command below reads the system registry of the {{ic|~/.wine}} prefix and returns {{ic|1=#arch=win32}} or {{ic|1=#arch=win64}} depending on the architecture type:<br />
<br />
$ grep '#arch' ~/.wine/system.reg<br />
<br />
=== Graphics drivers ===<br />
<br />
You need to install the 32-bit version of your graphics driver. Please install the package that is listed in the ''OpenGL (multilib)'' column in the table in [[Xorg#Driver installation]].<br />
<br />
A good sign that your drivers are inadequate or not properly configured is when Wine reports the following in your terminal window:<br />
<br />
Direct rendering is disabled, most likely your OpenGL drivers have not been installed correctly<br />
<br />
{{Note|You might need to restart X after having installed the correct library.}}<br />
<br />
=== Sound ===<br />
<br />
By default sound issues may arise when running Wine applications. Ensure only one sound device is selected in ''winecfg''.<br />
<br />
Install the correct packages for the audio driver you want to use:<br />
<br />
* For [[ALSA]] install {{Pkg|lib32-alsa-lib}} and {{Pkg|lib32-alsa-plugins}}<br />
* For [[PulseAudio]] install {{Pkg|lib32-libpulse}} <br />
* For [[PipeWire]] install either {{Pkg|pipewire-pulse}} and {{Pkg|lib32-libpulse}} or {{Pkg|pipewire-alsa}} and {{Pkg|lib32-alsa-lib}} + {{Pkg|lib32-alsa-plugins}}<br />
* For [[OSS]] install {{Pkg|lib32-alsa-oss}}<br />
<br />
Additional packages: <br />
<br />
* Games that use advanced sound systems (''e.g.'' TESV: Skyrim) may additionally require installations of {{Pkg|lib32-openal}}.<br />
<br />
If ''winecfg'' '''still''' fails to detect the audio driver (Selected driver: (none)), [https://wiki.winehq.org/Wine_User's_Guide#Using_Regedit configure it via the registry]. For example, in a case where the microphone was not working in a 32-bit Windows application on a 64-bit stock install of wine-1.9.7, this provided full access to the sound hardware (sound playback and mic): open ''regedit'', look for the key HKEY_CURRENT_USER → Software → Wine → Drivers, and add a string called ''Audio'' and give it the value ''alsa''. Also, it may help to [[#WINEARCH|recreate the prefix]].<br />
<br />
==== MIDI support ====<br />
<br />
[[MIDI]] was a quite popular system for video games music in the 90's. If you are trying out old games, it is not uncommon that the music will not play out of the box.<br />
Wine has excellent MIDI support. However you first need to make it work on your host system, as explained in [[MIDI]]. Last but not least you need to make sure Wine will use the correct MIDI output.<br />
<br />
=== Other dependencies ===<br />
<br />
Some applications may require additional packages for the following purposes:<br />
<br />
* playing music: {{Pkg|lib32-mpg123}}<br />
* native image manipulation libraries: {{Pkg|lib32-giflib}} and {{Pkg|lib32-libpng}}<br />
* encryption support: {{Pkg|lib32-gnutls}}<br />
* 32-bit video codecs: {{Pkg|lib32-gst-plugins-base}}, {{Pkg|lib32-gst-plugins-good}}, {{Aur|lib32-gst-plugins-bad}} and {{Aur|lib32-gst-plugins-ugly}}<br />
* NTLM authentication: {{Pkg|samba}}<br />
<br />
=== Fonts ===<br />
<br />
If Wine applications are not showing easily readable fonts, you may not have any fonts installed. To easily link all of the system fonts so they are accessible from wine:<br />
<br />
$ cd ${WINEPREFIX:-~/.wine}/drive_c/windows/Fonts && for i in /usr/share/fonts/**/*.{ttf,otf}; do ln -s "$i" ; done<br />
<br />
Wine uses FreeType to render fonts, and FreeType's defaults changed a few releases ago. Try using this environment setting for wine programs:<br />
<br />
FREETYPE_PROPERTIES="truetype:interpreter-version=35"<br />
<br />
Another possibility is to install Microsoft's TrueType fonts into your wine prefix. See [[MS Fonts]]. If this does not help, try running {{ic|winetricks corefonts}} first, then {{ic|winetricks allfonts}} as a last resort.<br />
<br />
After running such programs, kill all Wine servers and run {{ic|winecfg}}. Fonts should be legible now.<br />
<br />
If the fonts look somehow smeared, import the following text file into the Wine registry with [https://wiki.winehq.org/FAQ#How_do_I_edit_the_Wine_registry.3F regedit]:<br />
<br />
Windows Registry Editor Version 5.00<br />
[HKEY_CURRENT_USER\Software\Wine\X11 Driver]<br />
"ClientSideWithRender"="N"<br />
<br />
For high resolution displays, you can adjust dpi values in winecfg.<br />
<br />
See also [[Font configuration#Applications without fontconfig support]].<br />
<br />
==== Enable font smoothing ====<br />
<br />
A good way to improve wine font rendering is to enable cleartype font smoothing.<br />
To enable "Subpixel smoothing (ClearType) RGB":<br />
<br />
{{bc|<nowiki><br />
cat << EOF > /tmp/fontsmoothing<br />
REGEDIT4<br />
<br />
[HKEY_CURRENT_USER\Control Panel\Desktop]<br />
"FontSmoothing"="2"<br />
"FontSmoothingOrientation"=dword:00000001<br />
"FontSmoothingType"=dword:00000002<br />
"FontSmoothingGamma"=dword:00000578<br />
EOF<br />
<br />
WINE=${WINE:-wine} WINEPREFIX=${WINEPREFIX:-$HOME/.wine} $WINE regedit /tmp/fontsmoothing 2> /dev/null<br />
</nowiki>}}<br />
<br />
For more information, check [https://askubuntu.com/a/219795 the original answer]<br />
<br />
=== Desktop launcher menus ===<br />
<br />
When a Windows application installer creates a shortcut Wine creates a [[.desktop]] file instead. The default locations for those files in Arch Linux are:<br />
<br />
* Desktop shortcuts are put in {{ic|~/Desktop}}<br />
* Start menu shortcuts are put in {{ic|~/.local/share/applications/wine/Programs/}}<br />
<br />
{{Note|1=Wine does not support installing Windows applications for all users, so it will not put ''.desktop'' files in {{ic|/usr/share/applications}}. See WineHQ bug [https://bugs.winehq.org/show_bug.cgi?id=11112 11112]}}<br />
<br />
{{Tip|If menu items were ''not'' created while installing software or have been lost, {{ic|wine winemenubuilder}} may be of some use.}}<br />
<br />
==== Creating menu entries for Wine utilities ====<br />
<br />
By default, installation of Wine does not create desktop menus/icons for the software which comes with Wine (e.g. for ''winecfg'', ''winebrowser'', etc). This can be achieved by installing {{AUR|wine-installer}} or {{AUR|wine-installer-git}} meta-package (the latter has no additional dependencies), otherwise these instructions will add entries for these applications.<br />
<br />
First, install a Windows program using Wine to create the base menu. After the base menu is created, you can create the following files in {{ic|~/.local/share/applications/wine/}}:<br />
<br />
{{hc|wine-browsedrive.desktop|2=<br />
[Desktop Entry]<br />
Name=Browse C: Drive<br />
Comment=Browse your virtual C: drive<br />
Exec=wine winebrowser c:<br />
Terminal=false<br />
Type=Application<br />
Icon=folder-wine<br />
Categories=Wine;<br />
}}<br />
<br />
{{hc|wine-uninstaller.desktop|2=<br />
[Desktop Entry]<br />
Name=Uninstall Wine Software<br />
Comment=Uninstall Windows applications for Wine<br />
Exec=wine uninstaller<br />
Terminal=false<br />
Type=Application<br />
Icon=wine-uninstaller<br />
Categories=Wine;<br />
}}<br />
<br />
{{hc|wine-winecfg.desktop|2=<br />
[Desktop Entry]<br />
Name=Configure Wine<br />
Comment=Change application-specific and general Wine options<br />
Exec=winecfg<br />
Terminal=false<br />
Icon=wine-winecfg<br />
Type=Application<br />
Categories=Wine;<br />
}}<br />
<br />
And create the following file in {{ic|~/.config/menus/applications-merged/}}:<br />
<br />
{{hc|wine.menu|<nowiki><br />
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"<br />
"http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd"><br />
<Menu><br />
<Name>Applications</Name><br />
<Menu><br />
<Name>wine-wine</Name><br />
<Directory>wine-wine.directory</Directory><br />
<Include><br />
<Category>Wine</Category><br />
</Include><br />
</Menu><br />
</Menu><br />
</nowiki>}}<br />
<br />
If these settings produce a ugly/non-existent icon, it means that there are no icons for these launchers in the icon set that you have enabled. You should replace the icon settings with the explicit location of the icon that you want. Clicking the icon in the launcher's properties menu will have the same effect. A great icon set that supports these shortcuts is [https://www.gnome-look.org/content/show.php/GNOME-colors?content=82562 GNOME-colors].<br />
<br />
==== Removing menu entries ====<br />
<br />
Menu entries created by Wine are located in {{ic|~/.local/share/applications/wine/Programs/}}. Remove the program's ''.desktop'' entry to remove the application from the menu.<br />
<br />
In addition to remove unwanted extensions binding by Wine, execute the following commands (taken from the Wine website):<br />
<br />
$ rm ~/.local/share/mime/packages/x-wine*<br />
$ rm ~/.local/share/applications/wine-extension*<br />
$ rm ~/.local/share/icons/hicolor/*/*/application-x-wine-extension*<br />
$ rm ~/.local/share/mime/application/x-wine-extension*<br />
<br />
Sometimes you should also remove {{ic|wine-*.menu}} files from {{ic|/.config/menus/}} to completely remove items from wine submenu in kde.<br />
<br />
=== Appearance ===<br />
<br />
A similar to XP-looking theme can be [https://archive.org/download/zune-desktop-theme/ZuneDesktopTheme.msi downloaded]. To install it, see [https://wiki.winehq.org/Wine_User%27s_Guide#Running_.msi_files this upstream wiki article]. Lastly, use ''winecfg'' to select it.<br />
<br />
{{Note|The theme linked above can only be installed on 32-bit prefixes with Windows XP as the prefix version. To install it on 64-bit prefixes, you might want to create a temporary 32-bit prefix, install the theme and copy the {{ic|Zune}} folder and {{ic|Zune.theme}} files from {{ic|drive_c/Windows/Resources/Themes}} in that prefix to the same location in your usual prefix.}}<br />
<br />
Wine staging users may instead want to try enabling the option ''Enable GTK3 Theming'' under the Staging section of ''winecfg'' for a theme that matches the current GTK theme.<br />
<br />
=== Printing ===<br />
<br />
In order to use your installed printers (both local and network) with wine applications in ''win32 prefixes'' (e.g. MS Word), install the {{Pkg|lib32-libcups}} package, reboot wine (''wineboot'') and restart your wine application.<br />
<br />
=== Networking ===<br />
<br />
After installation, the {{pkg|lib32-gnutls}} package may need to be [[install]]ed for applications making TLS or HTTPS connections to work.<br />
<br />
For ICMP (ping), Wine may need the network access as described in the [https://wiki.winehq.org/FAQ#Failed_to_use_ICMP_.28network_ping.29.2C_this_requires_special_permissions WineHQ FAQ]:<br />
<br />
# setcap cap_net_raw+epi /usr/bin/wine-preloader<br />
<br />
If issues arise after this (such as an unhandled exception or privileged instruction), remove via:<br />
<br />
# setcap -r /usr/bin/wine-preloader<br />
<br />
== Usage ==<br />
<br />
{{Warning|Do not run or install Wine applications as root! See [https://wiki.winehq.org/FAQ#Should_I_run_Wine_as_root.3F Wine FAQ] for details.}}<br />
<br />
See [https://wiki.winehq.org/Wine_User%27s_Guide#Using_Wine Wine User's Guide] for general information on Wine usage.<br />
<br />
See [https://appdb.winehq.org/ Wine Application Database (AppDB)] for additional information on specific Windows applications in Wine.<br />
<br />
=== Wayland ===<br />
<br />
Currently Wine does not support Wayland directly, but you can use [[Wayland#XWayland|XWayland]] instead.<br />
<br />
There are some efforts to support Wayland though:<br />
<br />
* Experimental Wayland driver for Wine, which supports using OpenGL- and Windows GDI-applications. See [https://www.winehq.org/pipermail/wine-devel/2020-December/178575.html this] and [https://www.winehq.org/pipermail/wine-devel/2021-February/181325.html this] wine-devel maillist entries.<br />
* [https://github.com/varmd/wine-wayland wine-wayland]: a custom version of Wine, which supports Wayland via Vulkan (so it supports only: DirectX 9, 10 and 11 via [[#DXVK]] and Vulkan-compatible applications).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Wineconsole ===<br />
<br />
Often you may need to run ''.exe'''s to patch game files, for example a widescreen mod for an old game, and running the ''.exe'' normally through Wine might yield nothing happening. In this case, you can open a terminal and run the following command:<br />
<br />
$ wineconsole cmd<br />
<br />
Then navigate to the directory and run the ''.exe'' file from there.<br />
<br />
=== Winetricks ===<br />
<br />
[https://wiki.winehq.org/Winetricks Winetricks] is a script to allow one to install base requirements needed to run Windows programs. Installable components include DirectX 9.x, MSXML (required by Microsoft Office 2007 and Internet Explorer), Visual Runtime libraries and many more.<br />
<br />
[[Install]] the {{pkg|winetricks}} package (or alternatively {{AUR|winetricks-git}}). Then run it with:<br />
$ winetricks<br />
<br />
For using GUI you should [[install]] the {{pkg|zenity}}.<br />
<br />
=== Performance ===<br />
<br />
==== CSMT ====<br />
<br />
CSMT is a technology used by Wine to use a separate thread for the OpenGL calls to improve performance noticeably. Since Wine 3.2, CSMT is enabled by default. However, CSMT support needs to be enabled manually for Wine versions lower than 3.2. For vanilla Wine run {{ic|wine regedit}} and set the DWORD value for ''HKEY_CURRENT_USER -> Software > Wine > Direct3D > csmt'' to 0x01 (enabled). For wine-staging run {{ic|winecfg}} and enable it in the staging tab.<br />
<br />
Note that CSMT may actually hurt performance for some applications - if this is the case, disable it by creating/setting the registry value to 0x00 (disabled).<br />
<br />
Further information:<br />
*[https://www.phoronix.com/forums/showthread.php?93967-Wine-s-Big-Command-Stream-D3D-Patch-Set-Updated/page3&s=7775d7c3d4fa698089d5492bb7b1a435 Phoronix Forum discussion] with the CSMT developer Stefan Dösinger<br />
<br />
==== Force OpenGL mode in games ====<br />
<br />
Some games might have an OpenGL mode which ''may'' perform better than their default DirectX mode. While the steps to enable OpenGL rendering is ''application specific'', many games accept the {{Ic|-opengl}} parameter.<br />
<br />
$ wine ''/path/to/3d_game.exe'' -opengl<br />
<br />
You should of course refer to your application's documentation and Wine's [https://appdb.winehq.org AppDB] for such application specific information.<br />
<br />
==== DXVK ====<br />
<br />
[https://github.com/doitsujin/dxvk DXVK] is a promising new implementation for DirectX 9, 10 & 11 over Vulkan. This should allow for greater performance, and in some cases, even better compatibility. Battlefield 1 for example, only runs under DXVK. On the other hand, DXVK does not support all Wine games (yet).<br />
<br />
To use it, install {{aur|dxvk-bin}}. Then run the following command to activate it in your Wineprefix (by default {{ic|~/.wine}}):<br />
$ WINEPREFIX=''your-prefix'' setup_dxvk install<br />
<br />
{{Note|For Wine versions below 3.5 you need to configure Vulkan support manually, following the instructions at [https://github.com/roderickc/wine-vulkan GitHub].}}<br />
<br />
{{Warning|DXVK overrides the DirectX 10 and 11 DLLs, which may be considered cheating in online multiplayer games, and may get your account '''banned'''. Use at your own risk!}}<br />
<br />
==== Gallium Nine ====<br />
<br />
With the open-source gallium-based drivers (mostly AMD and Intel cards) there is a [https://wiki.ixit.cz/d3d9 Gallium Direct3D state tracker] that aims to provide nearly-native performance for DirectX 9. In most cases it has less visual glitches than the upstream wine and doubles the performances. It consumes much less CPU time than CSMT.<br />
<br />
Install {{Pkg|wine-nine}} to use it. This is a standalone package that can be installed with any Wine version. Use {{ic|wine ninewinecfg}} to check if it is enabled.<br />
<br />
For older Intel graphics (gen4-7: GMA 3000, GMA 4500, HD 2000-5000; year 2006-2014) Crocus Gallium driver should be used instead of i965 since Mesa 21.2. [[Export]] the following environment variable before running Wine: <br />
<br />
MESA_LOADER_DRIVER_OVERRIDE=crocus<br />
<br />
=== Unregister existing Wine file associations ===<br />
<br />
By default, Wine takes over as the default application for a lot of formats. Some (e.g. {{ic|vbs}} or {{ic|chm}}) are Windows-specific, and opening them with Wine can be a convenience. However, having other formats (e.g. {{ic|gif}}, {{ic|jpeg}}, {{ic|txt}}, {{ic|js}}) open in Wine's bare-bones simulations of Internet Explorer and Notepad can be annoying.<br />
<br />
Wine's file associations are set in {{ic|~/.local/share/applications/}} as {{ic|wine-extension-''extension''.desktop}} files. Delete the files corresponding to the extensions you want to unregister. Or, to remove all wine extensions:<br />
<br />
$ rm -f ~/.local/share/applications/wine-extension*.desktop<br />
$ rm -f ~/.local/share/icons/hicolor/*/*/application-x-wine-extension*<br />
<br />
Next, remove the old cache:<br />
<br />
$ rm -f ~/.local/share/applications/mimeinfo.cache<br />
$ rm -f ~/.local/share/mime/packages/x-wine*<br />
$ rm -f ~/.local/share/mime/application/x-wine-extension*<br />
<br />
And, update the cache:<br />
<br />
$ update-desktop-database ~/.local/share/applications<br />
$ update-mime-database ~/.local/share/mime/<br />
<br />
Please note Wine will still create new file associations and even recreate the file associations if the application sets the file associations again.<br />
<br />
=== Prevent Wine from creating filetype associations ===<br />
<br />
{{Note|This has to be done for each WINEPREFIX which should not update file associations unless you opt to change {{ic|/usr/share/wine/wine.inf}} .}}<br />
This method prevents the creation of filetype associations but retains the creation of XDG .desktop files (that you might see e.g. in menus).<br />
<br />
If you want to stop wine from creating filetype associations via winecfg you have to uncheck the "Manage File Associations" checkbox under the Desktop Integration tab. See [https://wiki.winehq.org/FAQ#How_can_I_prevent_Wine_from_changing_the_filetype_associations_on_my_system_or_adding_unwanted_menu_entries.2Fdesktop_links.3F Wine FAQ]<br />
<br />
To make the same change via registry add the string {{ic|Enable}} with value {{ic|N}} under:<br />
<br />
HKEY_CURRENT_USER\Software\Wine\FileOpenAssociations<br />
<br />
''You might have to create the key {{ic|FileOpenAssociations}} first!''<br />
<br />
If you want to apply this by default for new WINEPREFIXES, edit {{ic|/usr/share/wine/wine.inf}} and add this line for example under the {{ic|[Services]}} section:<br />
HKCU,"Software\Wine\FileOpenAssociations","Enable",2,"N"<br />
<br />
To prevent a package upgrade from overriding the modified file, create a pacman hook to make the change automatically:<br />
<br />
{{hc|1=/etc/pacman.d/hooks/stop-wine-associations.hook|2=<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Upgrade<br />
Type = Path<br />
Target = usr/share/wine/wine.inf<br />
<br />
[Action]<br />
Description = Stopping Wine from hijacking file associations...<br />
When = PostTransaction<br />
<nowiki>Exec = /bin/sh -c '/usr/bin/grep -q "HKCU,\"Software\\\Wine\\\FileOpenAssociations\",\"Enable\",2,\"N\"" /usr/share/wine/wine.inf || /usr/bin/sed -i "s/\[Services\]/\[Services\]\nHKCU,\"Software\\\Wine\\\FileOpenAssociations\",\"Enable\",2,\"N\"/g" /usr/share/wine/wine.inf'</nowiki><br />
}}<br />
<br />
See [[Pacman#Hooks]]<br />
<br />
=== Execute Windows binaries with Wine implicitly ===<br />
<br />
The {{pkg|wine}} package installs a ''binfmt'' file which will allows you to run Windows programs directly, e.g. {{ic|''./myprogram.exe''}} will launch as if you had typed {{ic|wine ''./myprogram.exe''}}. Service starts by default on boot, if you have not rebooted after installing Wine you can [[start]] {{ic|systemd-binfmt.service}} to use it right away.<br />
<br />
{{Note|Make sure the Windows binary is [[executable]], otherwise the binary will not run.}}<br />
<br />
=== Dual Head with different resolutions ===<br />
<br />
If you have issues with dual-head setups and different display resolutions you are probably missing {{Pkg|lib32-libxrandr}}.<br />
<br />
Also installing {{Pkg|lib32-libxinerama}} might fix dual-head issues with wine (for example, unclickable buttons and menus of application in the right most or bottom most monitor, not redrawable interface of application in that zone, dragging mouse cursor state stucked after leaving application area).<br />
<br />
=== Burning optical media ===<br />
<br />
To burn CDs or DVDs, you will need to load the {{ic|sg}} [[kernel module]].<br />
<br />
=== Proper mounting of optical media images ===<br />
<br />
Some applications will check for the optical media to be in drive. They may check for data only, in which case it might be enough to configure the corresponding path as being a CD-ROM drive in ''winecfg''.<br />
However, other applications will look for a media name and/or a serial number, in which case the image has to be mounted with these special properties.<br />
<br />
Some virtual drive tools do not handle these metadata, like fuse-based virtual drives (Acetoneiso for instance). [[CDemu]] will handle it correctly.<br />
<br />
=== Show FPS overlay in games ===<br />
<br />
Wine features an embedded FPS monitor which works for all graphical applications if the environment variable {{ic|1=WINEDEBUG=fps}} is set. This will output the framerate to stdout. You can display the FPS on top of the window thanks to {{ic|osd_cat}} from the {{pkg|xosd}} package. See [https://gist.github.com/anonymous/844aefd70bb50bf72b35 winefps.sh] for a helper script.<br />
<br />
=== Running Wine under a separate user account ===<br />
<br />
It may be desirable to run Wine under a specifically created user account in order to reduce concerns about Windows applications having access to your home directory.<br />
<br />
First, create a [[user account]] for Wine:<br />
<br />
# useradd -m -s /bin/bash wineuser<br />
<br />
Now switch to another TTY and start your X WM or DE as you normally would or keep reading...<br />
<br />
{{Note|The following approach only works when enabling root for Xorg. See [[Xorg#Rootless Xorg]] for more information on how to execute the {{ic|xhost}} command under your main user.}}<br />
<br />
Afterwards, in order to open Wine applications using this new user account you need to add the new user to the X server permissions list:<br />
<br />
$ xhost +SI:localuser:wineuser<br />
<br />
Finally, you can run Wine via the following command, which uses {{ic|env}} to launch Wine with the environment variables it expects:<br />
<br />
$ sudo -u wineuser env HOME=/home/wineuser USER=wineuser USERNAME=wineuser LOGNAME=wineuser wine ''arguments''<br />
<br />
It is possible to automate the process of running Windows applications with Wine via this method by using a shell script as follows:<br />
{{hc|1=/usr/local/bin/runaswine|2=<br />
#!/bin/bash<br />
xhost +SI:localuser:wineuser<br />
sudo -u wineuser env HOME=/home/wineuser USER=wineuser USERNAME=wineuser LOGNAME=wineuser wine "$@"}}<br />
<br />
Wine applications can then be launched via:<br />
<br />
$ runaswine ''"C:\path\to\application.exe"''<br />
<br />
In order to not be asked for a password each time Wine is run as another user the following entry can be added to the sudoers file: {{ic|1=''mainuser'' ALL=(wineuser) NOPASSWD: ALL}}. See [[Sudo#Configuration]] for more information.<br />
<br />
It is recommended to run {{ic|winecfg}} as the Wine user and remove all bindings for directories outside the home directory of the Wine user in the "Desktop Integration" section of the configuration window so no program run with Wine has read access to any file outside the special user's home directory.<br />
<br />
Keep in mind that audio will probably be non-functional in Wine programs which are run this way if [[PulseAudio]] is used. See [[PulseAudio/Examples#Allowing multiple users to share a PulseAudio daemon]] for information about allowing the Wine user to access the PulseAudio daemon of the principal user.<br />
<br />
=== Temp directory on tmpfs ===<br />
<br />
To prevent Wine from writing its temporary files to a physical disk, one can define an alternative location, like ''tmpfs''. Remove Wine's default directory for temporary files and creating a symlink:<br />
<br />
$ rm -r ~/.wine/drive_c/users/$USER/Temp<br />
$ ln -s /tmp/ ~/.wine/drive_c/users/$USER/Temp<br />
<br />
=== Prevent installing Mono/Gecko ===<br />
<br />
If Gecko and/or Mono are not present on the system nor in the Wine prefix, Wine will prompt to download them from the internet. If you do not need Gecko and/or Mono, you might want to disable this dialog, by setting the {{ic|WINEDLLOVERRIDES}} [[environment variable]] to {{ic|1=mscoree=d;mshtml=d}}.<br />
<br />
=== Vulkan ===<br />
<br />
Vulkan support is included, since Wine 3.3. The default Wine Vulkan ICD loader works fine for most applications, but does not support advanced features, like Vulkan layers. To use these features, you have to install the official Vulkan SDK, see step 2-4 on the original Vulkan patches author's [https://github.com/roderickc/wine-vulkan GitHub page].<br />
<br />
{{Note|The Wine ICD loader was added in Wine 3.5, you need to install the official Vulkan SDK to use Vulkan in Wine 3.3 and 3.4}}<br />
<br />
=== Remove Wine file bindings ===<br />
<br />
For security reasons it may be useful to remove the preinstalled Wine bindings so Windows applications cannot be launched directly from a file manager or from the browser (Firefox offers to open EXE files directly with Wine!).<br />
If you want to do this, you may add the following to the {{ic|1= [options]}} section in {{ic|1= /etc/pacman.conf}}<br />
<br />
NoExtract = usr/lib/binfmt.d/wine.conf<br />
NoExtract = usr/share/applications/wine.desktop<br />
<br />
== Troubleshooting ==<br />
<br />
See [https://wiki.winehq.org/Wine_User%27s_Guide#Troubleshooting_.2F_Reporting_bugs Wine User's Guide] and [https://wiki.winehq.org/FAQ Wine FAQ] (especially its [https://wiki.winehq.org/FAQ#Troubleshooting Troubleshooting] section) for general tips.<br />
<br />
Also refer to the [https://appdb.winehq.org/ Wine AppDB] for an advice on specific applications.<br />
<br />
=== XWayland problems ===<br />
<br />
If you use Wine under [[Wayland#XWayland|XWayland]], you can activate the option for "Emulating a virtual desktop" in the Graphics Tab in winecfg, to avoid problems with:<br />
<br />
* flickering;<br />
* wrong window location;<br />
* wrong mouse cursor location and clicks;<br />
* keyboard detection.<br />
<br />
=== Keyboard input not working ===<br />
<br />
Try toggling the settings in ''winecfg'' for ''Window settings'', click ''Apply'' and then change them back. If that does not work, try changing individual settings.<br />
<br />
If the keyboard does not work after unfocusing the application, try editing the registry:<br />
Under ''HKEY_CURRENT_USER\Software\Wine\X11 Driver'', add a string value ''UseTakeFocus'' and set it to ''N''.<br />
<br />
Alternatively, you can use winetricks to set the value.<br />
winetricks usetakefocus=n<br />
<br />
== See also ==<br />
<br />
* [https://www.winehq.org/ Wine Homepage]<br />
* [https://wiki.winehq.org/ Wine Wiki]<br />
* [https://appdb.winehq.org/ Wine Application Database (AppDB)] - Information about running specific Windows applications (Known issues, ratings, guides, etc tailored to specific applications)<br />
* [https://forum.winehq.org/ Wine Forums] - A great place to ask questions ''after'' you have looked through the FAQ and AppDB<br />
* [[Gentoo:Wine]]<br />
* [https://www.darlinghq.org/ Darling] - a similar project for MacOS software</div>Jwh7https://wiki.archlinux.org/index.php?title=NVIDIA&diff=715180NVIDIA2022-02-02T17:00:01Z<p>Jwh7: /* Custom kernel */ Add kernel config requirements for nvidia-dkms</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X server]]<br />
[[de:Nvidia]]<br />
[[fa:اِنویدیا]]<br />
[[fr:NVIDIA]]<br />
[[it:NVIDIA]]<br />
[[ja:NVIDIA]]<br />
[[ru:NVIDIA]]<br />
[[zh-hans:NVIDIA]]<br />
{{Related articles start}}<br />
{{Related|NVIDIA/Tips and tricks}}<br />
{{Related|NVIDIA/Troubleshooting}}<br />
{{Related|Nouveau}}<br />
{{Related|NVIDIA Optimus}}<br />
{{Related|PRIME}}<br />
{{Related|Bumblebee}}<br />
{{Related|nvidia-xrun}}<br />
{{Related|Xorg}}<br />
{{Related|Vulkan}}<br />
{{Related articles end}}<br />
<br />
This article covers the proprietary [https://www.nvidia.com NVIDIA] graphics card driver. For the open-source driver, see [[Nouveau]]. If you have a laptop with hybrid Intel/NVIDIA graphics, see [[NVIDIA Optimus]] instead.<br />
<br />
== Installation ==<br />
<br />
{{Warning|Avoid installing the NVIDIA driver through the package provided from the NVIDIA website. Installation through [[pacman]] allows upgrading the driver together with the rest of the system.}}<br />
<br />
These instructions are for those using the stock {{Pkg|linux}} or {{Pkg|linux-lts}} packages. For custom kernel setup, skip to the [[#Custom kernel|next]] subsection.<br />
<br />
1. If you do not know what graphics card you have, find out by issuing:<br />
:{{bc|$ lspci -k {{!}} grep -A 2 -E "(VGA{{!}}3D)"}}<br />
<br />
2. Determine the necessary driver version for your card by:<br />
:* Finding the code name (e.g. NV50, NVC0, etc.) on [https://nouveau.freedesktop.org/wiki/CodeNames/ Nouveau wiki's code names page] or [https://gitlab.freedesktop.org/nouveau/wiki/-/blob/master/sources/CodeNames.mdwn].<br />
:* Looking up the name in NVIDIA's [https://www.nvidia.com/object/IO_32667.html legacy card list]: if your card is not there you can use the latest driver.<br />
:* Visiting NVIDIA's [https://www.nvidia.com/Download/index.aspx driver download site].<br />
<br />
3. Install the appropriate driver for your card:<br />
:* For the Maxwell (NV110) series and newer, including: GeForce 930~, 10-20, Quadro/Tesla/Tegra cards and newer (for a detailed list, see [https://download.nvidia.com/XFree86/Linux-x86_64/495.44/README/supportedchips.html Official Readme]), [[install]] the {{Pkg|nvidia}} package (for use with the {{Pkg|linux}} kernel) or {{Pkg|nvidia-lts}} (for use with the {{Pkg|linux-lts}} kernel) package.<br />
::* If these packages do not work, {{AUR|nvidia-beta}} may have a newer driver version that offers support.<br />
:* For the Kepler (NVE0) series (including GeForce 630-920) from around 2013-2014, [[install]] the {{AUR|nvidia-470xx-dkms}} package.<br />
:* For GeForce 400/500/600 series cards [NVCx and NVDx] from around 2010-2011, [[install]] the {{AUR|nvidia-390xx-dkms}} package.<br />
:* For even older cards (released in 2010 or earlier), have a look at [[#Unsupported drivers]].<br />
<br />
4. For 32-bit application support, also install the corresponding ''lib32'' nvidia package from the [[multilib]] repository (e.g. {{Pkg|lib32-nvidia-utils}}).<br />
<br />
5. Reboot. The {{Pkg|nvidia}} package contains a file which blacklists the {{ic|nouveau}} module, so rebooting is necessary.<br />
<br />
Once the driver has been installed, continue to [[#Xorg configuration]] or [[#Wayland]].<br />
<br />
=== Unsupported drivers ===<br />
<br />
If you have a GeForce 300 series card or older (released in 2010 or earlier), Nvidia no longer supports drivers for your card. This means that these drivers [https://nvidia.custhelp.com/app/answers/detail/a_id/3142/ do not support the current Xorg version]. It thus might be easier if you use the [[Nouveau]] driver, which supports the old cards with the current Xorg.<br />
<br />
However, Nvidia's legacy drivers are still available and might provide better 3D performance/stability.<br />
<br />
* For GeForce 8/9, ION and 100-300 series cards [NV5x, NV8x, NV9x and NVAx], [[install]] the {{AUR|nvidia-340xx-dkms}} package.<br />
* GeForce 7 series cards and older [NV6x, NV4x and lower] do not have a driver packaged for Arch Linux.<br />
<br />
=== Custom kernel ===<br />
<br />
If using a custom kernel, compilation of the Nvidia kernel modules can be automated with [[DKMS]]. Install the {{Pkg|nvidia-dkms}} package (or a specific branch).<br />
<br />
Ensure your kernel config has ''CONFIG_DRM_SIMPLEDRM=y'', and if using ''CONFIG_DEBUG_INFO_BTF'' then this is needed in the PKGBUILD (since kernel 5.16):<br />
install -Dt "$builddir/tools/bpf/resolve_btfids" tools/bpf/resolve_btfids/resolve_btfids<br />
<br />
The Nvidia module will be rebuilt after every Nvidia or kernel update thanks to the DKMS [[pacman hook]].<br />
<br />
=== DRM kernel mode setting ===<br />
<br />
To enable DRM ([[Wikipedia:Direct Rendering Manager|Direct Rendering Manager]]) [[kernel mode setting]], add the {{ic|1=nvidia-drm.modeset=1}} [[kernel parameter]].<br />
<br />
{{Note|1=<nowiki/><br />
* The NVIDIA driver does '''not''' provide an {{ic|fbdev}} driver for the high-resolution console for the kernel compiled-in {{ic|vesafb}} module. However, the kernel compiled-in {{ic|efifb}} module supports a high-resolution console on EFI systems. This method requires GRUB or rEFInd and is described in [[NVIDIA/Tips and tricks#Fixing terminal resolution]].[https://forums.fedoraforum.org/showthread.php?t=306271][https://www.reddit.com/r/archlinux/comments/4gwukx/nvidia_drivers_and_high_resolution_tty_possible/][https://www.reddit.com/r/archlinux/comments/86lqc5/tty_resolution_nvidia_psaish/].<br />
* Nvidia drivers prior to version 470 (e.g. {{AUR|nvidia-390xx-dkms}}) do not support hardware accelerated XWayland, causing non-Wayland-native applications to suffer from poor performance in Wayland sessions.<br />
}}<br />
<br />
==== Early loading ====<br />
<br />
For basic functionality, just adding the kernel parameter should suffice. If you want to ensure it is loaded at the earliest possible occasion, or are noticing startup issues (such as the {{ic|nvidia}} kernel module being loaded after the [[display manager]]) you can add {{ic|nvidia}}, {{ic|nvidia_modeset}}, {{ic|nvidia_uvm}} and {{ic|nvidia_drm}} to the initramfs.<br />
<br />
===== mkinitcpio =====<br />
<br />
If you use [[mkinitcpio]] initramfs, follow [[mkinitcpio#MODULES]] to add modules.<br />
<br />
If added to the initramfs, do not forget to run [[mkinitcpio]] every time there is a {{Pkg|nvidia}} driver update. See [[#pacman hook]] to automate these steps.<br />
<br />
===== Booster =====<br />
<br />
If you use [[Booster]], follow [[Booster#Early module loading]].<br />
<br />
===== pacman hook =====<br />
<br />
To avoid the possibility of forgetting to update [[initramfs]] after an NVIDIA driver upgrade, you may want to use a [[pacman hook]]:<br />
<br />
{{hc|/etc/pacman.d/hooks/nvidia.hook|2=<br />
[Trigger]<br />
Operation=Install<br />
Operation=Upgrade<br />
Operation=Remove<br />
Type=Package<br />
Target=nvidia<br />
Target=linux<br />
# Change the linux part above and in the Exec line if a different kernel is used<br />
<br />
[Action]<br />
Description=Update Nvidia module in initcpio<br />
Depends=mkinitcpio<br />
When=PostTransaction<br />
NeedsTargets<br />
Exec=/bin/sh -c 'while read -r trg; do case $trg in linux) exit 0; esac; done; /usr/bin/mkinitcpio -P'<br />
}}<br />
<br />
Make sure the {{ic|Target}} package set in this hook is the one you have installed in steps above (e.g. {{ic|nvidia}}, {{ic|nvidia-dkms}}, {{ic|nvidia-lts}} or {{ic|nvidia-ck-''something''}}).<br />
<br />
{{Note|The complication in the {{ic|Exec}} line above is in order to avoid running ''mkinitcpio'' multiple times if both {{ic|nvidia}} and {{ic|linux}} get updated. In case this does not bother you, the {{ic|1=Target=linux}} and {{ic|NeedsTargets}} lines may be dropped, and the {{ic|Exec}} line may be reduced to simply {{ic|1=Exec=/usr/bin/mkinitcpio -P}}.}}<br />
<br />
=== Hardware accelerated video decoding ===<br />
<br />
Accelerated video decoding with VDPAU is supported on GeForce 8 series cards and newer. Accelerated video decoding with NVDEC is supported on Fermi (~400 series) cards and newer. See [[Hardware video acceleration]] for details.<br />
<br />
=== Hardware accelerated video encoding with NVENC ===<br />
<br />
NVENC requires the {{ic|nvidia_uvm}} module and the creation of related device nodes under {{ic|/dev}}. Manually loading the {{ic|nvidia_uvm}} module will not create the device nodes, but invoking the {{ic|nvidia-modprobe}} utility will. Create {{ic|/etc/udev/rules.d/70-nvidia.rules}}:<br />
<br />
{{hc|/etc/udev/rules.d/70-nvidia.rules|2=<br />
ACTION=="add", DEVPATH=="/bus/pci/drivers/nvidia", RUN+="/usr/bin/nvidia-modprobe -c0 -u"<br />
}}<br />
<br />
== Xorg configuration ==<br />
<br />
The proprietary NVIDIA graphics card driver does not need any Xorg server configuration file. You can [[Xorg#Running|start X]] to see if the Xorg server will function correctly without a configuration file. However, it may be required to create a configuration file (prefer {{ic|/etc/X11/xorg.conf.d/20-nvidia.conf}} over {{ic|/etc/X11/xorg.conf}}) in order to adjust various settings. This configuration can be generated by the NVIDIA Xorg configuration tool, or it can be created manually. If created manually, it can be a minimal configuration (in the sense that it will only pass the basic options to the [[Xorg]] server), or it can include a number of settings that can bypass Xorg's auto-discovered or pre-configured options.<br />
<br />
{{Tip|For more configuration options, see [[NVIDIA/Troubleshooting]].}}<br />
<br />
=== Automatic configuration ===<br />
<br />
The NVIDIA package includes an automatic configuration tool to create an Xorg server configuration file ({{ic|xorg.conf}}) and can be run by:<br />
<br />
# nvidia-xconfig<br />
<br />
This command will auto-detect and create (or edit, if already present) the {{ic|/etc/X11/xorg.conf}} configuration according to present hardware.<br />
<br />
If there are instances of DRI, ensure they are commented out:<br />
<br />
# Load "dri"<br />
<br />
Double check your {{ic|/etc/X11/xorg.conf}} to make sure your default depth, horizontal sync, vertical refresh, and resolutions are acceptable.<br />
<br />
=== nvidia-settings ===<br />
<br />
The {{Pkg|nvidia-settings}} tool lets you configure many options using either CLI or GUI. Running {{ic|nvidia-settings}} without any options launches the GUI, for CLI options see {{man|1|nvidia-settings}}.<br />
<br />
You can run the CLI/GUI as a non-root user and save the settings to {{ic|~/.nvidia-settings-rc}} or save it as [[Xorg#Using_xorg.conf|xorg.conf]] by using the option ''Save to X configuration File'' for a multi-user environment.<br />
<br />
To load the {{ic|~/.nvidia-settings-rc}} for the current user:<br />
<br />
$ nvidia-settings --load-config-only<br />
<br />
See [[Autostarting]] to start this command on every boot.<br />
<br />
{{Note|[[Xorg]] may not start or crash on startup after saving {{ic|nvidia-settings}} changes. Adjusting or deleting the generated {{ic|~/.nvidia-settings-rc}} and/or [[Xorg]] file(s) should recover normal startup.}}<br />
<br />
{{Note|[[Cinnamon]] desktop can override changes made through {{ic|nvidia-settings}}. You can [[Cinnamon#Cinnamon_overrides_settings_in_xorg.conf|adjust the Cinnamon startup behavior to prevent that]].}}<br />
<br />
=== Manual configuration ===<br />
<br />
Several tweaks (which cannot be enabled [[#Automatic configuration|automatically]] or with [[#nvidia-settings|nvidia-settings]]) can be performed by editing your configuration file. The Xorg server will need to be restarted before any changes are applied.<br />
<br />
See [https://download.nvidia.com/XFree86/Linux-x86_64/470.63.01/README/ NVIDIA Accelerated Linux Graphics Driver README and Installation Guide] for additional details and options.<br />
<br />
==== Minimal configuration ====<br />
<br />
A basic configuration block in {{ic|20-nvidia.conf}} (or deprecated in {{ic|xorg.conf}}) would look like this:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-nvidia.conf|<br />
Section "Device"<br />
Identifier "Nvidia Card"<br />
Driver "nvidia"<br />
VendorName "NVIDIA Corporation"<br />
BoardName "GeForce GTX 1050 Ti"<br />
EndSection<br />
}}<br />
<br />
==== Disabling the logo on startup ====<br />
<br />
Add the {{ic|"NoLogo"}} option under section {{ic|Device}}:<br />
<br />
Option "NoLogo" "1"<br />
<br />
==== Overriding monitor detection ====<br />
<br />
The {{ic|"ConnectedMonitor"}} option under section {{ic|Device}} allows to override monitor detection when X server starts, which may save a significant amount of time at start up. The available options are: {{ic|"CRT"}} for analog connections, {{ic|"DFP"}} for digital monitors and {{ic|"TV"}} for televisions.<br />
<br />
The following statement forces the NVIDIA driver to bypass startup checks and recognize the monitor as DFP:<br />
<br />
Option "ConnectedMonitor" "DFP"<br />
<br />
{{Note|Use "CRT" for all analog 15 pin VGA connections, even if the display is a flat panel. "DFP" is intended for DVI, HDMI, or DisplayPort digital connections only.}}<br />
<br />
==== Enabling brightness control ====<br />
<br />
{{Out of date|Potentially obsolete[https://lists.archlinux.org/pipermail/aur-requests/2021-April/051047.html], upstream package also seems to be ancient.}}<br />
<br />
Add to kernel paremeters:<br />
<br />
nvidia.NVreg_RegistryDwords=EnableBrightnessControl=1<br />
<br />
Alternatively, add the following under section {{ic|Device}}:<br />
<br />
Option "RegistryDwords" "EnableBrightnessControl=1"<br />
<br />
If brightness control still does not work with this option, try installing {{AUR|nvidia-bl-dkms}}.<br />
<br />
{{Note|Installing {{AUR|nvidia-bl-dkms}} will provide a {{ic|/sys/class/backlight/nvidia_backlight/}} interface to backlight brightness control, but your system may continue to issue backlight control changes on {{ic|/sys/class/backlight/acpi_video0/}}. One solution in this case is to watch for changes on, e.g. {{ic|acpi_video0/brightness}} with ''inotifywait'' and to translate and write to {{ic|nvidia_backlight/brightness}} accordingly. See [[Backlight#sysfs modified but no brightness change]].}}<br />
<br />
==== Enabling SLI ====<br />
<br />
{{Warning|Since the GTX 10xx Series (1080, 1070, 1060, etc) only 2-way SLI is supported. 3-way and 4-way SLI may work for CUDA/OpenCL applications, but will most likely break all OpenGL applications.}}<br />
<br />
Taken from the NVIDIA driver's [ftp://download.nvidia.com/XFree86/Linux-x86/355.11/README/xconfigoptions.html README] Appendix B: ''This option controls the configuration of SLI rendering in supported configurations.'' A "supported configuration" is a computer equipped with an SLI-Certified Motherboard and 2 or 3 SLI-Certified GeForce GPUs.<br />
<br />
Find the first GPU's PCI Bus ID using {{ic|lspci}}:<br />
<br />
{{hc|# lspci {{!}} grep "VGA{{!}}3D controller"|<br />
00:02.0 VGA compatible controller: Intel Corporation Xeon E3-1200 v2/3rd Gen Core processor Graphics Controller (rev 09)<br />
03:00.0 VGA compatible controller: NVIDIA Corporation GK107 [GeForce GTX 650] (rev a1)<br />
04:00.0 VGA compatible controller: NVIDIA Corporation GK107 [GeForce GTX 650] (rev a1)<br />
08:00.0 3D controller: NVIDIA Corporation GM108GLM [Quadro K620M / Quadro M500M] (rev a2)<br />
}}<br />
<br />
Add the BusID (3 in the previous example) under section {{ic|Device}}:<br />
<br />
BusID "PCI:3:0:0"<br />
<br />
{{Note|The format is important. The BusID value must be specified as {{ic|"PCI:<BusID>:0:0"}}}}<br />
<br />
Add the desired SLI rendering mode value under section {{ic|Screen}}:<br />
<br />
Option "SLI" "AA"<br />
<br />
The following table presents the available rendering modes.<br />
<br />
{| class="wikitable"<br />
! Value !! Behavior<br />
|-<br />
| 0, no, off, false, Single || Use only a single GPU when rendering.<br />
|-<br />
| 1, yes, on, true, Auto || Enable SLI and allow the driver to automatically select the appropriate rendering mode.<br />
|-<br />
| AFR || Enable SLI and use the alternate frame rendering mode.<br />
|-<br />
| SFR || Enable SLI and use the split frame rendering mode.<br />
|-<br />
| AA || Enable SLI and use SLI antialiasing. Use this in conjunction with full scene antialiasing to improve visual quality.<br />
|}<br />
<br />
Alternatively, you can use the ''nvidia-xconfig'' utility to insert these changes into {{ic|xorg.conf}} with a single command:<br />
<br />
# nvidia-xconfig --busid=PCI:3:0:0 --sli=AA<br />
<br />
To verify that SLI mode is enabled from a shell:<br />
<br />
{{hc|$ nvidia-settings -q all {{!}} grep SLIMode|<br />
Attribute 'SLIMode' (arch:0.0): AA <br />
'SLIMode' is a string attribute.<br />
'SLIMode' is a read-only attribute.<br />
'SLIMode' can use the following target types: X Screen.<br />
}}<br />
<br />
{{Warning|After enabling SLI, your system may become frozen/non-responsive upon starting xorg. It is advisable that you disable your display manager before restarting.}}<br />
<br />
If this configuration does not work, you may need to use the PCI Bus ID provided by {{ic|nvidia-settings}},<br />
<br />
{{hc|$ nvidia-settings -q all {{!}} grep -i pcibus|<br />
Attribute 'PCIBus' (host:0[gpu:0]): 101.<br />
'PCIBus' is an integer attribute.<br />
'PCIBus' is a read-only attribute.<br />
'PCIBus' can use the following target types: GPU, SDI Input Device.<br />
Attribute 'PCIBus' (host:0[gpu:1]): 23.<br />
'PCIBus' is an integer attribute.<br />
'PCIBus' is a read-only attribute.<br />
'PCIBus' can use the following target types: GPU, SDI Input Device.<br />
}}<br />
<br />
and comment out the PrimaryGPU option in your xorg.d configuration,<br />
<br />
{{hc|/usr/share/X11/xorg.conf.d/10-nvidia-drm-outputclass.conf|<br />
...<br />
<br />
Section "OutputClass"<br />
...<br />
# Option "PrimaryGPU" "yes"<br />
...<br />
}}<br />
<br />
Using this configuration may also solve any graphical boot issues.<br />
<br />
=== Multiple monitors ===<br />
<br />
See [[Multihead]] for more general information.<br />
<br />
==== Using nvidia-settings ====<br />
<br />
The [[#nvidia-settings|nvidia-settings]] tool can configure multiple monitors.<br />
<br />
For CLI configuration, first get the {{ic|CurrentMetaMode}} by running:<br />
<br />
{{hc|$ nvidia-settings -q CurrentMetaMode|2=<br />
Attribute 'CurrentMetaMode' (hostnmae:0.0): id=50, switchable=no, source=nv-control :: DPY-1: 2880x1620 @2880x1620 +0+0 {ViewPortIn=2880x1620, ViewPortOut=2880x1620+0+0}<br />
}}<br />
<br />
Save everything after the {{ic|::}} to the end of the attribute (in this case: {{ic|1=DPY-1: 2880x1620 @2880x1620 +0+0 {ViewPortIn=2880x1620, ViewPortOut=2880x1620+0+0}<nowiki/>}}) and use to reconfigure your displays with {{ic|1=nvidia-settings --assign "CurrentMetaMode=''your_meta_mode''"}}.<br />
<br />
{{Tip|You can create shell aliases for the different monitor and resolution configurations you use.}}<br />
<br />
==== ConnectedMonitor ====<br />
<br />
If the driver does not properly detect a second monitor, you can force it to do so with ConnectedMonitor. <br />
<br />
{{hc|/etc/X11/xorg.conf|<br />
<br />
Section "Monitor"<br />
Identifier "Monitor1"<br />
VendorName "Panasonic"<br />
ModelName "Panasonic MICRON 2100Ex"<br />
HorizSync 30.0 - 121.0 # this monitor has incorrect EDID, hence Option "UseEDIDFreqs" "false"<br />
VertRefresh 50.0 - 160.0<br />
Option "DPMS"<br />
EndSection<br />
<br />
Section "Monitor"<br />
Identifier "Monitor2"<br />
VendorName "Gateway"<br />
ModelName "GatewayVX1120"<br />
HorizSync 30.0 - 121.0<br />
VertRefresh 50.0 - 160.0<br />
Option "DPMS"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Device1"<br />
Driver "nvidia"<br />
Option "NoLogo"<br />
Option "UseEDIDFreqs" "false"<br />
Option "ConnectedMonitor" "CRT,CRT"<br />
VendorName "NVIDIA Corporation"<br />
BoardName "GeForce 6200 LE"<br />
BusID "PCI:3:0:0"<br />
Screen 0<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Device2"<br />
Driver "nvidia"<br />
Option "NoLogo"<br />
Option "UseEDIDFreqs" "false"<br />
Option "ConnectedMonitor" "CRT,CRT"<br />
VendorName "NVIDIA Corporation"<br />
BoardName "GeForce 6200 LE"<br />
BusID "PCI:3:0:0"<br />
Screen 1<br />
EndSection<br />
<br />
}}<br />
<br />
The duplicated device with {{ic|Screen}} is how you get X to use two monitors on one card without {{ic|TwinView}}. Note that {{ic|nvidia-settings}} will strip out any {{ic|ConnectedMonitor}} options you have added.<br />
<br />
==== TwinView ====<br />
<br />
You want only one big screen instead of two. Set the {{ic|TwinView}} argument to {{ic|1}}. This option should be used if you desire compositing. TwinView only works on a per card basis, when all participating monitors are connected to the same card.<br />
<br />
Option "TwinView" "1"<br />
<br />
Example configuration:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/10-monitor.conf|<br />
Section "ServerLayout"<br />
Identifier "TwinLayout"<br />
Screen 0 "metaScreen" 0 0<br />
EndSection<br />
<br />
Section "Monitor"<br />
Identifier "Monitor0"<br />
Option "Enable" "true"<br />
EndSection<br />
<br />
Section "Monitor"<br />
Identifier "Monitor1"<br />
Option "Enable" "true"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Card0"<br />
Driver "nvidia"<br />
VendorName "NVIDIA Corporation"<br />
<br />
#refer to the link below for more information on each of the following options.<br />
Option "HorizSync" "DFP-0: 28-33; DFP-1: 28-33"<br />
Option "VertRefresh" "DFP-0: 43-73; DFP-1: 43-73"<br />
Option "MetaModes" "1920x1080, 1920x1080"<br />
Option "ConnectedMonitor" "DFP-0, DFP-1"<br />
Option "MetaModeOrientation" "DFP-1 LeftOf DFP-0"<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "metaScreen"<br />
Device "Card0"<br />
Monitor "Monitor0"<br />
DefaultDepth 24<br />
Option "TwinView" "True"<br />
SubSection "Display"<br />
Modes "1920x1080"<br />
EndSubSection<br />
EndSection<br />
}}<br />
<br />
[https://download.nvidia.com/XFree86/Linux-x86_64/440.31/README/configtwinview.html Device option information].<br />
<br />
If you have multiple cards that are SLI capable, it is possible to run more than one monitor attached to separate cards (for example: two cards in SLI with one monitor attached to each). The "MetaModes" option in conjunction with SLI Mosaic mode enables this. Below is a configuration which works for the aforementioned example and runs [[GNOME]] flawlessly.<br />
<br />
{{hc|/etc/X11/xorg.conf.d/10-monitor.conf|<br />
Section "Device"<br />
Identifier "Card A"<br />
Driver "nvidia"<br />
BusID "PCI:1:00:0"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Card B"<br />
Driver "nvidia"<br />
BusID "PCI:2:00:0"<br />
EndSection<br />
<br />
Section "Monitor"<br />
Identifier "Right Monitor"<br />
EndSection<br />
<br />
Section "Monitor"<br />
Identifier "Left Monitor"<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "Right Screen"<br />
Device "Card A"<br />
Monitor "Right Monitor"<br />
DefaultDepth 24<br />
Option "SLI" "Mosaic"<br />
Option "Stereo" "0"<br />
Option "BaseMosaic" "True"<br />
Option "MetaModes" "GPU-0.DFP-0: 1920x1200+4480+0, GPU-1.DFP-0:1920x1200+0+0"<br />
SubSection "Display"<br />
Depth 24<br />
EndSubSection<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "Left Screen"<br />
Device "Card B"<br />
Monitor "Left Monitor"<br />
DefaultDepth 24<br />
Option "SLI" "Mosaic"<br />
Option "Stereo" "0"<br />
Option "BaseMosaic" "True"<br />
Option "MetaModes" "GPU-0.DFP-0: 1920x1200+4480+0, GPU-1.DFP-0:1920x1200+0+0"<br />
SubSection "Display"<br />
Depth 24<br />
EndSubSection<br />
EndSection<br />
<br />
Section "ServerLayout"<br />
Identifier "Default"<br />
Screen 0 "Right Screen" 0 0<br />
Option "Xinerama" "0"<br />
EndSection<br />
}}<br />
<br />
===== Vertical sync using TwinView =====<br />
<br />
If you are using TwinView and vertical sync (the "Sync to VBlank" option in '''nvidia-settings'''), you will notice that only one screen is being properly synced, unless you have two identical monitors. Although '''nvidia-settings''' does offer an option to change which screen is being synced (the "Sync to this display device" option), this does not always work. A solution is to add the following environment variables at startup, for example append in {{ic|/etc/profile}}:<br />
<br />
export __GL_SYNC_TO_VBLANK=1<br />
export __GL_SYNC_DISPLAY_DEVICE=DFP-0<br />
export VDPAU_NVIDIA_SYNC_DISPLAY_DEVICE=DFP-0<br />
<br />
You can change {{ic|DFP-0}} with your preferred screen ({{ic|DFP-0}} is the DVI port and {{ic|CRT-0}} is the VGA port). You can find the identifier for your display from '''nvidia-settings''' in the "X Server XVideoSettings" section.<br />
<br />
===== Gaming using TwinView =====<br />
<br />
In case you want to play fullscreen games when using TwinView, you will notice that games recognize the two screens as being one big screen. While this is technically correct (the virtual X screen really is the size of your screens combined), you probably do not want to play on both screens at the same time. <br />
<br />
To correct this behavior for SDL, try:<br />
<br />
export SDL_VIDEO_FULLSCREEN_HEAD=1<br />
<br />
For OpenGL, add the appropriate Metamodes to your xorg.conf in section {{ic|Device}} and restart X:<br />
<br />
Option "Metamodes" "1680x1050,1680x1050; 1280x1024,1280x1024; 1680x1050,NULL; 1280x1024,NULL;"<br />
<br />
Another method that may either work alone or in conjunction with those mentioned above is [[Gaming#Starting_games_in_a_separate_X_server|starting games in a separate X server]].<br />
<br />
==== Mosaic mode ====<br />
<br />
Mosaic mode is the only way to use more than 2 monitors across multiple graphics cards with compositing. Your window manager may or may not recognize the distinction between each monitor. Mosaic mode requires a valid SLI configuration. Even if using Base mode without SLI, the GPUs must still be SLI capable/compatible.<br />
<br />
===== Base Mosaic =====<br />
<br />
Base Mosaic mode works on any set of Geforce 8000 series or higher GPUs. It cannot be enabled from within the nvidia-setting GUI. You must either use the ''nvidia-xconfig'' command line program or edit {{ic|xorg.conf}} by hand. Metamodes must be specified. The following is an example for four DFPs in a 2x2 configuration, each running at 1920x1024, with two DFPs connected to two cards:<br />
<br />
$ nvidia-xconfig --base-mosaic --metamodes="GPU-0.DFP-0: 1920x1024+0+0, GPU-0.DFP-1: 1920x1024+1920+0, GPU-1.DFP-0: 1920x1024+0+1024, GPU-1.DFP-1: 1920x1024+1920+1024"<br />
<br />
{{Note|While the documentation lists a 2x2 configuration of monitors, [https://devtalk.nvidia.com/default/topic/579449/linux/basemosaic-v295-vs-v310-vs-v325-only-up-to-three-screens-/post/3954733/#3954733 GeForce cards are artificially limited to 3 monitors] in Base Mosaic mode. Quadro cards support more than 3 monitors. As of September 2014, the Windows driver has dropped this artificial restriction, but it remains in the Linux driver.}}<br />
<br />
===== SLI Mosaic =====<br />
<br />
If you have an SLI configuration and each GPU is a Quadro FX 5800, Quadro Fermi or newer then you can use SLI Mosaic mode. It can be enabled from within the nvidia-settings GUI or from the command line with:<br />
<br />
$ nvidia-xconfig --sli=Mosaic --metamodes="GPU-0.DFP-0: 1920x1024+0+0, GPU-0.DFP-1: 1920x1024+1920+0, GPU-1.DFP-0: 1920x1024+0+1024, GPU-1.DFP-1: 1920x1024+1920+1024"<br />
<br />
== Wayland ==<br />
<br />
See [[Wayland#Requirements]] for more information.<br />
<br />
For further configuration options, take a look at the wiki pages or documentation of the respective compositor.<br />
<br />
Regarding XWayland take a look at [[Wayland#XWayland]].<br />
<br />
== Tips and tricks ==<br />
<br />
See [[NVIDIA/Tips and tricks]].<br />
<br />
== Troubleshooting ==<br />
<br />
See [[NVIDIA/Troubleshooting]].<br />
<br />
== See also ==<br />
<br />
* [https://forums.developer.nvidia.com/t/current-graphics-driver-releases/28500 Current graphics driver releases in official Nvidia Forum]<br />
* [https://forums.developer.nvidia.com/c/gpu-unix-graphics/linux/148 NVIDIA Developers Forum - Linux Subforum]</div>Jwh7https://wiki.archlinux.org/index.php?title=Xorg&diff=639965Xorg2020-10-28T15:02:42Z<p>Jwh7: /* Driver installation */ modify card identification to show the specific model via 'Subsystem'</p>
<hr />
<div>[[Category:X server]]<br />
[[cs:Xorg]]<br />
[[da:Xorg]]<br />
[[de:X]]<br />
[[el:Xorg]]<br />
[[es:Xorg]]<br />
[[fr:Xorg]]<br />
[[it:Xorg]]<br />
[[ja:Xorg]]<br />
[[nl:Xorg]]<br />
[[pl:Xorg]]<br />
[[pt:Xorg]]<br />
[[ru:Xorg]]<br />
[[uk:Xorg]]<br />
[[zh-hans:Xorg]]<br />
[[zh-hant:Xorg]]<br />
{{Related articles start}}<br />
{{Related|Autostarting}}<br />
{{Related|Display manager}}<br />
{{Related|Window manager}}<br />
{{Related|Font configuration}}<br />
{{Related|Cursor themes}}<br />
{{Related|Desktop environment}}<br />
{{Related|Wayland}}<br />
{{Related|xinit}}<br />
{{Related|xrandr}}<br />
{{Related articles end}}<br />
From https://www.x.org/wiki/:<br />
:The X.Org project provides an open source implementation of the [[Wikipedia:X Window System|X Window System]]. The development work is being done in conjunction with the freedesktop.org community. The X.Org Foundation is the educational non-profit corporation whose Board serves this effort, and whose Members lead this work.<br />
<br />
'''Xorg''' (commonly referred as simply '''X''') is the most popular display server among Linux users. Its ubiquity has led to making it an ever-present requisite for GUI applications, resulting in massive adoption from most distributions. See the [[Wikipedia:X.Org Server|Xorg]] Wikipedia article or visit the [https://www.x.org/wiki/ Xorg website] for more details.<br />
<br />
== Installation ==<br />
<br />
Xorg can be [[install]]ed with the {{Pkg|xorg-server}} package.<br />
<br />
Additionally, some packages from the {{Grp|xorg-apps}} group are necessary for certain configuration tasks, they are pointed out in the relevant sections.<br />
<br />
Finally, an {{Grp|xorg}} group is also available, which includes Xorg server packages, packages from the {{Grp|xorg-apps}} group and fonts. <br />
<br />
{{Tip|You will typically seek to install a [[window manager]] or a [[desktop environment]] to supplement X.}}<br />
<br />
=== Driver installation ===<br />
<br />
The Linux kernel includes open-source video drivers and support for hardware accelerated framebuffers. However, userland support is required for OpenGL and 2D acceleration in X11.<br />
<br />
First, identify the graphics card (the ''Subsystem'' output shows the specific model):<br />
<br />
$ lspci -v | grep -A1 -e VGA -e 3D<br />
<br />
Then install an appropriate driver. You can search the package database for a complete list of open-source video drivers:<br />
<br />
$ pacman -Ss xf86-video<br />
<br />
Xorg searches for installed drivers automatically:<br />
<br />
* If it cannot find the specific driver installed for the hardware (listed below), it first searches for ''fbdev'' ({{pkg|xf86-video-fbdev}}).<br />
* If that is not found, it searches for ''vesa'' ({{pkg|xf86-video-vesa}}), the generic driver, which handles a large number of chipsets but does not include any 2D or 3D acceleration.<br />
* If ''vesa'' is not found, Xorg will fall back to [[kernel mode setting]], which includes GLAMOR acceleration (see {{man|4|modesetting}}).<br />
<br />
In order for video acceleration to work, and often to expose all the modes that the GPU can set, a proper video driver is required:<br />
<br />
{| class="wikitable" style="text-align:center"<br />
|-<br />
! Brand !! Type !! Driver !! OpenGL !! OpenGL ([[multilib]]) !! Documentation<br />
|-<br />
! rowspan="2" | AMD / ATI<br />
| rowspan="2" | Open source || {{Pkg|xf86-video-amdgpu}} || rowspan="2" | {{Pkg|mesa}} || rowspan="2" | {{Pkg|lib32-mesa}} || [[AMDGPU]]<br />
|-<br />
| {{Pkg|xf86-video-ati}} || [[ATI]]<br />
|-<br />
! Intel<br />
| Open source || {{Pkg|xf86-video-intel}} || {{Pkg|mesa}} || {{Pkg|lib32-mesa}} || [[Intel graphics]]<br />
|-<br />
! rowspan="3" | NVIDIA<br />
| Open source || {{Pkg|xf86-video-nouveau}} || {{Pkg|mesa}} || {{Pkg|lib32-mesa}} || [[Nouveau]]<br />
|-<br />
| rowspan="2" | Proprietary || {{Pkg|nvidia}} || {{Pkg|nvidia-utils}} || {{Pkg|lib32-nvidia-utils}} || rowspan="2" | [[NVIDIA]]<br />
|-<br />
| {{AUR|nvidia-390xx}} || {{AUR|nvidia-390xx-utils}} || {{AUR|lib32-nvidia-390xx-utils}}<br />
|}<br />
<br />
{{Note|<br />
* For NVIDIA Optimus enabled laptop which uses an integrated video card combined with a dedicated GPU, see [[NVIDIA Optimus]].<br />
* For Intel graphics on 4th generation and above, see [[Intel graphics#Installation]] for available drivers.<br />
}}<br />
<br />
Other video drivers can be found in the {{Grp|xorg-drivers}} group.<br />
<br />
Xorg should run smoothly without closed source drivers, which are typically needed only for advanced features such as fast 3D-accelerated rendering for games. The exceptions to this rule are recent GPUs (especially NVIDIA GPUs), that are not supported by the open source drivers.<br />
<br />
=== AMD ===<br />
<br />
{| class="wikitable" style="text-align:center"<br />
|-<br />
! GPU architecture !! Radeon cards !! Open-source driver !! Proprietary driver<br />
|-<br />
| GCN 4<br/>and newer || rowspan=4 | [[wikipedia:List of AMD graphics processing units|various]] || [[AMDGPU]] || [[AMDGPU PRO]]<br />
|-<br />
| GCN 3 || [[AMDGPU]] || [[Catalyst]] /<br/>[[AMDGPU PRO]]<br />
|- <br />
| GCN 2 || [[AMDGPU]]* / [[ATI]] || [[Catalyst]]<br />
|- <br />
| GCN 1 || [[AMDGPU]]* / [[ATI]] || [[Catalyst]]<br />
|-<br />
| TeraScale 2&3 || HD 5000 - HD 6000 || rowspan=3 | [[ATI]] || [[Catalyst]]<br />
|-<br />
| TeraScale 1 || HD 2000 - HD 4000 || [[Catalyst]] legacy<br />
|-<br />
| Older || X1000 and older || ''not available''<br />
|-<br />
|}<br />
: *: Experimental<br />
<br />
== Running ==<br />
<br />
The {{man|1|Xorg}} command is usually not run directly, instead the X server is started with either a [[display manager]] or [[xinit]].<br />
<br />
== Configuration ==<br />
<br />
{{Note|Arch supplies default configuration files in {{ic|/usr/share/X11/xorg.conf.d/}}, and no extra configuration is necessary for most setups.}}<br />
<br />
Xorg uses a configuration file called {{ic|xorg.conf}} and files ending in the suffix {{ic|.conf}} for its initial setup: the complete list of the folders where these files are searched can be found in {{man|5|xorg.conf}}, together with a detailed explanation of all the available options.<br />
<br />
=== Using .conf files ===<br />
<br />
The {{ic|/etc/X11/xorg.conf.d/}} directory stores host-specific configuration. You are free to add configuration files there, but they must have a {{ic|.conf}} suffix: the files are read in ASCII order, and by convention their names start with {{ic|''XX''-}} (two digits and a hyphen, so that for example 10 is read before 20). These files are parsed by the X server upon startup and are treated like part of the traditional {{ic|xorg.conf}} configuration file. Note that on conflicting configuration, the file read ''last'' will be processed. For that reason the most generic configuration files should be ordered first by name. The configuration entries in the {{ic|xorg.conf}} file are processed at the end. <br />
<br />
For option examples to set, see also the [https://fedoraproject.org/wiki/Input_device_configuration#xorg.conf.d Fedora wiki].<br />
<br />
=== Using xorg.conf ===<br />
<br />
Xorg can also be configured via {{ic|/etc/X11/xorg.conf}} or {{ic|/etc/xorg.conf}}. You can also generate a skeleton for {{ic|xorg.conf}} with:<br />
<br />
# Xorg :0 -configure<br />
<br />
This should create a {{ic|xorg.conf.new}} file in {{ic|/root/}} that you can copy over to {{ic|/etc/X11/xorg.conf}}.<br />
<br />
{{Tip|If you are already running an X server, use a different display, for example {{ic|Xorg :2 -configure}}.}}<br />
<br />
Alternatively, your proprietary video card drivers may come with a tool to automatically configure Xorg: see the article of your video driver, [[NVIDIA]] or [[AMD Catalyst]], for more details.<br />
<br />
{{Note|Configuration file keywords are case insensitive, and "_" characters are ignored. Most strings (including Option names) are also case insensitive, and insensitive to white space and "_" characters.}}<br />
<br />
== Input devices ==<br />
<br />
For input devices the X server defaults to the libinput driver ({{Pkg|xf86-input-libinput}}), but {{Pkg|xf86-input-evdev}} and related drivers are available as alternative.[https://www.archlinux.org/news/xorg-server-1191-is-now-in-extra/]<br />
<br />
[[Udev]], which is provided as a systemd dependency, will detect hardware and both drivers will act as hotplugging input driver for almost all devices, as defined in the default configuration files {{ic|10-quirks.conf}} and {{ic|40-libinput.conf}} in the {{ic|/usr/share/X11/xorg.conf.d/}} directory.<br />
<br />
After starting X server, the log file will show which driver hotplugged for the individual devices (note the most recent log file name may vary): <br />
$ grep -e "Using input driver " Xorg.0.log<br />
<br />
If both do not support a particular device, install the needed driver from the {{Grp|xorg-drivers}} group. The same applies, if you want to use another driver. <br />
<br />
To influence hotplugging, see [[#Configuration]]. <br />
<br />
For specific instructions, see also the [[libinput]] article, the following pages below, or the [https://fedoraproject.org/wiki/Input_device_configuration Fedora wiki] entry for more examples.<br />
<br />
=== Input identification ===<br />
<br />
See [[Keyboard input#Identifying keycodes in Xorg]].<br />
<br />
=== Mouse acceleration ===<br />
<br />
See [[Mouse acceleration]].<br />
<br />
=== Extra mouse buttons ===<br />
<br />
See [[Mouse buttons]].<br />
<br />
=== Touchpad ===<br />
<br />
See [[libinput]] or [[Synaptics]].<br />
<br />
=== Touchscreen ===<br />
<br />
See [[Touchscreen]].<br />
<br />
=== Keyboard settings ===<br />
<br />
See [[Keyboard configuration in Xorg]].<br />
<br />
== Monitor settings ==<br />
<br />
=== Manual configuration ===<br />
<br />
{{Note|<br />
* Newer versions of Xorg are auto-configuring, so manual configuration should not be needed.<br />
* If Xorg is unable to detect any monitor or to avoid auto-configuring, a configuration file can be used. A common case where this is necessary is a headless system, which boots without a monitor and starts Xorg automatically, either from a [[Automatic login to virtual console|virtual console]] at [[Start X at login|login]], or from a [[display manager]].<br />
}}<br />
<br />
For a headless configuration the {{pkg|xf86-video-dummy}} driver is necessary; [[install]] it and create a configuration file, such as the following:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/10-headless.conf|<br />
Section "Monitor"<br />
Identifier "dummy_monitor"<br />
HorizSync 28.0-80.0<br />
VertRefresh 48.0-75.0<br />
Modeline "1920x1080" 172.80 1920 2040 2248 2576 1080 1081 1084 1118<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "dummy_card"<br />
VideoRam 256000<br />
Driver "dummy"<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "dummy_screen"<br />
Device "dummy_card"<br />
Monitor "dummy_monitor"<br />
SubSection "Display"<br />
EndSubSection<br />
EndSection<br />
}}<br />
<br />
=== Multiple monitors ===<br />
<br />
See main article [[Multihead]] for general information.<br />
<br />
See also GPU-specific instructions:<br />
<br />
* [[NVIDIA#Multiple monitors]]<br />
* [[Nouveau#Dual head]]<br />
* [[AMD Catalyst#Double Screen (Dual Head / Dual Screen / Xinerama)]]<br />
* [[ATI#Multihead setup]]<br />
<br />
==== More than one graphics card ====<br />
<br />
You must define the correct driver to use and put the bus ID of your graphic cards (in decimal notation).<br />
<br />
{{bc|<br />
Section "Device"<br />
Identifier "Screen0"<br />
Driver "intel"<br />
BusID "PCI:0:2:0"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Screen1"<br />
Driver "nouveau"<br />
BusID "PCI:1:0:0"<br />
EndSection<br />
}}<br />
<br />
To get your bus IDs (in hexadecimal):<br />
<br />
{{hc|$ lspci {{!}} grep -e VGA -e 3D|<br />
00:02.0 VGA compatible controller: Intel Corporation HD Graphics 630 (rev 04)<br />
01:00.0 3D controller: NVIDIA Corporation GP107M [GeForce GTX 1050 Mobile] (rev a1)<br />
}}<br />
<br />
The bus IDs here are 0:2:0 and 1:0:0.<br />
<br />
=== Display size and DPI ===<br />
<br />
{{Accuracy|1=Xorg always sets dpi to 96. See [https://bugs.freedesktop.org/show_bug.cgi?id=23705 this], [https://gitlab.freedesktop.org/xorg/xserver/issues/253 this] and finally [https://pastebin.com/vtzyBK6e this].}}<br />
<br />
The DPI of the X server is determined in the following manner:<br />
<br />
# The {{ic|-dpi}} command line option has highest priority.<br />
# If this is not used, the {{ic|DisplaySize}} setting in the X config file is used to derive the DPI, given the screen resolution.<br />
# If no {{ic|DisplaySize}} is given, the monitor size values from [[Wikipedia:Display Data Channel|DDC]] are used to derive the DPI, given the screen resolution.<br />
# If DDC does not specify a size, 75 DPI is used by default.<br />
<br />
In order to get correct dots per inch (DPI) set, the display size must be recognized or set. Having the correct DPI is especially necessary where fine detail is required (like font rendering). Previously, manufacturers tried to create a standard for 96 DPI (a 10.3" diagonal monitor would be 800x600, a 13.2" monitor 1024x768). These days, screen DPIs vary and may not be equal horizontally and vertically. For example, a 19" widescreen LCD at 1440x900 may have a DPI of 89x87. To be able to set the DPI, the Xorg server attempts to auto-detect your monitor's physical screen size through the graphic card with DDC. <s>When the Xorg server knows the physical screen size, it will be able to set the correct DPI depending on resolution size.</s><br />
<br />
To see if your display size and DPI are detected/calculated correctly:<br />
<br />
$ xdpyinfo | grep -B2 resolution<br />
<br />
Check that the dimensions match your display size. If the Xorg server is not able to correctly calculate the screen size, it will default to 75x75 DPI and you will have to calculate it yourself.<br />
<br />
If you have specifications on the physical size of the screen, they can be entered in the Xorg configuration file so that the proper DPI is calculated (adjust identifier to your xrandr output) :<br />
<br />
{{bc|<br />
Section "Monitor"<br />
Identifier "DVI-D-0"<br />
DisplaySize 286 179 # In millimeters<br />
EndSection<br />
}}<br />
<br />
If you only want to enter the specification of your monitor '''without''' creating a full xorg.conf create a new config file. For example ({{ic|/etc/X11/xorg.conf.d/90-monitor.conf}}):<br />
<br />
{{bc|<br />
Section "Monitor"<br />
Identifier "<default monitor>"<br />
DisplaySize 286 179 # In millimeters<br />
EndSection<br />
}}<br />
<br />
If you do not have specifications for physical screen width and height (most specifications these days only list by diagonal size), you can use the monitor's native resolution (or aspect ratio) and diagonal length to calculate the horizontal and vertical physical dimensions. Using the Pythagorean theorem on a 13.3" diagonal length screen with a 1280x800 native resolution (or 16:10 aspect ratio):<br />
<br />
$ echo 'scale=5;sqrt(1280^2+800^2)' | bc # 1509.43698<br />
<br />
This will give the pixel diagonal length and with this value you can discover the physical horizontal and vertical lengths (and convert them to millimeters):<br />
<br />
$ echo 'scale=5;(13.3/1509)*1280*25.4' | bc # 286.43072<br />
$ echo 'scale=5;(13.3/1509)*800*25.4' | bc # 179.01920<br />
<br />
{{Note|This calculation works for monitors with square pixels; however, there is the seldom monitor that may compress aspect ratio (e.g 16:10 aspect resolution to a 16:9 monitor). If this is the case, you should measure your screen size manually.}}<br />
<br />
==== Setting DPI manually ====<br />
<br />
{{Note|While you can set any dpi you like and applications using Qt and GTK will scale accordingly, it's recommended to set it to 96, 120 (25% higher), 144 (50% higher), 168 (75% higher), 192 (100% higher) etc., to reduce scaling artifacts to GUI that use bitmaps. Reducing it below 96 dpi may not reduce size of graphical elements of GUI as typically the lowest dpi the icons are made for is 96.}}<br />
<br />
For RandR compliant drivers (for example the open source ATI driver), you can set it by:<br />
<br />
$ xrandr --dpi 144<br />
<br />
{{Note|Applications that comply with the setting will not change immediately. You have to start them anew.}}<br />
<br />
To make it permanent, see [[Autostarting#On Xorg startup]].<br />
<br />
===== Proprietary NVIDIA driver =====<br />
<br />
DPI can be set manually if you only plan to use one resolution ([https://www.pxcalc.com/ DPI calculator]):<br />
<br />
{{bc|<br />
Section "Monitor"<br />
Identifier "Monitor0"<br />
Option "DPI" "96 x 96"<br />
EndSection<br />
}}<br />
<br />
You can manually set the DPI adding the options below on {{ic|/etc/X11/xorg.conf.d/20-nvidia.conf}} (inside '''Device''' section):<br />
<br />
Option "UseEdidDpi" "False"<br />
Option "DPI" "96 x 96"<br />
<br />
===== Manual DPI Setting Caveat =====<br />
<br />
GTK very often overrides the server's DPI via the optional Xresource {{ic|Xft.dpi}}. To find out whether this is happening to you, check with:<br />
<br />
$ xrdb -query | grep dpi<br />
<br />
With GTK library versions since 3.16, when this variable is not otherwise explicitly set, GTK sets it to 96. To have GTK apps obey the server DPI you may need to explictly set Xft.dpi to the same value as the server. The Xft.dpi resource is the method by which some desktop environments optionally force DPI to a particular value in personal settings. Among these are [[KDE]] and [[TDE]].<br />
<br />
=== Display Power Management ===<br />
<br />
[[DPMS]] (Display Power Management Signaling) is a technology that allows power saving behaviour of monitors when the computer is not in use. This will allow you to have your monitors automatically go into standby after a predefined period of time.<br />
<br />
== Composite ==<br />
<br />
The Composite extension for X causes an entire sub-tree of the window hierarchy to be rendered to an off-screen buffer. Applications can then take the contents of that buffer and do whatever they like. The off-screen buffer can be automatically merged into the parent window or merged by external programs, called compositing managers. See the following article for more information: [[Wikipedia:Compositing window manager|compositing window manager]]<br />
<br />
Some window managers (e.g. [[Compiz]], [[Enlightenment]], KWin, Marco, Metacity, Muffin, Mutter, [[Xfwm]]) do compositing on their own. For other window managers, a standalone composite manager can be used.<br />
<br />
=== List of composite managers ===<br />
<br />
* {{App|[[Picom]]|Compositor (a fork of Compton)|https://github.com/yshui/picom|{{Pkg|picom}}}}<br />
* {{App|[[Xcompmgr]]|Composite window-effects manager|https://cgit.freedesktop.org/xorg/app/xcompmgr/|{{Pkg|xcompmgr}}}}<br />
* {{App|Unagi|Modular compositing manager which aims written in C and based on XCB|https://projects.mini-dweeb.org/projects/unagi|{{AUR|unagi}}}}<br />
<br />
== Tips and tricks ==<br />
<br />
{{Expansion|Mention {{Pkg|xorg-xkill}}.}}<br />
<br />
=== Automation ===<br />
<br />
This section lists utilities for automating keyboard / mouse input and window operations (like moving, resizing or raising).<br />
<br />
{| class="wikitable"<br />
! Tool !! Package !! Manual !! [[Keysym]]<br>input !! Window<br>operations !! Note<br />
|-<br />
! xautomation<br />
| {{Pkg|xautomation}} || {{man|1|xte}} || {{Yes}} || {{No}} || Also contains screen scraping tools. Cannot simulate F13+.<br />
|-<br />
! xdo<br />
| {{Pkg|xdo}} || {{man|1|xdo}} || {{No}} || {{Yes}} || Small X utility to perform elementary actions on windows.<br />
|-<br />
! xdotool<br />
| {{Pkg|xdotool}} || {{man|1|xdotool}} || {{Yes}} || {{Yes}} || [https://github.com/jordansissel/xdotool/issues Very buggy] and not in active development, e.g: has broken CLI parsing.[https://github.com/jordansissel/xdotool/issues/14#issuecomment-327968132][https://github.com/jordansissel/xdotool/issues/71]<br />
|-<br />
! xvkbd<br />
| {{AUR|xvkbd}} || {{man|1|xvkbd|url=http://t-sato.in.coocan.jp/xvkbd/#option}} || {{Yes}} || {{No}} || Virtual keyboard for Xorg, also has the {{ic|-text}} option for sending characters.<br />
|<br />
|-<br />
! AutoKey<br />
| {{AUR|autokey}} || [https://github.com/autokey/autokey#documentation documentation] || {{Yes}} || {{Yes}} || Higher-level, powerful macro and scripting utility, with both Qt and Gtk front-ends.<br />
|}<br />
<br />
See also [[Clipboard#Tools]] and [https://venam.nixers.net/blog/unix/2019/01/07/win-automation.html an overview of X automation tools].<br />
<br />
=== Nested X session ===<br />
<br />
{{Expansion|mention [[Awesome#Using_Xephyr|xephyr]]}}<br />
<br />
To run a nested session of another desktop environment:<br />
<br />
$ /usr/bin/Xnest :1 -geometry 1024x768+0+0 -ac -name Windowmaker & wmaker -display :1<br />
<br />
This will launch a Window Maker session in a 1024 by 768 window within your current X session.<br />
<br />
This needs the package {{Pkg|xorg-server-xnest}} to be installed.<br />
<br />
=== Starting GUI programs remotely ===<br />
<br />
See main article: [[OpenSSH#X11 forwarding]].<br />
<br />
=== On-demand disabling and enabling of input sources ===<br />
<br />
With the help of ''xinput'' you can temporarily disable or enable input sources. This might be useful, for example, on systems that have more than one mouse, such as the ThinkPads and you would rather use just one to avoid unwanted mouse clicks.<br />
<br />
[[Install]] the {{Pkg|xorg-xinput}} package.<br />
<br />
Find the name or ID of the device you want to disable:<br />
<br />
$ xinput<br />
<br />
For example in a Lenovo ThinkPad T500, the output looks like this:<br />
<br />
{{hc|$ xinput|<nowiki><br />
⎡ Virtual core pointer id=2 [master pointer (3)]<br />
⎜ ↳ Virtual core XTEST pointer id=4 [slave pointer (2)]<br />
⎜ ↳ TPPS/2 IBM TrackPoint id=11 [slave pointer (2)]<br />
⎜ ↳ SynPS/2 Synaptics TouchPad id=10 [slave pointer (2)]<br />
⎣ Virtual core keyboard id=3 [master keyboard (2)]<br />
↳ Virtual core XTEST keyboard id=5 [slave keyboard (3)]<br />
↳ Power Button id=6 [slave keyboard (3)]<br />
↳ Video Bus id=7 [slave keyboard (3)]<br />
↳ Sleep Button id=8 [slave keyboard (3)]<br />
↳ AT Translated Set 2 keyboard id=9 [slave keyboard (3)]<br />
↳ ThinkPad Extra Buttons id=12 [slave keyboard (3)]<br />
</nowiki>}}<br />
<br />
Disable the device with {{ic|xinput --disable ''device''}}, where ''device'' is the device ID or name of the device you want to disable. In this example we will disable the Synaptics Touchpad, with the ID 10:<br />
<br />
$ xinput --disable 10<br />
<br />
To re-enable the device, just issue the opposite command:<br />
<br />
$ xinput --enable 10<br />
<br />
Alternatively using the device name, the command to disable the touchpad would be:<br />
<br />
$ xinput --disable "SynPS/2 Synaptics TouchPad"<br />
<br />
=== Killing application with hotkey ===<br />
<br />
Run script on hotkey:<br />
<br />
#!/bin/bash<br />
windowFocus=$(xdotool getwindowfocus);<br />
pid=$(xprop -id $windowFocus | grep PID);<br />
kill -9 $pid<br />
<br />
Deps: {{Pkg|xorg-xprop}}, {{Pkg|xdotool}}<br />
<br />
=== Block TTY access ===<br />
<br />
{{Expansion|Why would you want to do this?}}<br />
<br />
To block tty access when in an X add the following to [[#Configuration|xorg.conf]]:<br />
<br />
{{bc|<br />
Section "ServerFlags"<br />
Option "DontVTSwitch" "True"<br />
EndSection<br />
}}<br />
<br />
=== Prevent a user from killing X ===<br />
<br />
To prevent a user from killing when it is running add the following to [[#Configuration|xorg.conf]]:<br />
<br />
{{bc|<br />
Section "ServerFlags"<br />
Option "DontZap" "True"<br />
EndSection<br />
}}<br />
<br />
=== Rootless Xorg ===<br />
<br />
Xorg may run with standard user privileges instead of root (so-called "rootless" Xorg). This is a significant security improvement over running as root. Note that most display managers do not support rootless Xorg.<br />
<br />
You can verify which user Xorg is running as with {{ic|ps -o user $(pgrep Xorg)}}.<br />
<br />
See also {{man|1|Xorg.wrap}}, {{man|8|systemd-logind}}, [[Systemd/User#Xorg as a systemd user service]], [https://fedoraproject.org/wiki/Changes/XorgWithoutRootRights] and {{Bug|41257}}. <br />
<br />
==== Using xinitrc ====<br />
<br />
To configure rootless Xorg using [[xinitrc]]:<br />
<br />
* Run startx as a subprocess of the login shell; run {{ic|startx}} directly and do not use {{ic|exec startx}}.<br />
* If using certain proprietary display drivers, [[kernel mode setting]] [https://cgit.freedesktop.org/xorg/xserver/tree/hw/xfree86/xorg-wrapper.c#n222 auto-detection] will fail. In such cases, you must set {{ic|1=needs_root_rights = no}} in {{ic|/etc/X11/Xwrapper.config}}.<br />
<br />
==== Using GDM ====<br />
<br />
[[GDM]] will run Xorg without root privileges by default when [[kernel mode setting]] is used.<br />
<br />
==== Session log redirection ====<br />
<br />
When Xorg is run in rootless mode, Xorg logs are saved to {{ic|~/.local/share/xorg/Xorg.log}}. However, the stdout and stderr output from the Xorg session is not redirected to this log. To re-enable redirection, start Xorg with the {{ic|-keeptty}} flag and redirect the stdout and stderr output to a file:<br />
<br />
startx -- -keeptty &> ~/.xorg.log<br />
<br />
Alternatively, copy {{ic|/etc/X11/xinit/xserverrc}} to {{ic|~/.xserverrc}}, and append {{ic|-keeptty}}. See [https://bbs.archlinux.org/viewtopic.php?pid=1446402#p1446402].<br />
<br />
== Troubleshooting ==<br />
<br />
=== General ===<br />
<br />
If a problem occurs, view the log stored in either {{ic|/var/log/}} or, for the rootless X default since v1.16, in {{ic|~/.local/share/xorg/}}. [[GDM]] users should check the [[systemd journal]]. [https://bbs.archlinux.org/viewtopic.php?id=184639]<br />
<br />
The logfiles are of the form {{ic|Xorg.n.log}} with {{ic|n}} being the display number. For a single user machine with default configuration the applicable log is frequently {{ic|Xorg.0.log}}, but otherwise it may vary. To make sure to pick the right file it may help to look at the timestamp of the X server session start and from which console it was started. For example: <br />
<br />
{{hc|$ grep -e Log -e tty Xorg.0.log|2=<br />
[ 40.623] (==) Log file: "/home/archuser/.local/share/xorg/Xorg.0.log", Time: Thu Aug 28 12:36:44 2014<br />
[ 40.704] (--) controlling tty is VT number 1, auto-enabling KeepTty<br />
}}<br />
<br />
* In the logfile then be on the lookout for any lines beginning with {{ic|(EE)}}, which represent errors, and also {{ic|(WW)}}, which are warnings that could indicate other issues.<br />
* If there is an ''empty'' {{ic|.xinitrc}} file in your {{ic|$HOME}}, either delete or edit it in order for X to start properly. If you do not do this X will show a blank screen with what appears to be no errors in your {{ic|Xorg.0.log}}. Simply deleting it will get it running with a default X environment.<br />
* If the screen goes black, you may still attempt to switch to a different virtual console (e.g. {{ic|Ctrl+Alt+F6}}), and blindly log in as root. You can do this by typing {{ic|root}} (press {{ic|Enter}} after typing it) and entering the root password (again, press {{ic|Enter}} after typing it).<br />
<br />
: You may also attempt to kill the X server with:<br />
: {{bc|# pkill -x X}}<br />
: If this does not work, reboot blindly with:<br />
: {{bc|# reboot}}<br />
<br />
* Check specific pages in [[:Category:Input devices]] if you have issues with keyboard, mouse, touchpad etc.<br />
* Search for common problems in [[ATI]], [[Intel]] and [[NVIDIA]] articles.<br />
<br />
=== Black screen, No protocol specified.., Resource temporarily unavailable for all or some users ===<br />
<br />
X creates configuration and temporary files in current user's home directory. Make sure there is free disk space available on the partition your home directory resides in. Unfortunately, X server does not provide any more obvious information about lack of disk space in this case.<br />
<br />
=== DRI with Matrox cards stopped working ===<br />
<br />
If you use a Matrox card and DRI stopped working after upgrading to Xorg, try adding the line:<br />
<br />
Option "OldDmaInit" "On"<br />
<br />
to the Device section that references the video card in {{ic|xorg.conf}}.<br />
<br />
=== Frame-buffer mode problems ===<br />
<br />
If X fails to start with the following log messages,<br />
<br />
{{bc|<nowiki><br />
(WW) Falling back to old probe method for fbdev<br />
(II) Loading sub module "fbdevhw"<br />
(II) LoadModule: "fbdevhw"<br />
(II) Loading /usr/lib/xorg/modules/linux//libfbdevhw.so<br />
(II) Module fbdevhw: vendor="X.Org Foundation"<br />
compiled for 1.6.1, module version=0.0.2<br />
ABI class: X.Org Video Driver, version 5.0<br />
(II) FBDEV(1): using default device<br />
<br />
Fatal server error:<br />
Cannot run in framebuffer mode. Please specify busIDs for all framebuffer devices<br />
</nowiki>}}<br />
<br />
[[Uninstall]] the {{pkg|xf86-video-fbdev}} package.<br />
<br />
=== Program requests "font '(null)'" ===<br />
<br />
Error message: {{ic|unable to load font `(null)'}}.<br />
<br />
Some programs only work with bitmap fonts. Two major packages with bitmap fonts are available, {{Pkg|xorg-fonts-75dpi}} and {{Pkg|xorg-fonts-100dpi}}. You do not need both; one should be enough. To find out which one would be better in your case, try {{ic|xdpyinfo}} from {{Pkg|xorg-xdpyinfo}}, like this:<br />
<br />
$ xdpyinfo | grep resolution<br />
<br />
and use what is closer to the shown value.<br />
<br />
=== Recovery: disabling Xorg before GUI login ===<br />
<br />
If Xorg is set to boot up automatically and for some reason you need to prevent it from starting up before the login/display manager appears (if the system is wrongly configured and Xorg does not recognize your mouse or keyboard input, for instance), you can accomplish this task with two methods.<br />
<br />
* Change default target to rescue.target. See [[systemd#Change default target to boot into]].<br />
* If you have not only a faulty system that makes Xorg unusable, but you have also set the GRUB menu wait time to zero, or cannot otherwise use GRUB to prevent Xorg from booting, you can use the Arch Linux live CD. Follow the [[Installation_guide#Format the partitions|installation guide]] about how to mount and chroot into the installed Arch Linux. Alternatively try to switch into another [[tty]] with {{ic|Ctrl+Alt}} + function key (usually from {{ic|F1}} to {{ic|F7}} depending on which is not used by X), login as root and follow steps below.<br />
<br />
Depending on setup, you will need to do one or more of these steps:<br />
<br />
* [[Disable]] the [[display manager]].<br />
* Disable the [[start X at login|automatic start of the X]].<br />
* Rename the {{ic|~/.xinitrc}} or comment out the {{ic|exec}} line in it.<br />
<br />
=== X clients started with "su" fail ===<br />
<br />
If you are getting "Client is not authorized to connect to server", try adding the line:<br />
<br />
session optional pam_xauth.so<br />
<br />
to {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}}. {{ic|pam_xauth}} will then properly set environment variables and handle {{ic|xauth}} keys.<br />
<br />
=== X failed to start: Keyboard initialization failed ===<br />
<br />
If the filesystem (specifically {{ic|/tmp}}) is full, {{ic|startx}} will fail. {{ic|/var/log/Xorg.0.log}} will end with:<br />
<br />
{{bc|<nowiki><br />
(EE) Error compiling keymap (server-0)<br />
(EE) XKB: Could not compile keymap<br />
(EE) XKB: Failed to load keymap. Loading default keymap instead.<br />
(EE) Error compiling keymap (server-0)<br />
(EE) XKB: Could not compile keymap<br />
XKB: Failed to compile keymap<br />
Keyboard initialization failed. This could be a missing or incorrect setup of xkeyboard-config.<br />
Fatal server error:<br />
Failed to activate core devices.<br />
Please consult the The X.Org Foundation support at http://wiki.x.org<br />
for help.<br />
Please also check the log file at "/var/log/Xorg.0.log" for additional information.<br />
(II) AIGLX: Suspending AIGLX clients for VT switch<br />
</nowiki>}}<br />
<br />
Make some free space on the relevant filesystem and X will start.<br />
<br />
=== A green screen whenever trying to watch a video===<br />
<br />
Your color depth is set wrong. It may need to be 24 instead of 16, for example.<br />
<br />
=== SocketCreateListener error ===<br />
<br />
If X terminates with error message "SocketCreateListener() failed", you may need to delete socket files in {{ic|/tmp/.X11-unix}}. This may happen if you have previously run Xorg as root (e.g. to generate an {{ic|xorg.conf}}).<br />
<br />
=== Invalid MIT-MAGIC-COOKIE-1 key when trying to run a program as root ===<br />
<br />
That error means that only the current user has access to the X server. The solution is to give access to root:<br />
<br />
$ xhost +si:localuser:root<br />
<br />
That line can also be used to give access to X to a different user than root.<br />
<br />
=== Xorg-server Fatal server error: (EE) AddScreen/ScreenInit ===<br />
<br />
If the Xorg server is not working randomly and in the Xorg log you see:<br />
<br />
systemd-logind: failed to take device /dev/dri/card0: Operation not permitted<br />
...<br />
AddScreen/ScreenInit failed for driver 0<br />
<br />
Then, this problem may be caused by [https://github.com/systemd/systemd/issues/13943 systemd issue 13943]. Set up [[Kernel mode setting#Early KMS start|early KMS start]].<br />
<br />
== See also ==<br />
<br />
* [https://magcius.github.io/xplain/article/ Xplain] - In-depth explanation of the X Window System<br />
* {{man|1|Xorg}} - Xorg's Manual Page<br />
* [https://wiki.gentoo.org/wiki/Xorg/Guide/en#Configuration Gentoo/Xorg#Configuration] - Gentoo Wiki's Xorg Configuration page</div>Jwh7https://wiki.archlinux.org/index.php?title=Wine&diff=636530Wine2020-09-26T03:54:41Z<p>Jwh7: /* Networking */ show how to remove the setcap command</p>
<hr />
<div>[[Category:Emulation]]<br />
[[Category:Gaming]]<br />
[[cs:Wine]]<br />
[[de:Wine]]<br />
[[es:Wine]]<br />
[[fr:Wine]]<br />
[[it:Wine]]<br />
[[ja:Wine]]<br />
[[ru:Wine]]<br />
[[zh-hans:Wine]]<br />
[[zh-hant:Wine]]<br />
{{Related articles start}}<br />
{{Related|CrossOver}}<br />
{{Related|Deepin-wine}}<br />
{{Related|Wine package guidelines}}<br />
{{Related articles end}}<br />
[[Wikipedia:Wine (software)|Wine]] is a ''compatibility layer'' capable of running Microsoft Windows applications on Unix-like operating systems. Programs running in Wine act as native programs would, without the performance/memory penalties of an emulator.<br />
<br />
{{Warning|If you can access a file or resource with your user account, programs running in Wine can too. See [[#Running Wine under a separate user account]] and [[Security#Sandboxing applications]] for possible precautions.}}<br />
<br />
== Installation ==<br />
<br />
Wine can be installed by enabling the [[multilib]] repository and [[install]]ing the {{Pkg|wine}} (development) or {{Pkg|wine-staging}} (testing) package. [https://wine-staging.com/ Wine Staging] is a patched version of [https://www.winehq.org/ Wine], which contains bug fixes and features that have not been integrated into the stable or development branch yet. See also [[#Graphics drivers]] and [[#Sound]].<br />
<br />
Consider installing {{pkg|wine-gecko}} and {{pkg|wine-mono}} for applications that depend on Internet Explorer and .NET, respectively. These packages are not strictly required as Wine will download the relevant files as needed. However, having the files downloaded in advance allows you to work off-line and makes it so Wine does not download the files for each Wine prefix needing them.<br />
<br />
=== Third-party applications ===<br />
<br />
These have their own communities and websites, and are '''not supported''' by greater Wine community. See [https://wiki.winehq.org/Third_Party_Applications Wine Wiki] for more details.<br />
<br />
* {{App|[[CrossOver]]|Paid, commercialized version of Wine which provides more comprehensive end-user support.|https://www.codeweavers.com|{{AUR|crossover}}}}<br />
* {{App|exe-thumbnailer|Generates thumbnails for Windows executable files (.exe, .lnk, .msi, and .dll).|https://github.com/exe-thumbnailer/exe-thumbnailer|{{AUR|exe-thumbnailer}}}}<br />
* {{App|[[Wikipedia:Lutris|Lutris]]|Gaming launcher for all types of games, including Wine games (with prefix management), native Linux games and emulators.|https://lutris.net|{{Pkg|lutris}}}}<br />
* {{App|[[Wikipedia:PlayOnLinux|PlayOnLinux]]|Graphical prefix manager for Wine. Contains scripts to assist with program installation and configuration.|https://www.playonlinux.com|{{Pkg|playonlinux}}}}<br />
* {{App|Proton|Compatibility tool made for [[Steam]] based on Wine and additional components. See [https://www.protondb.com/ ProtonDB] for compatibility list.|https://github.com/ValveSoftware/Proton|{{AUR|proton}}}}<br />
* {{App|PyWinery|Simple graphical prefix manager for Wine.|https://github.com/ergoithz/pywinery|{{AUR|pywinery}}}}<br />
* {{App|Q4Wine|Graphical prefix manager for Wine. Can export [[Qt]] themes into the Wine configuration for better integration.|https://sourceforge.net/projects/q4wine/|{{AUR|q4wine}}}}<br />
<br />
== Configuration ==<br />
<br />
Configuring Wine is typically accomplished using:<br />
<br />
* [https://wiki.winehq.org/Winecfg winecfg] is a GUI configuration tool for Wine, which can be started by running {{ic|winecfg}}.<br />
* [https://wiki.winehq.org/Regedit regedit] is Wine's registry editing tool, which can be started by running {{ic|regedit}}. See WineHQ's article on [https://wiki.winehq.org/Useful_Registry_Keys Useful Registry Keys].<br />
* [https://wiki.winehq.org/Control control] is Wine's implementation of the Windows Control Panel, which can be started by running {{ic|wine control}}.<br />
* See WineHQ's [https://wiki.winehq.org/List_of_Commands List of Commands] for the full list.<br />
<br />
=== WINEPREFIX ===<br />
<br />
By default, Wine stores its configuration files and installed Windows programs in {{ic|~/.wine}}. This directory is commonly called a "Wine prefix" or "Wine bottle". It is created/updated automatically whenever you run a Windows program or one of Wine's bundled programs such as ''winecfg''. The prefix directory also contains a tree which your Windows programs will see as {{ic|C:}} (the C-drive).<br />
<br />
You can override the location Wine uses for a prefix with the {{ic|WINEPREFIX}} [[environment variable]]. This is useful if you want to use separate configurations for different Windows programs. The first time a program is run with a new Wine prefix, Wine will automatically create a directory with a bare C-drive and registry.<br />
<br />
For example, if you run one program with {{ic|1= $ env WINEPREFIX=~/.win-a wine program-a.exe}}, and another with {{ic|1= $ env WINEPREFIX=~/.win-b wine program-b.exe}}, the two programs will each have a separate C-drive and separate registries.<br />
<br />
{{Note|Wine prefixes are not [[Wikipedia:Sandbox (computer security)|sandboxes]]! Programs running under Wine can still access the rest of the system! (for example, {{ic|Z:}} is mapped to {{ic|/}}, regardless of the Wine prefix).}}<br />
<br />
To create a default prefix without running a Windows program or other GUI tool you can use:<br />
<br />
$ env WINEPREFIX=~/.customprefix wineboot -u<br />
<br />
=== WINEARCH ===<br />
<br />
Wine will start a 64-bit environment by default. You can change this behavior using the {{ic|WINEARCH}} [[environment variable]]. Rename your {{ic|~/.wine}} directory and create a new Wine environment by running {{ic|1=$ WINEARCH=win32 winecfg}}. This will get you a 32-bit Wine environment. Not setting {{ic|WINEARCH}} will get you a 64-bit one.<br />
<br />
You can combine this with {{ic|WINEPREFIX}} to make a separate {{ic|win32}} and {{ic|win64}} environment:<br />
<br />
$ WINEARCH=win32 WINEPREFIX=~/win32 winecfg<br />
$ WINEPREFIX=~/win64 winecfg<br />
<br />
You can also use {{ic|WINEARCH}} in combination with other Wine programs, such as ''winetricks'' (using Steam as an example):<br />
<br />
WINEARCH=win32 WINEPREFIX=~/.local/share/wineprefixes/steam winetricks steam<br />
<br />
=== Graphics drivers ===<br />
<br />
You need to install the 32-bit version of your graphics driver. Please install the package that is listed in the ''OpenGL (multilib)'' column in the table in [[Xorg#Driver installation]].<br />
<br />
A good sign that your drivers are inadequate or not properly configured is when Wine reports the following in your terminal window:<br />
<br />
Direct rendering is disabled, most likely your OpenGL drivers have not been installed correctly<br />
<br />
{{Note|You might need to restart X after having installed the correct library.}}<br />
<br />
=== Sound ===<br />
<br />
By default sound issues may arise when running Wine applications. Ensure only one sound device is selected in ''winecfg''.<br />
<br />
* If you want to use the [[ALSA]] driver in Wine, you will need to install {{Pkg|lib32-alsa-lib}} and {{Pkg|lib32-alsa-plugins}}.<br />
* If you want to use the [[PulseAudio]] driver in Wine, you will need to install the {{Pkg|lib32-libpulse}} package.<br />
* If you want to use the [[OSS]] driver in Wine, you will need to install the {{Pkg|lib32-alsa-oss}} package. The OSS driver in the kernel will not suffice.<br />
* Games that use advanced sound systems (''e.g.'' TESV: Skyrim) may additionally require installations of {{Pkg|lib32-openal}}.<br />
<br />
If ''winecfg'' '''still''' fails to detect the audio driver (Selected driver: (none)), [https://wiki.winehq.org/Wine_User's_Guide#Using_Regedit configure it via the registry]. For example, in a case where the microphone was not working in a 32-bit Windows application on a 64-bit stock install of wine-1.9.7, this provided full access to the sound hardware (sound playback and mic): open ''regedit'', look for the key HKEY_CURRENT_USER → Software → Wine → Drivers, and add a string called ''Audio'' and give it the value ''alsa''. Also, it may help to [[#WINEARCH|recreate the prefix]]. <br />
<br />
==== MIDI support ====<br />
<br />
[[MIDI]] was a quite popular system for video games music in the 90's. If you are trying out old games, it is not uncommon that the music will not play out of the box.<br />
Wine has excellent MIDI support. However you first need to make it work on your host system, as explained in [[MIDI]]. Last but not least you need to make sure Wine will use the correct MIDI output.<br />
<br />
=== Other dependencies ===<br />
<br />
* Some applications that play music may require {{Pkg|lib32-mpg123}}.<br />
* Some applications that use native image manipulation libraries may require {{Pkg|lib32-giflib}} and {{Pkg|lib32-libpng}}.<br />
* Some applications that require encryption support may require {{Pkg|lib32-gnutls}}.<br />
* Some applications require 32-bit video codecs or the program crashes. Install {{Pkg|lib32-gst-plugins-base}}, {{Pkg|lib32-gst-plugins-good}}, {{Aur|lib32-gst-plugins-bad}} and {{Aur|lib32-gst-plugins-ugly}}.<br />
* Some applications that use NTLM authentication may require {{Pkg|samba}}.<br />
<br />
=== Fonts ===<br />
<br />
If Wine applications are not showing easily readable fonts, you may not have any fonts installed. To easily link all of the system fonts so they are accessible from wine:<br />
<br />
$ cd ${WINEPREFIX:-~/.wine}/drive_c/windows/Fonts && for i in /usr/share/fonts/**/*.{ttf,otf}; do ln -s "$i" ; done<br />
<br />
Wine uses FreeType to render fonts, and FreeType's defaults changed a few releases ago. Try using this environment setting for wine programs:<br />
<br />
FREETYPE_PROPERTIES="truetype:interpreter-version=35"<br />
<br />
Another possibility is to install Microsoft's TrueType fonts into your wine prefix. See [[MS Fonts]]. If this does not help, try running {{ic|winetricks corefonts}} first, then {{ic|winetricks allfonts}} as a last resort.<br />
<br />
After running such programs, kill all Wine servers and run {{ic|winecfg}}. Fonts should be legible now.<br />
<br />
If the fonts look somehow smeared, import the following text file into the Wine registry with [https://wiki.winehq.org/FAQ#How_do_I_edit_the_Wine_registry.3F regedit]:<br />
<br />
Windows Registry Editor Version 5.00<br />
[HKEY_CURRENT_USER\Software\Wine\X11 Driver]<br />
"ClientSideWithRender"="N"<br />
<br />
For high resolution displays, you can adjust dpi values in winecfg.<br />
<br />
See also [[Font configuration#Applications without fontconfig support]].<br />
<br />
==== Enable font smoothing ====<br />
<br />
A good way to improve wine font rendering is to enable cleartype font smoothing.<br />
To enable "Subpixel smoothing (ClearType) RGB":<br />
<br />
{{bc|<nowiki><br />
cat << EOF > /tmp/fontsmoothing<br />
REGEDIT4<br />
<br />
[HKEY_CURRENT_USER\Control Panel\Desktop]<br />
"FontSmoothing"="2"<br />
"FontSmoothingOrientation"=dword:00000001<br />
"FontSmoothingType"=dword:00000002<br />
"FontSmoothingGamma"=dword:00000578<br />
EOF<br />
<br />
WINE=${WINE:-wine} WINEPREFIX=${WINEPREFIX:-$HOME/.wine} $WINE regedit /tmp/fontsmoothing 2> /dev/null<br />
</nowiki>}}<br />
<br />
For more information, check [https://askubuntu.com/a/219795/514682 the original answer]<br />
<br />
=== Desktop launcher menus ===<br />
<br />
When a Windows application installer creates a shortcut Wine creates a {{ic|.desktop}} file instead. The default locations for those files in Arch Linux are:<br />
<br />
* Desktop shortcuts are put in {{ic|~/Desktop}}<br />
* Start menu shortcuts are put in {{ic|~/.local/share/applications/wine/Programs/}}<br />
<br />
{{Note|1=Wine does not support installing Windows applications for all users, so it will not put {{ic|.desktop}} files in {{ic|/usr/share/applications}}. See WineHQ bug [https://bugs.winehq.org/show_bug.cgi?id=11112 11112]}}<br />
<br />
{{Tip|If menu items were ''not'' created while installing software or have been lost, {{ic|wine winemenubuilder}} may be of some use.}}<br />
<br />
==== Creating menu entries for Wine utilities ====<br />
<br />
By default, installation of Wine does not create desktop menus/icons for the software which comes with Wine (e.g. for ''winecfg'', ''winebrowser'', etc). This can be achieved by installing {{AUR|wine-installer}} or {{AUR|wine-installer-git}} meta-package (the latter has no additional dependencies), otherwise these instructions will add entries for these applications.<br />
<br />
First, install a Windows program using Wine to create the base menu. After the base menu is created, you can create the following files in {{ic|~/.local/share/applications/wine/}}:<br />
<br />
{{hc|wine-browsedrive.desktop|2=<br />
[Desktop Entry]<br />
Name=Browse C: Drive<br />
Comment=Browse your virtual C: drive<br />
Exec=wine winebrowser c:<br />
Terminal=false<br />
Type=Application<br />
Icon=folder-wine<br />
Categories=Wine;<br />
}}<br />
<br />
{{hc|wine-uninstaller.desktop|2=<br />
[Desktop Entry]<br />
Name=Uninstall Wine Software<br />
Comment=Uninstall Windows applications for Wine<br />
Exec=wine uninstaller<br />
Terminal=false<br />
Type=Application<br />
Icon=wine-uninstaller<br />
Categories=Wine;<br />
}}<br />
<br />
{{hc|wine-winecfg.desktop|2=<br />
[Desktop Entry]<br />
Name=Configure Wine<br />
Comment=Change application-specific and general Wine options<br />
Exec=winecfg<br />
Terminal=false<br />
Icon=wine-winecfg<br />
Type=Application<br />
Categories=Wine;<br />
}}<br />
<br />
And create the following file in {{ic|~/.config/menus/applications-merged/}}:<br />
<br />
{{hc|wine.menu|<nowiki><br />
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"<br />
"http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd"><br />
<Menu><br />
<Name>Applications</Name><br />
<Menu><br />
<Name>wine-wine</Name><br />
<Directory>wine-wine.directory</Directory><br />
<Include><br />
<Category>Wine</Category><br />
</Include><br />
</Menu><br />
</Menu><br />
</nowiki>}}<br />
<br />
If these settings produce a ugly/non-existent icon, it means that there are no icons for these launchers in the icon set that you have enabled. You should replace the icon settings with the explicit location of the icon that you want. Clicking the icon in the launcher's properties menu will have the same effect. A great icon set that supports these shortcuts is [http://www.gnome-look.org/content/show.php/GNOME-colors?content=82562 GNOME-colors].<br />
<br />
==== Removing menu entries ====<br />
<br />
Menu entries created by Wine are located in {{ic|~/.local/share/applications/wine/Programs/}}. Remove the program's ''.desktop'' entry to remove the application from the menu.<br />
<br />
In addition to remove unwanted extensions binding by Wine, execute the following commands (taken from the Wine website):<br />
<br />
$ rm ~/.local/share/mime/packages/x-wine*<br />
$ rm ~/.local/share/applications/wine-extension*<br />
$ rm ~/.local/share/icons/hicolor/*/*/application-x-wine-extension*<br />
$ rm ~/.local/share/mime/application/x-wine-extension*<br />
<br />
=== Appearance ===<br />
<br />
A similar to XP looking theme can be downloaded from [https://download.microsoft.com/download/e/a/9/ea9af5ae-b48e-473e-85fe-dcde7472e644/ZuneDesktopTheme.msi here]. To install it see [https://wiki.winehq.org/Wine_User%27s_Guide#Running_.msi_files here]. Lastly use ''winecfg'' to select it.<br />
Wine staging users may instead want to try enabling the option ''Enable GTK3 Theming'' under the Staging section of ''winecfg'' for a theme that matches the current GTK theme.<br />
<br />
=== Printing ===<br />
<br />
In order to use your installed printers (both local and network) with wine applications in ''win32 prefixes'' (e.g. MS Word), install the {{Pkg|lib32-libcups}} package, reboot wine (''wineboot'') and restart your wine application.<br />
<br />
=== Networking ===<br />
<br />
After installation, the {{pkg|lib32-gnutls}} package may need [[install]]ed for applications making TLS or HTTPS connections to work.<br />
<br />
For ICMP (ping), Wine may need the network access as described in the [https://wiki.winehq.org/FAQ#Failed_to_use_ICMP_.28network_ping.29.2C_this_requires_special_permissions WineHQ FAQ]:<br />
<br />
$ sudo setcap cap_net_raw+epi /usr/bin/wine-preloader<br />
<br />
If issues arise after this (such as an unhandled exception or privileged instruction), remove via:<br />
<br />
$ sudo setcap -r /usr/bin/wine-preloader<br />
<br />
== Usage ==<br />
<br />
{{Warning|Do not run or install Wine applications as root! See [https://wiki.winehq.org/FAQ#Should_I_run_Wine_as_root.3F Wine FAQ] for details.}}<br />
<br />
See [https://wiki.winehq.org/FAQ Wine FAQ] and [https://wiki.winehq.org/Wine_User%27s_Guide Wine User's Guide] for general information on Wine usage.<br />
<br />
See [https://appdb.winehq.org/ Wine Application Database (AppDB)] for information on running Windows applications in Wine.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Wineconsole ===<br />
<br />
Often you may need to run ''.exe'''s to patch game files, for example a widescreen mod for an old game, and running the ''.exe'' normally through Wine might yield nothing happening. In this case, you can open a terminal and run the following command:<br />
<br />
$ wineconsole cmd<br />
<br />
Then navigate to the directory and run the ''.exe'' file from there.<br />
<br />
=== Winetricks ===<br />
<br />
[https://wiki.winehq.org/Winetricks Winetricks] is a script to allow one to install base requirements needed to run Windows programs. Installable components include DirectX 9.x, MSXML (required by Microsoft Office 2007 and Internet Explorer), Visual Runtime libraries and many more.<br />
<br />
[[Install]] the {{pkg|winetricks}} package (or alternatively {{AUR|winetricks-git}}). Then run it with:<br />
$ winetricks<br />
<br />
For using GUI you should [[install]] the {{pkg|zenity}}.<br />
<br />
=== Performance ===<br />
<br />
==== CSMT ====<br />
<br />
CSMT is a technology used by Wine to use a separate thread for the OpenGL calls to improve performance noticeably. Since Wine 3.2, CSMT is enabled by default. However, CSMT support needs to be enabled manually for Wine versions lower than 3.2. For vanilla Wine run {{ic|wine regedit}} and set the DWORD value for ''HKEY_CURRENT_USER -> Software > Wine > Direct3D > csmt'' to 0x01 (enabled). For wine-staging run {{ic|winecfg}} and enable it in the staging tab.<br />
<br />
Note that CSMT may actually hurt performance for some applications - if this is the case, disable it by creating/setting the registry value to 0x00 (disabled).<br />
<br />
Further information:<br />
*[http://www.phoronix.com/forums/showthread.php?93967-Wine-s-Big-Command-Stream-D3D-Patch-Set-Updated/page3&s=7775d7c3d4fa698089d5492bb7b1a435 Phoronix Forum discussion] with the CSMT developer Stefan Dösinger<br />
<br />
==== Force OpenGL mode in games ====<br />
<br />
Some games might have an OpenGL mode which ''may'' perform better than their default DirectX mode. While the steps to enable OpenGL rendering is ''application specific'', many games accept the {{Ic|-opengl}} parameter.<br />
<br />
$ wine ''/path/to/3d_game.exe'' -opengl<br />
<br />
You should of course refer to your application's documentation and Wine's [http://appdb.winehq.org AppDB] for such application specific information.<br />
<br />
==== DXVK ====<br />
<br />
[https://github.com/doitsujin/dxvk DXVK] is a promising new implementation for DirectX 9 through 11 over Vulkan. This should allow for greater performance, and in some cases, even better compatibility. Battlefield 1 for example, only runs under DXVK. On the other hand, DXVK does not support all Wine games (yet).<br />
<br />
To use it, install {{aur|dxvk-bin}}. Then run the following command to activate it in your Wineprefix (by default {{ic|~/.wine}}):<br />
$ WINEPREFIX=''your-prefix'' setup_dxvk install<br />
<br />
{{Note|For Wine versions below 3.5 you need to configure Vulkan support manually, following the instructions at [https://github.com/roderickc/wine-vulkan GitHub]. {{Pkg|wine}} and {{Pkg|wine-staging}} work out of the box.}}<br />
<br />
{{Warning|DXVK overrides the DirectX 10 and 11 DLLs, which may be considered cheating in online multiplayer games, and may get your account '''banned'''. Use at your own risk!}}<br />
<br />
==== Gallium Nine ====<br />
<br />
With the open-source gallium-based drivers (mostly AMD cards) there is a [https://wiki.ixit.cz/d3d9 Gallium Direct3D state tracker] that aims to provide nearly-native performance for DirectX 9. In most cases it has less visual glitches than the upstream wine and doubles the performances. It consumes much less CPU time than CSMT.<br />
<br />
Install {{Pkg|wine-nine}} to use it. This is a standalone package that can be installed with any wine version. Use {{ic|wine ninewinecfg}} to check if it is enabled.<br />
<br />
=== Unregister existing Wine file associations ===<br />
<br />
By default, Wine takes over as the default application for a lot of formats. Some (e.g. {{ic|vbs}} or {{ic|chm}}) are Windows-specific, and opening them with Wine can be a convenience. However, having other formats (e.g. {{ic|gif}}, {{ic|jpeg}}, {{ic|txt}}, {{ic|js}}) open in Wine's bare-bones simulations of Internet Explorer and Notepad can be annoying.<br />
<br />
Wine's file associations are set in {{ic|~/.local/share/applications/}} as {{ic|wine-extension-''extension''.desktop}} files. Delete the files corresponding to the extensions you want to unregister. Or, to remove all wine extensions:<br />
<br />
$ rm -f ~/.local/share/applications/wine-extension*.desktop<br />
$ rm -f ~/.local/share/icons/hicolor/*/*/application-x-wine-extension*<br />
<br />
Next, remove the old cache:<br />
<br />
$ rm -f ~/.local/share/applications/mimeinfo.cache<br />
$ rm -f ~/.local/share/mime/packages/x-wine*<br />
$ rm -f ~/.local/share/mime/application/x-wine-extension*<br />
<br />
And, update the cache:<br />
<br />
$ update-desktop-database ~/.local/share/applications<br />
$ update-mime-database ~/.local/share/mime/<br />
<br />
Alternatively you can delete all wine related stuff:<br />
<br />
$ find ~/.local/share -name "*wine*" | xargs -I '{}' --no-run-if-empty rm -r '{}'<br />
<br />
And update the cache as above.<br />
<br />
Please note Wine will still create new file associations and even recreate the file associations if the application sets the file associations again.<br />
<br />
=== Prevent Wine from creating filetype associations ===<br />
{{Note|This has to be done for each WINEPREFIX which should not update file associations unless you opt to change {{ic|/usr/share/wine/wine.inf}} .}}<br />
This method prevents the creation of filetype associations but retains the creation of XDG .desktop files (that you might see e.g. in menus).<br />
<br />
If you want to stop wine from creating filetype associations via winecfg you have to uncheck the "Manage File Associations" checkbox under the Desktop Integration tab. See [https://wiki.winehq.org/FAQ#How_can_I_prevent_Wine_from_changing_the_filetype_associations_on_my_system_or_adding_unwanted_menu_entries.2Fdesktop_links.3F Wine FAQ]<br />
<br />
To make the same change via registry add the string {{ic|Enable}} with value {{ic|N}} under:<br />
<br />
HKEY_CURRENT_USER\Software\Wine\FileOpenAssociations<br />
<br />
''You might have to create the key {{ic|FileOpenAssociations}} first!''<br />
<br />
If you want to apply this by default for new WINEPREFIXES, edit {{ic|/usr/share/wine/wine.inf}} and add this line for example under the {{ic|[Services]}} section:<br />
HKCU,"Software\Wine\FileOpenAssociations","Enable",2,"N"<br />
<br />
To prevent a package upgrade from overriding the modified file, create a pacman hook to make the change automatically:<br />
<br />
{{hc|1=/etc/pacman.d/hooks/stop-wine-associations.hook|2=<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Upgrade<br />
Type = Path<br />
Target = usr/share/wine/wine.inf<br />
<br />
[Action]<br />
Description = Stopping Wine from hijacking file associations...<br />
When = PostTransaction<br />
<nowiki>Exec = /bin/sh -c '/usr/bin/grep -q "HKCU,\"Software\\\Wine\\\FileOpenAssociations\",\"Enable\",2,\"N\"" /usr/share/wine/wine.inf || /usr/bin/sed -i "s/\[Services\]/\[Services\]\nHKCU,\"Software\\\Wine\\\FileOpenAssociations\",\"Enable\",2,\"N\"/g" /usr/share/wine/wine.inf'</nowiki><br />
}}<br />
<br />
See [[Pacman#Hooks]]<br />
<br />
=== Execute Windows binaries with Wine implicitly ===<br />
<br />
The {{pkg|wine}} package installs a ''binfmt'' file which will allows you to run Windows programs directly, e.g. {{ic|''./myprogram.exe''}} will launch as if you had typed {{ic|wine ''./myprogram.exe''}}. Service starts by default on boot, if you haven't rebooted after installing Wine you can [[start]] {{ic|systemd-binfmt.service}} to use it right away.<br />
<br />
{{Note|Make sure the Windows binary is executable, otherwise the binary will not be executed: e.g. run {{ic|chmod +x ''windows-binary''}}.}}<br />
<br />
=== Dual Head with different resolutions ===<br />
<br />
If you have issues with dual-head setups and different display resolutions you are probably missing {{Pkg|lib32-libxrandr}}.<br />
<br />
Also installing {{Pkg|lib32-libxinerama}} might fix dual-head issues with wine (for example, unclickable buttons and menus of application in the right most or bottom most monitor, not redrawable interface of application in that zone, dragging mouse cursor state stucked after leaving application area).<br />
<br />
=== Burning optical media ===<br />
<br />
To burn CDs or DVDs, you will need to load the {{ic|sg}} [[kernel module]].<br />
<br />
=== Proper mounting of optical media images ===<br />
<br />
Some applications will check for the optical media to be in drive. They may check for data only, in which case it might be enough to configure the corresponding path as being a CD-ROM drive in ''winecfg''.<br />
However, other applications will look for a media name and/or a serial number, in which case the image has to be mounted with these special properties.<br />
<br />
Some virtual drive tools do not handle these metadata, like fuse-based virtual drives (Acetoneiso for instance). CDEmu will handle it correctly.<br />
<br />
=== Show FPS overlay in games ===<br />
<br />
Wine features an embedded FPS monitor which works for all graphical applications if the environment variable {{ic|1=WINEDEBUG=fps}} is set. This will output the framerate to stdout. You can display the FPS on top of the window thanks to {{ic|osd_cat}} from the {{pkg|xosd}} package. See [https://gist.github.com/anonymous/844aefd70bb50bf72b35 winefps.sh] for a helper script.<br />
<br />
=== Running Wine under a separate user account ===<br />
<br />
It may be desirable to run Wine under a specifically created user account in order to reduce concerns about Windows applications having access to your home directory.<br />
<br />
First, create a [[user account]] for Wine:<br />
<br />
# useradd -m -s /bin/bash wineuser<br />
<br />
Now switch to another TTY and start your X WM or DE as you normally would or keep reading...<br />
<br />
{{Note|The following approach only works when enabling root for Xorg. See [[Xorg#Rootless Xorg]] for more information.}}<br />
<br />
Afterwards, in order to open Wine applications using this new user account you need to add the new user to the X server permissions list:<br />
<br />
$ xhost +SI:localuser:wineuser<br />
<br />
Finally, you can run Wine via the following command, which uses {{ic|env}} to launch Wine with the environment variables it expects:<br />
<br />
$ sudo -u wineuser env HOME=/home/wineuser USER=wineuser USERNAME=wineuser LOGNAME=wineuser wine ''arguments''<br />
<br />
It is possible to automate the process of running Windows applications with Wine via this method by using a shell script as follows:<br />
{{hc|1=/usr/local/bin/runaswine|2=<br />
#!/bin/bash<br />
xhost +SI:localuser:wineuser<br />
sudo -u wineuser env HOME=/home/wineuser USER=wineuser USERNAME=wineuser LOGNAME=wineuser wine "$@"}}<br />
<br />
Wine applications can then be launched via:<br />
<br />
$ runaswine ''"C:\path\to\application.exe"''<br />
<br />
In order to not be asked for a password each time Wine is run as another user the following entry can be added to the sudoers file: {{ic|1=''mainuser'' ALL=(wineuser) NOPASSWD: ALL}}. See [[Sudo#Configuration]] for more information.<br />
<br />
It is recommended to run {{ic|winecfg}} as the Wine user and remove all bindings for directories outside the home directory of the Wine user in the "Desktop Integration" section of the configuration window so no program run with Wine has read access to any file outside the special user's home directory.<br />
<br />
Keep in mind that audio will probably be non-functional in Wine programs which are run this way if [[PulseAudio]] is used. See [[PulseAudio/Examples#Allowing multiple users to use PulseAudio at the same time]] for information about allowing the Wine user to access the PulseAudio daemon of the principal user.<br />
<br />
=== Temp directory on tmpfs ===<br />
<br />
To prevent Wine from writing its temporary files to a physical disk, one can define an alternative location, like ''tmpfs''. Remove Wine's default directory for temporary files and creating a symlink:<br />
<br />
$ rm -r ~/.wine/drive_c/users/$USER/Temp<br />
$ ln -s /tmp/ ~/.wine/drive_c/users/$USER/Temp<br />
<br />
=== Prevent installing Mono/Gecko ===<br />
If Gecko and/or Mono are not present on the system nor in the Wine prefix, Wine will prompt to download them from the internet. If you do not need Gecko and/or Mono, you might want to disable this dialog, by setting the {{ic|WINEDLLOVERRIDES}} [[environment variable]] to {{ic|1=mscoree=d;mshtml=d}}.<br />
<br />
=== Vulkan ===<br />
<br />
Vulkan support is included, since Wine 3.3. The default Wine Vulkan ICD loader works fine for most applications, but does not support advanced features, like Vulkan layers. To use these features, you have to install the official Vulkan SDK, see step 2-4 on the original Vulkan patches author's [https://github.com/roderickc/wine-vulkan GitHub page].<br />
<br />
{{Note|The Wine ICD loader was added in Wine 3.5, you need to install the official Vulkan SDK to use Vulkan in Wine 3.3 and 3.4}}<br />
<br />
=== Remove Wine file bindings ===<br />
<br />
For security reasons it may be useful to remove the preinstalled Wine bindings so Windows applications cannot be launched directly from a file manager or from the browser (Firefox offers to open EXE files directly with Wine!).<br />
If you want to do this, you may add the following to the {{ic|1= [options]}} section in {{ic|1= /etc/pacman.conf}}<br />
<br />
NoExtract = usr/lib/binfmt.d/wine.conf<br />
NoExtract = usr/share/applications/wine.desktop<br />
<br />
== See also ==<br />
<br />
* [https://www.winehq.org/ Wine Homepage]<br />
* [https://wiki.winehq.org/ Wine Wiki]<br />
* [https://appdb.winehq.org/ Wine Application Database (AppDB)] - Information about running specific Windows applications (Known issues, ratings, guides, etc tailored to specific applications)<br />
* [https://forum.winehq.org/ Wine Forums] - A great place to ask questions ''after'' you have looked through the FAQ and AppDB<br />
* [https://wiki.gentoo.org/wiki/Wine Wine - Gentoo Wiki]</div>Jwh7https://wiki.archlinux.org/index.php?title=XMLTV&diff=636494XMLTV2020-09-25T12:25:55Z<p>Jwh7: add actual AUR link</p>
<hr />
<div>[[Category:Television]]<br />
{{Style|FAQ-like format, does not fit with [[Help:Style]]}}<br />
[http://wiki.xmltv.org/index.php/Main_Page/ XMLTV] ({{AUR|xmltv}}) is a set of utilities to download TV listings and format them in XML.<br />
<br />
==What does XMLTV actually *do* ?==<br />
<br />
Any good PVR system needs to know when to record. Systems like VideoPlus in the UK, where numbers encode start and stop times, have made programming easier, but it's much easier to just look at an EPG and click on the programme you want to record.<br />
<br />
However, there is no central system for acquiring TV programme data, at present, so that's where XMLTV comes in. XMLTV's job is to take program data off the internet and convert it to a standard format for PVRs like MythTV and FreeVO.<br />
<br />
==Why XMLTV is so problematic?==<br />
<br />
The problem with XMLTV is it is grabbing data from places that were not really designed to supply it. It kind of "screen scrapes" - it looks at a web page containing TV information like this and tries to rip the text off it and convert it into an easy to use format. Things can go wrong with this ; if the website decides it's going to reformat its text, then it will cease to work properly or indeed at all.<br />
<br />
==What about the DVB-T EPG ?==<br />
<br />
DVB-T, aka Freeview here, has programme guide information embedded in it ; any UK Freeview set top box has an EPG. It seems to be problematic getting this to work in MythTV, as it is currently "in development". When it does work, this will make it much easier as XMLTV can be abandoned, for DVB-T anyway (still needed for analogue, which is sound and video only)<br />
<br />
One downside of the DVB-T EPG is that it only goes 7 days into the future, whereas XMLTV does 14 days. This is useful if you want to record when you are on holiday.<br />
<br />
==Compilation==<br />
<br />
If your grabber is not available in the package in ''community'', you have to try and compile xmltv yourself. You can choose between two ways of obtaining a self compiled xmltv installation. You can use [[ABS]] and edit the [[PKGBUILD]] to make a package or compile it by hand.<br />
<br />
===Make a package===<br />
<br />
Refer to the wiki page about the Arch Build System (ABS) on how to use it. Copy the directory xmltv to your build directory. Now you have to check, why your grabber is not available. Extract the source and run Makefile.PL:<br />
<br />
makepkg -e<br />
cd src/"PKGNAME"<br />
perl Makefile.PL<br />
<br />
You will be prompted for every grabber. The script will tell you, which grabber is not supported and why. You will have to install additional dependencies then. For the grabber "tv_grab_eu_epgdata" for example you will have to install perl-datetime-format-strptime from [[AUR]]. Add these dependencies in the PKGBUILD and run makepkg.<br />
<br />
==Configuring XMLTV==<br />
<br />
Next we need to configure XMLTV. To do this run<br />
<br />
tv_grab_uk_rt --configure<br />
<br />
Now, for this grabber, you can individually select whether or not you want each channel. To select every channel (it's quicker to edit the configuration file in a text editor), type:<br />
<br />
all<br />
<br />
And it will configure itself to download every single channel it can.<br />
<br />
==Checking XMLTV actually works==<br />
<br />
To check it, simply run it.<br />
<br />
tv_grab_uk_rt<br />
<br />
If all is well, it should churn out reams and reams of channel programme data. It should look like this<br />
<br />
<programme start="20070330035500 +0100" stop="20070330042000 +0100" channel="abc1.disney.com"><br />
<title>8 Simple Rules for Dating My Teenage Daughter</title><br />
<sub-title>Rory's Got a Girlfriend</sub-title><br />
<desc lang="en">Sitcom in which a father has his hands full when his wife returns to work and he is left to supervise their teenage daughters. Paul has to face the fact that his son wants to start dating girls, and Kerry envies her sister.</desc><br />
<credits><br />
<actor>John Ritter</actor><br />
<actor>Katey Sagal</actor><br />
<br />
except there will be pages of it.</div>Jwh7https://wiki.archlinux.org/index.php?title=EFISTUB&diff=635710EFISTUB2020-09-18T18:31:53Z<p>Jwh7: /* Using UEFI directly */ clarify some unified kernel image info</p>
<hr />
<div>[[Category:Boot loaders]]<br />
[[es:EFISTUB]]<br />
[[ja:EFISTUB]]<br />
[[pt:EFISTUB]]<br />
[[ru:EFISTUB]]<br />
{{Related articles start}}<br />
{{Related|Arch boot process}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related articles end}}<br />
<br />
The Linux kernel supports EFISTUB booting which allows [[EFI]] firmware to load the kernel as an EFI executable. The option is enabled by default on Arch Linux kernels, or if compiling the kernel one can activate it by setting {{ic|1=CONFIG_EFI_STUB=y}} in the Kernel configuration. See [https://www.kernel.org/doc/html/latest/admin-guide/efi-stub.html The EFI Boot Stub] for more information.<br />
<br />
With EFISTUB a kernel can be booted directly by a UEFI motherboard or indirectly using a [[boot loader]]. Using a boot loader is recommended if you have multiple kernel/initramfs pairs and your motherboard's UEFI boot menu is not easy to use.<br />
<br />
== Preparing for EFISTUB ==<br />
<br />
First, you must create an [[EFI system partition]] and choose how it is mounted. See [[EFI system partition#Mount the partition]] for all available ESP mounting options.<br />
<br />
{{Tip|<br />
* [[pacman]] will directly update the kernel that the EFI firmware will read if you mount the ESP to {{ic|/boot}}. <br />
* You can keep the kernel and initramfs off of the ESP if you use a boot manager which has a file system driver for the partition where they reside, e.g. [[rEFInd]].<br />
}}<br />
<br />
== Booting EFISTUB ==<br />
<br />
{{Note|Linux Kernel EFISTUB initramfs path should be relative to the EFI System Partition's root and use backslashes (in accordance with EFI standards). For example, if the initramfs is located in {{ic|''esp''/EFI/arch/initramfs-linux.img}}, the corresponding UEFI formatted line should be {{ic|1=initrd=\EFI\arch\initramfs-linux.img}}. In the following examples we will assume that everything is under {{ic|''esp''/}}.}}<br />
<br />
=== Using a boot manager ===<br />
<br />
There are several UEFI boot managers which can provide additional options or simplify the process of UEFI booting - especially if you have multiple kernels/operating systems. See [[Arch boot process#Boot loader]] for more information.<br />
<br />
=== Using UEFI directly ===<br />
<br />
UEFI is designed to remove the need for an intermediate bootloader such as [[GRUB]]. If your motherboard has a good UEFI implementation, it is possible to embed the kernel parameters within a UEFI boot entry and for the motherboard to boot Arch directly. You can use [[efibootmgr]] or UEFI Shell v2 to modify your motherboard's boot entries.<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* Outdated UEFI implementations may have compatibility issues with the Linux kernel. If there is a newer version of your UEFI with bug fixes, consider flashing it with the manufacturer's recommended tool.<br />
* Some firmwares do not pass command line parameters from the boot entries in NVRAM to the EFI binaries.[https://bbs.archlinux.org/viewtopic.php?id=178154] In that case, the kernel and parameters can be combined into a [[unified kernel image]], then create a boot entry with an [[#efibootmgr_with_.efi_file|.efi file]].<br />
}}<br />
<br />
==== efibootmgr ====<br />
<br />
To create a boot entry with ''efibootmgr'' that will load the kernel:<br />
<br />
# efibootmgr --disk ''/dev/sdX'' --part ''Y'' --create --label "Arch Linux" --loader /vmlinuz-linux --unicode 'root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw initrd=\initramfs-linux.img' --verbose<br />
<br />
or create a boot entry with ''efibootmgr'' and hibernation on swap partition:<br />
<br />
# efibootmgr --disk ''/dev/sdX'' --part ''Y'' --create --label "Arch Linux" --loader /vmlinuz-linux --unicode 'root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' resume=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw initrd=\initramfs-linux.img' --verbose<br />
<br />
Where {{ic|''/dev/sdX''}} and {{ic|''Y''}} are the drive and partition number where the ESP is located. Change the {{ic|1=root=}} and {{ic|1=resume=}} parameters to reflect your Linux root and swap partitions, see [[kernel parameters#Parameter list|kernel parameters]] for supported device name formats, and [[persistent block device naming]] for how to obtain the corresponding value. If omitted, then the first partition on {{ic|''/dev/sda''}} is used as the ESP.<br />
<br />
Note that the {{ic|-u}}/{{ic|--unicode}} argument in quotes is just the list of [[kernel parameters]], so you may need to add additional parameters (e.g. for [[Suspend and hibernate#Required kernel parameters|suspend to disk]] or [[microcode]]).<br />
<br />
After adding the boot entry, you can verify the entry was added properly with:<br />
<br />
# efibootmgr --verbose<br />
<br />
To set the boot order:<br />
<br />
# efibootmgr --bootorder ''XXXX'',''XXXX'' --verbose<br />
<br />
Where ''XXXX'' is the number that appears in the output of ''efibootmgr'' command against each entry.<br />
<br />
{{Tip|1=<nowiki></nowiki><br />
* It is convenient to save the command to create the boot entry in a shell script, which makes it easier to modify, for example when changing kernel parameters. In doing so, consider automating the deletion of old boot entries, as ''efibootmgr'' currently [https://github.com/rhboot/efibootmgr/issues/49 does not support editing existing entries].<br />
* The forum post titled [https://bbs.archlinux.org/viewtopic.php?pid=1090040#p1090040 The linux kernel with build in bootloader?] might also be of interest.<br />
}}<br />
<br />
==== efibootmgr with .efi file ====<br />
<br />
If using {{AUR|cryptboot}} and {{AUR|sbupdate-git}} to generate your own keys for [[Secure Boot#Using_your_own_keys|Secure Boot]] and sign the initramfs and kernel then create a bootable ''.efi'' image, ''efibootmgr'' can be used directly to boot the ''.efi'' file:<br />
<br />
# efibootmgr --create --disk /dev/sdX --part ''partition_number'' --label "''label''" --loader "EFI\''folder''\''file''.efi" --verbose<br />
<br />
See {{man|8|efibootmgr}} for an explanation of the options. To include microcode in a [[unified kernel image]], concatenate it with [[Microcode#Unified_kernel_images|the initramfs and use the resultant image]] with objtool.<br />
<br />
==== UEFI Shell ====<br />
<br />
Some UEFI implementations make it difficult to modify the NVRAM successfully using ''efibootmgr''. If ''efibootmgr'' cannot successfully create an entry, you can use the [[UEFI#bcfg|bcfg]] command in UEFI Shell v2 (i.e., from the [https://www.archlinux.org/download/ Arch Linux live iso]).<br />
<br />
First, find out the device number where your [[ESP]] resides with:<br />
<br />
Shell> map<br />
<br />
In this example, {{ic|1}} is used as the device number. To list the contents of the [[ESP]]:<br />
<br />
Shell> ls fs1:<br />
<br />
To view the current boot entries:<br />
<br />
Shell> bcfg boot dump<br />
<br />
To add an entry for your kernel, use:<br />
<br />
Shell> bcfg boot add ''N'' fs1:\vmlinuz-linux "Arch Linux"<br />
<br />
Where {{ic|''N''}} is the location where the entry will be added in the boot menu. 0 is the first menu item. Menu items already existing will be shifted in the menu without being discarded.<br />
<br />
Add the necessary kernel options by creating a file on your ESP:<br />
<br />
Shell> edit fs1:\options.txt<br />
<br />
In the file, add the boot line. For example:<br />
<br />
root=/dev/sda2 ro initrd=\initramfs-linux.img<br />
<br />
{{Note|Add extra spaces in the beginning of the line in the file. There is a [[Wikipedia:Byte order mark|byte order mark]] at the beginning of the line that will squash any character next to it which will cause an error when booting.}}<br />
<br />
Press {{ic|F2}} to save and then {{ic|F3}} to exit.<br />
<br />
Add these options to your previous entry:<br />
<br />
Shell> bcfg boot -opt ''N'' fs1:\options.txt<br />
<br />
Repeat this process for any additional entries.<br />
<br />
To remove a previously added item do:<br />
<br />
Shell> bcfg boot rm ''N''<br />
<br />
==== More tools ====<br />
<br />
Some of the tools above, and more, are briefly discussed in [[rEFInd#Tools]].<br />
<br />
==== Using a startup.nsh script ====<br />
<br />
Some UEFI implementations do not retain EFI variables between cold boots (e.g. [[VirtualBox]] before version 6.1) and anything set through the UEFI firmware interface is lost on poweroff.<br />
<br />
The [http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf UEFI Shell Specification 2.0] establishes that a script called {{ic|startup.nsh}} at the root of the ESP partition will always be interpreted and can contain arbitrary instructions; among those you can set a bootloading line. Make sure you mount the ESP partition on {{ic|/boot}} and create a {{ic|startup.nsh}} script that contains a kernel bootloading line. For example:<br />
<br />
vmlinuz-linux rw root=/dev/sd''X'' [rootfs=''myfs''] [rootflags=''myrootflags''] \<br />
[kernel.flag=''foo''] [''mymodule''.flag=''bar''] \<br />
[initrd=\intel-ucode.img] initrd=\initramfs-linux.img<br />
<br />
This method will work with almost all UEFI firmware versions you may encounter in real hardware, you can use it as last resort. '''The script must be a single long line.''' Sections in brackets are optional and given only as a guide. Shell style linebreaks are for visual clarification only. FAT filesystems use the backslash as path separator and in this case, the backslash declares the initramfs is located in the root of the ESP partition. Only Intel microcode is loaded in the booting parameters line; AMD microcode is read from disk later during the boot process; this is done automatically by the kernel.<br />
<br />
=== Using UEFI Shell ===<br />
<br />
If you do not want to create a permanent boot entry it is possible to launch the kernel from UEFI Shell as if it is a normal UEFI application:<br />
<br />
> fs0:<br />
> \vmlinuz-linux root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 rw initrd=\initramfs-linux.img<br />
<br />
In this case, the kernel parameters are passed as normal parameters to the launched EFISTUB kernel file.<br />
<br />
To avoid needing to remember all of your kernel parameters every time, you can save the executable command to a shell script such as {{ic|archlinux.nsh}} on your UEFI System Partition, then run it with:<br />
<br />
> fs0:<br />
> archlinux<br />
<br />
== Troubleshooting ==<br />
<br />
=== Cannot create a new boot entry with efibootmgr ===<br />
<br />
Some kernel and ''efibootmgr'' version combinations might refuse to create new boot entries. This could be due to lack of free space in the NVRAM. You can try deleting any EFI dump files:<br />
<br />
# rm /sys/firmware/efi/efivars/dump-*<br />
<br />
Or, as a last resort, boot with the {{ic|efi_no_storage_paranoia}} kernel parameter. You can also try to [[downgrade]] your ''efibootmgr'' install to version 0.11.0. This version works with Linux version 4.0.6. See the bug discussion {{Bug|34641}}, in particular the [https://bugs.archlinux.org/task/34641#comment111365 closing comment], for more information.<br />
<br />
=== Newly created boot entries are removed ===<br />
<br />
Some motherboards may remove boot entries after a couple of boots. This could be due to lack of free space in the NVRAM. To prevent this from occurring, it may help to reduce the amount of Linux boot entries being added by ''efibootmgr'' by minimizing your entry creation process, as well as reducing the amount of automatic drive boot entries by the [[Wikipedia:Unified Extensible Firmware Interface#CSM booting|Compatibility Support Module (CSM)]] by disabling it from your UEFI settings.<br />
<br />
== See also ==<br />
<br />
* [https://www.kernel.org/doc/html/latest/admin-guide/efi-stub.html Linux Kernel Documentation on EFISTUB]<br />
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=commitdiff;h=291f36325f9f252bd76ef5f603995f37e453fc60;hp=55839d515495e766605d7aaabd9c2758370a8d27 Linux Kernel EFISTUB Git Commit]<br />
* [http://www.rodsbooks.com/efi-bootloaders/efistub.html Rod Smith's page on EFISTUB]</div>Jwh7https://wiki.archlinux.org/index.php?title=CUPS&diff=635046CUPS2020-09-13T01:08:11Z<p>Jwh7: /* Installation */ Clarify the 'service' versus 'socket' methods</p>
<hr />
<div>[[Category:Printers]]<br />
[[Category:Servers]]<br />
[[cs:CUPS]]<br />
[[de:CUPS]]<br />
[[es:CUPS]]<br />
[[fr:CUPS]]<br />
[[it:CUPS]]<br />
[[ja:CUPS]]<br />
[[pl:CUPS]]<br />
[[ru:CUPS]]<br />
[[th:CUPS]]<br />
[[zh-hans:CUPS]]<br />
[[zh-hant:CUPS]]<br />
{{Related articles start}}<br />
{{Related|CUPS/Printer sharing}}<br />
{{Related|CUPS/Printer-specific problems}}<br />
{{Related|CUPS/Troubleshooting}}<br />
{{Related|Samba}}<br />
{{Related|LPRng}}<br />
{{Related articles end}}<br />
<br />
[https://www.cups.org/ CUPS] is the standards-based, open source printing system currently developed by Apple Inc. for macOS® and other UNIX®-like operating systems.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|cups}} package. Then [[enable]] and [[start]] {{ic|org.cups.cupsd.service}} or alternatively use [[#Socket_activation|socket activation]] to only start CUPS when a program wants to use the service.<br />
<br />
If you intend to "print" into a PDF document, also install the {{pkg|cups-pdf}} package. By default, pdf files are stored in {{ic|/var/spool/cups-pdf/''username''/}}. The location can be changed in {{ic|/etc/cups/cups-pdf.conf}}.<br />
<br />
=== Socket activation ===<br />
<br />
{{Pkg|cups}} provides a {{ic|org.cups.cupsd.socket}} unit. If {{ic|org.cups.cupsd.socket}} is [[enable]]d (and {{ic|org.cups.cupsd.service}} is [[disable]]d), systemd will not start CUPS immediately; it will just listen to the appropriate sockets. Then, whenever a program attempts to connect to one of these CUPS sockets, systemd will start {{ic|org.cups.cupsd.service}} and transparently hand over control of these ports to the CUPS process.<br />
<br />
=== Print steps ===<br />
it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
== Connection Interfaces ==<br />
<br />
Additional steps for printer detection are listed below for various connection interfaces.<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* CUPS helper programs are run using the {{ic|cups}} user and group. This allows the helper programs to access printer devices and read config files in {{ic|/etc/cups/}}, which are owned by the {{ic|cups}} group.<br />
* Prior to {{Pkg|cups}} 2.2.6-2, the {{ic|lp}} group [https://github.com/archlinux/svntogit-packages/commit/a209bf21797a239c7ddb4614f0266ba1e5238622 was used instead]. After the upgrade, the files in {{ic|/etc/cups}} should be owned by the {{ic|cups}} group and {{ic|User 209}} and {{ic|Group 209}} set in {{ic|/etc/cups/cups-files.conf}}.<br />
}}<br />
<br />
=== USB ===<br />
<br />
To see if your USB printer is detected:<br />
<br />
{{hc|$ lsusb|<br />
(...)<br />
Bus 001 Device 007: ID 03f0:1004 Hewlett-Packard DeskJet 970c/970cse<br />
}}<br />
<br />
=== Parallel port ===<br />
<br />
To use a parallel port printer, the {{ic|lp}}, {{ic|parport}} and {{ic|parport_pc}} [[kernel modules]] are required.<br />
<br />
{{hc|$ dmesg {{!}} grep -i parport|<br />
parport0: Printer, Hewlett-Packard HP LaserJet 2100 Series<br />
lp0: using parport0 (polling)<br />
}}<br />
<br />
=== Network ===<br />
<br />
To discover or share printers using DNS-SD/mDNS, setup [[Avahi#Hostname_resolution|.local hostname resolution]] with [[Avahi]] and [[restart]] {{ic|org.cups.cupsd.service}}.<br />
<br />
{{Note|DNS-SD is only supported when using [[Avahi]]. CUPS does not support using [[systemd-resolved]] for DNS-SD, see [https://github.com/apple/cups/issues/5452 CUPS issue 5452].}}<br />
<br />
To share printers with [[Samba]], e.g. if the system is to be a print server for Windows clients, the {{Pkg|samba}} package will be required.<br />
<br />
== Printer Drivers ==<br />
<br />
{{Expansion|CUPS is planning to drop PPD and driver support ([https://github.com/apple/cups/issues/5271 CUPS issue 5271]), instead relying entirely on IPP Everywhere. Explain what is/will be handled by {{Pkg|cups}} and what by {{Pkg|cups-filters}} and/or other software.|section=CUPS printer drivers and backends are deprecated}}<br />
<br />
<br />
The drivers for a printer may come from any of the sources shown below. See [[CUPS/Printer-specific problems]] for an incomplete list of drivers that others have managed to get working.<br />
<br />
To drive a printer, CUPS needs a PPD file and, for most printers, some [https://www.cups.org/doc/man-filter.html filters].<br />
For details on how CUPS uses PPDs and filters, see [https://www.cups.org/doc/postscript-driver.html].<br />
<br />
The [http://www.openprinting.org/printers OpenPrinting Printer List] provides driver recommendations for many printers. It also supplies PPD files for each printer, but most are available through [[#Foomatic|foomatic]] or the recommended driver package.<br />
<br />
When a PPD file is provided to CUPS, the CUPS server will regenerate the PPD files and save them in {{ic|/etc/cups/ppd/}}.<br />
<br />
=== CUPS ===<br />
<br />
CUPS includes support for [[wikipedia:AirPrint|AirPrint]] and [http://www.pwg.org/ipp/everywhere.html IPP Everywhere] printers.<br />
<br />
=== OpenPrinting CUPS filters ===<br />
<br />
The Linux Foundation's OpenPrinting workgroup provides [https://wiki.linuxfoundation.org/openprinting/cups-filters cups-filters]. Those are backends, filters, and other binaries that were once part of CUPS but are no longer maintained by Apple. They are available in the {{Pkg|cups-filters}} package that is a dependency of {{Pkg|cups}}.<br />
<br />
Non-PDF printers require {{pkg|ghostscript}} to be installed. For PostScript printers {{Pkg|gsfonts}} may also be required.<br />
<br />
=== Foomatic ===<br />
<br />
The Linux Foundation's OpenPrinting workgroup's [https://wiki.linuxfoundation.org/openprinting/database/foomatic foomatic] provides PPDs for many printer drivers, both free and nonfree. For more information about what foomatic does, see [http://www.openprinting.org/download/kpfeifle/LinuxKongress2002/Tutorial/IV.Foomatic-Developer/IV.tutorial-handout-foomatic-development.html Foomatic from the Developer's View].<br />
<br />
To use foomatic, install {{pkg|foomatic-db-engine}} and at least one of:<br />
<br />
* {{pkg|foomatic-db}} - a collection of XML files used by foomatic-db-engine to generate PPD files.<br />
* {{pkg|foomatic-db-ppds}} - prebuilt PPD files.<br />
* {{Pkg|foomatic-db-nonfree}} - a collection of XML files from printer manufacturers under non-free licenses used by foomatic-db-engine to generate PPD files.<br />
* {{pkg|foomatic-db-nonfree-ppds}} - prebuilt PPD files under non-free licenses.<br />
<br />
The foomatic PPDs may require additional filters, such as {{aur|min12xxw}}.<br />
<br />
=== Gutenprint ===<br />
<br />
The [http://gimp-print.sourceforge.net/ Gutenprint project] provides drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with CUPS and [[GIMP]].<br />
<br />
Install {{Pkg|gutenprint}} and {{Pkg|foomatic-db-gutenprint-ppds}}.<br />
<br />
{{Note|When the Gutenprint packages get updated, the printers using Gutenprint drivers will stop working until you run {{ic|cups-genppdupdate}} as root and restart CUPS. ''cups-genppdupdate'' will update the PPD files of the configured printers, see {{man|8|cups-genppdupdate}} for more details.}}<br />
<br />
=== Manufacturer-specific drivers ===<br />
<br />
Many printer manufacturers supply their own Linux drivers. These are often available in the official Arch repositories or in the [[AUR]].<br />
<br />
Some of those drivers are described in more detail in [[CUPS/Printer-specific problems]].<br />
<br />
== Printer URI ==<br />
<br />
Listed below are additional steps to manually generate the URI if required. Some printers or drivers may need a special URI as described in [[CUPS/Printer-specific problems]].<br />
<br />
=== USB ===<br />
<br />
CUPS should be able to automatically generate a URI for USB printers, for example {{ic|1=usb://HP/DESKJET%20940C?serial=CN16E6C364BH}}.<br />
<br />
If it does not, see [[CUPS/Troubleshooting#USB printers]] for troubleshooting steps.<br />
<br />
=== Parallel port ===<br />
<br />
The URI should be of the form {{ic|parallel:''device''}}. For instance, if the printer is connected on {{ic|/dev/lp0}}, use {{ic|parallel:/dev/lp0}}.<br />
If you are using a USB to parallel port adapter, use {{ic|parallel:/dev/usb/lp0}} as the printer URI.<br />
<br />
=== Network ===<br />
<br />
If you have set up [[Avahi]] as in [[#Network]], CUPS should detect the printer URI. You can also use {{ic|avahi-discover}} to find the name of your printer and its address (for instance, {{ic|BRN30055C6B4C7A.local/10.10.0.155:631}}).<br />
<br />
The URI can also be generated manually, without using [[Avahi]].<br />
A list of the available URI schemes for networked printers is available in the [https://www.cups.org/doc/network.html#PROTOCOLS CUPS documentation]. As exact details of the URIs differ between printers, check either the manual of the printer or [[CUPS/Printer-specific problems]].<br />
<br />
The URI for printers on [[SMB]] shares is described in the {{man|8|smbspool}} man page.<br />
<br />
{{Note|Any special characters in the printer URIs need to be appropriately quoted, or, if your Windows printer name or user passwords have spaces, CUPS will throw a {{ic|lpadmin: Bad device-uri}} error.<br />
For example, {{ic|smb://BEN-DESKTOP/HP Color LaserJet CP1510 series PCL6}} becomes {{ic|smb://BEN-DESKTOP/HP%20Color%20LaserJet%20CP1510%20series%20PCL6}}.<br />
<br />
This result string can be obtained by running the following command:<br />
<br />
$ python -c 'from urllib.parse import quote; print("smb://" + quote("BEN-DESKTOP/HP Color LaserJet CP1510 series PCL6"))'<br />
<br />
}}<br />
<br />
Remote CUPS print servers can be accessed through a URI of the form {{ic|ipp://''hostname'':631/printers/''queue_name''}}. See [[CUPS/Printer sharing#Printer sharing]] for details on setting up the remote print server.<br />
<br />
See [[CUPS/Troubleshooting#Networking issues]] for additional issues and solutions.<br />
<br />
{{Warning|1=Avoid configuring both the server and the client with a printer filter - either the print queue on the client or the server should be 'raw'. This avoids sending a print job through the filters for a printer twice, which can cause problems such as shared printer works locally but remote machine fails to print([https://bbs.archlinux.org/viewtopic.php?pid=1589908#p1589908]). See [[#Usage]] for an example of setting a print queue to 'raw'.}}<br />
<br />
== Usage ==<br />
<br />
CUPS can be fully controlled using the lp* and cups* CLI tools.<br />
Alternatively, the [[#Web interface]] or one of several [[#GUI applications]] can be used.<br />
<br />
* The ''queue'' name is a short but descriptive name used on the system to identify the queue. This name should not contain spaces or any special characters. For instance, a print queue corresponding to a HP LaserJet 5P could be named "hpljet5p". More than one queue can be associated with each physical printer.<br />
* The ''location'' is a description of the printer's physical location (for instance "bedroom", or "kitchen"). This is to aid in maintaining several printers.<br />
* The ''description'' is a full description of the print queue. A common use is a full printer name (like "HP LaserJet 5P").<br />
<br />
=== CLI tools ===<br />
<br />
See [http://localhost:631/help/options.html CUPS local documentation] for more tips on the command-line tools.<br />
<br />
{{Note|Command-line switches cannot be grouped}}<br />
<br />
{{Style|Nonstandard use of definition lists, comments in command line.}}<br />
<br />
;List the devices<br />
# lpinfo -v<br />
$ /usr/lib/cups/backend/snmp ''ip_address'' # Use SNMP to find a URI<br />
<br />
;List the models<br />
$ lpinfo -m<br />
<br />
;Add a new queue<br />
# lpadmin -p ''queue_name'' -E -v ''uri'' -m ''model''<br />
<br />
The ''queue_name'' is up to you.<br />
Examples:<br />
# lpadmin -p HP_DESKJET_940C -E -v "usb://HP/DESKJET%20940C?serial=CN16E6C364BH" -m drv:///HP/hp-deskjet_940c.ppd.gz<br />
# lpadmin -p AirPrint -E -v "ipp://10.0.1.25/ipp/print" -m everywhere # Driverless queue (Apple AirPrint or IPP Everywhere)<br />
# lpadmin -p SHARED_PRINTER -m raw # Raw queue; no PPD or filter<br />
# lpadmin -p Test_Printer -E -v "ipp://10.0.1.3/ipp/print" -m pxlmono.ppd # Specifying a PPD instead of a model<br />
<br />
{{Note|When specifying the PPD, use just the file name and not the full path (for instance, {{ic|pxlmono.ppd}} instead of {{ic|/usr/share/ppd/cupsfilters/pxlmono.ppd}}). Alternatively, the full path can be used with the {{ic|-P}} command line switch.}}<br />
<br />
;Set the default printer<br />
$ lpoptions -d ''queue_name''<br />
<br />
;Change the options<br />
$ lpoptions -p ''queue_name'' -l # List the options<br />
$ lpoptions -p ''queue_name'' -o ''option''=''value'' # Set an option<br />
<br />
Example:<br />
$ lpoptions -p HP_DESKJET_940C -o PageSize=A4<br />
<br />
;Check the status<br />
$ lpstat -s<br />
$ lpstat -p ''queue_name''<br />
<br />
;Deactivate a printer<br />
# cupsdisable ''queue_name''<br />
<br />
;Activate a printer<br />
# cupsenable ''queue_name''<br />
<br />
;Set the printer to accept jobs<br />
# cupsaccept ''queue_name''<br />
<br />
;Remove a printer<br />
First set it to reject all incoming entries:<br />
# cupsreject ''queue_name''<br />
Then disable it.<br />
# cupsdisable ''queue_name''<br />
Finally remove it.<br />
# lpadmin -x ''queue_name''<br />
<br />
;Print a test page<br />
$ lpr /usr/share/cups/data/testprint<br />
<br />
;Print a file<br />
$ lpr ''file''<br />
$ lpr -# 17 ''file'' # print the file 17 times<br />
$ echo 'Hello, world!' | lpr -p # print the result of a command. The -p switch adds a header.<br />
<br />
;Check the queue<br />
$ lpq<br />
$ lpq -a # on all queues<br />
<br />
;Clear the queue<br />
# lprm # remove last entry only<br />
# lprm - # remove all entries<br />
<br />
;View ink levels<br />
Install {{aur|ink}}. <br />
{{Note|See [http://libinklevel.sourceforge.net/index.html#supported list of supported printers].}}<br />
<br />
Add your user to the {{ic|lp}} [[user group]]:<br />
# usermod -aG lp <user><br />
<br />
Log out and log in again.<br />
<br />
For usage information, use:<br />
$ ink<br />
<br />
=== Web interface ===<br />
<br />
The CUPS server can be fully administered through the web interface, available on http://localhost:631/.<br />
<br />
{{Note|If an HTTPS connection to CUPS is used, it ''may'' take a very long time before the interface appears the first time it is accessed. This is because the first request triggers the generation of SSL certificates which can be a time-consuming job.}}<br />
<br />
To perform administrative tasks from the web interface authentication is required. Authenticate either as {{ic|root}} or make sure your user is member of a group with printer administration privileges, see [[#Configuration]].<br />
<br />
;Add a queue<br />
Go to the '''Administration''' page. <br />
<br />
;Modify existing queues<br />
Go to the '''Printers''' page, and select a queue to modify.<br />
<br />
;Test a queue<br />
Go to the '''Printers''' page, and select a queue.<br />
<br />
=== GUI applications ===<br />
<br />
If your user does not have sufficient privileges to administer CUPS, the applications will request the root password when they start. To give users administrative privileges without needing root access, see [[#Configuration]].<br />
<br />
* {{App|GtkLP|GTK interface for CUPS.|https://gtklp.sirtobi.com/index.shtml|{{AUR|gtklp}}}}<br />
* {{App|print-manager|Tool for managing print jobs and printers ([[KDE]]).|https://invent.kde.org/utilities/print-manager|{{Pkg|print-manager}}}}<br />
* {{App|system-config-printer|GTK printer configuration tool and status applet.|https://github.com/OpenPrinting/system-config-printer|{{Pkg|system-config-printer}}}}<br />
<br />
== Configuration ==<br />
<br />
The CUPS server configuration is located in {{ic|/etc/cups/cupsd.conf}} and {{ic|/etc/cups/cups-files.conf}} (see {{man|5|cupsd.conf}} and {{man|5|cups-files.conf}}). After editing either file, [[restart]] {{ic|org.cups.cupsd.service}} to apply any changes. The default configuration is sufficient for most users.<br />
<br />
[[User group]]s with printer administration privileges are defined in {{ic|SystemGroup}} in the {{ic|/etc/cups/cups-files.conf}}. The {{ic|sys}} and {{ic|root}} and {{ic|wheel}} groups are used by default.<br />
<br />
{{pkg|cups}} is built with {{pkg|libpaper}} support and libpaper defaults to the '''Letter''' paper size (called {{ic|PageSize}} in {{ic|lpoptions}}). To avoid having to change the paper size for each print queue you add, edit {{ic|/etc/papersize}} and set your system default paper size. See {{man|5|papersize}}.<br />
<br />
By default, all logs are sent to files in {{ic|/var/log/cups/}}. By changing the values of the {{ic|AccessLog}}, {{ic|ErrorLog}}, and {{ic|PageLog}} directives in {{ic|/etc/cups/cups-files.conf}} to {{ic|syslog}}, CUPS can be made to log to the [[systemd journal]] instead. See [https://fedoraproject.org/wiki/Changes/CupsJournalLogging the fedora wiki page] for information on the original proposed change.<br />
<br />
=== cups-browsed ===<br />
<br />
{{Out of date|{{ic|cups-browsed.service}} is not required to discover printers advertised over DNS-SD, that is done by {{ic|org.cups.cupsd.service}}. The service is only required to discover printers on an LDAP server and those using the legacy CUPS protocol (CUPS servers ≤ 1.5).}}<br />
<br />
CUPS can use [[Avahi]] browsing to discover unknown shared printers in your network. This can be useful in large setups where the server is unknown. To use this feature, set up [[Avahi#Hostname_resolution|.local hostname resolution]], and start both {{ic|avahi-daemon.service}} and {{ic|cups-browsed.service}}. Jobs are sent directly to the printer without any processing so the created queues may not work, however driverless printers such as those supporting [http://www.pwg.org/ipp/everywhere.html IPP Everywhere] or [[wikipedia:AirPrint|AirPrint]] should work out of the box.<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* Searching for network printers [https://bbs.archlinux.org/viewtopic.php?pid=1720219#p1720219 may significantly increase the time it takes for your computer to boot].<br />
* {{ic|cups-browsed.service}} is only needed to dynamically add and remove printers as they appear and disappear from a network. It is not required if you simply want to add a an DNS-SD/mDNS supporting network printer to CUPS.<br />
}}<br />
<br />
=== Print servers and remote administration ===<br />
<br />
See [[CUPS/Printer sharing]] and [[CUPS/Printer sharing#Remote administration]].<br />
<br />
=== Allowing admin authentication through PolicyKit ===<br />
<br />
[[PolicyKit]] can be configured to allow users to configure printers using a GUI without the admin password.<br />
<br />
{{Note|1=You may need to install {{Pkg|cups-pk-helper}} for working this rules.}}<br />
<br />
Here is an example that allows members of the wheel [[user group]] to administer printers without a password:<br />
<br />
{{hc|/etc/polkit-1/rules.d/49-allow-passwordless-printer-admin.rules|<nowiki><br />
polkit.addRule(function(action, subject) { <br />
if (action.id == "org.opensuse.cupspkhelper.mechanism.all-edit" && <br />
subject.isInGroup("wheel")){ <br />
return polkit.Result.YES; <br />
} <br />
});<br />
</nowiki>}}<br />
<br />
=== Without a local CUPS server ===<br />
<br />
CUPS can be configured to directly connect to remote printer servers instead of running a local print server. This requires [[install]]ation of the {{Pkg|libcups}} package. Some applications will still require the {{Pkg|cups}} package for printing.<br />
<br />
{{Warning|Accessing remote printers without a local CUPS server is not recommended by the developers. [https://lists.cups.org/pipermail/cups/2015-October/027229.html]}}<br />
<br />
To use a remote CUPS server, set the {{ic|CUPS_SERVER}} [[environment variable]] to {{ic|printerserver.mydomain:port}}. For instance, if you want to use a different print server for a single [[Firefox]] instance (substitute {{ic|printserver.mydomain:port}} with your print server name/port):<br />
<br />
$ CUPS_SERVER=printserver.mydomain:port firefox<br />
<br />
To make this configuration permanent create configuration file {{ic|/etc/cups/client.conf}} and add a hostname of the remote CUPS server to it:<br />
ServerName server<br />
You can also specify a custom port:<br />
ServerName server:port<br />
See [https://www.cups.org/doc/sharing.html#AUTO_IPP] for details.<br />
<br />
== Troubleshooting ==<br />
<br />
See [[CUPS/Troubleshooting]].<br />
<br />
== See also ==<br />
<br />
* [http://localhost:631/help Official CUPS documentation], ''locally installed''<br />
* [[Wikipedia:CUPS]]<br />
* [http://www.linuxfoundation.org/collaborate/workgroups/openprinting OpenPrinting homepage]<br />
* [https://en.opensuse.org/Concepts_printing OpenSuSE Concepts printing guide - explains the full printing workflow]<br />
* [https://en.opensuse.org/SDB:CUPS_in_a_Nutshell OpenSuSE CUPS in a Nutshell - a quick CUPS overview]<br />
* [https://wiki.gentoo.org/wiki/Printing Gentoo's printing guide]<br />
* [[debian:Printing|Debian's Printing portal - detailed technical guides]]<br />
* [[debian:SystemPrinting|Debian's printing overview - a basic view of the CUPS printing system]]</div>Jwh7https://wiki.archlinux.org/index.php?title=Modprobed-db&diff=634863Modprobed-db2020-09-10T14:56:37Z<p>Jwh7: /* Usage */ add reference to the list option and clarify the update methods</p>
<hr />
<div>[[Category:Kernel]]<br />
[[ja:Modprobed-db]]<br />
{{Related articles start}}<br />
{{Related|Kernels}}<br />
{{Related|Linux-ck}}<br />
{{Related articles end}}<br />
<br />
{{AUR|modprobed-db}} keeps a running list of ALL modules ever probed on a system and allow for easy recall. This is very useful for users wishing to build a minimal kernel via a {{ic|make localmodconfig}} which simply takes every module currently probed and switches everything BUT them off in the {{ic|.config}} for a kernel resulting in smaller kernel packages and reduced compilation times.<br />
<br />
== Installation and Setup ==<br />
The {{AUR|modprobed-db}} package is available from the [[AUR]].<br />
<br />
#Run {{ic|modprobed-db}} which will create {{ic|$XDG_CONFIG_HOME/modprobed-db.conf}} if one does not already exist.<br />
#Run {{ic|modprobed-db store}} to store the current loaded modules.<br />
<br />
'''Optionally:''' add modules in the ignore array that you do NOT want counted, for example modules that get built or that are provided by another package.<br />
Some common ones are included by default:<br />
{{hc|$ cat ~/.config/modprobed-db.conf|<nowiki><br />
IGNORE=(nvidia vboxdrv vboxnetflt vboxnetadp vboxpci lirc_dev lirc_i2c<br />
osscore oss_hdaudio oss_usb tp_smapi thinkpad_ec<br />
zavl znvpair zunicode zcommon zpios zfs spl splat)</nowiki>}}<br />
<br />
== Usage ==<br />
Once the initial database has been created, use {{ic|modprobed-db list}} to show the current database modules.<br />
=== Database Update ===<br />
Now simply use the system (insert USB sticks and devices, use hardware and mount filesystems requiring modules, etc.) and periodically update the database with {{ic|modprobed-db store}} or one of these automatic methods:<br />
<br />
==== Cron ====<br />
The most convenient method to use modprobed-db is to simply add a crontab entry invoking {{ic|/usr/bin/modprobed-db store}} at some regular interval.<br />
<br />
Example running the script once every hour:<br />
$ crontab -e<br />
0 */1 * * * /usr/bin/modprobed-db store &> /dev/null<br />
<br />
==== Systemd ====<br />
Systemd users not wishing to use cron may use the included user service: {{ic|modprobed-db.service}}. It will run modprobed-db in store mode once per hour, and at boot and on shutdown.<br />
<br />
$ systemctl --user enable --now modprobed-db.service<br />
<br />
Status of the service and of the timer can be queried like any service and timer:<br />
$ systemctl --user status modprobed-db<br />
$ systemctl --user list-timers<br />
<br />
=== Data Recall ===<br />
After the database has been adequately populated, it can be read directly by [https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/README?id=refs/tags/v4.3.3#n205 make localmodconfig]<br />
<br />
==== Using the Official Arch kernel PKGBUILD ====<br />
The official Arch kernel PKGBUILD can be modified as shown to do this automatically:<br />
<br />
{{bc| ...<br />
msg2 "Applying patch $src..."<br />
patch -Np1 < "../$src"<br />
done<br />
<br />
msg2 "Setting config..."<br />
cp ../config .config<br />
make olddefconfig<br />
<br />
<nowiki>make LSMOD=$HOME/.config/modprobed.db localmodconfig # <---- insert this line</nowiki><br />
<br />
make -s kernelrelease > ../version<br />
...}}<br />
<br />
== Recommendations ==<br />
It is recommended that users install the package and then "use" the system for a good amount of time to allow the database to grow based on usage and capture everything the system needs before building a kernel with a '''make localmodconfig'''. Some suggested actions to allow appropriate modules to load and get cataloged:<br />
<br />
*Insert every kind of removable media (USB, DVD, CD, etc.)<br />
*Use every device on the machine (wifi, network, USB stuff like cameras, ipods, etc.)<br />
*Mount every kind of filesystem one might typically use including ext2/3/4, fat, vfat, CIFS shares, NFS shares, etc.<br />
*Use as many applications (that one would normally use) as possible in order to capture modules on which they depend. For example, IP blocking/filtering software like {{AUR|pgl-cli}}.<br />
*Users who plan to mount iso image file should do so (this will make sure to capture the '''loop''' and '''isofs''' modules).<br />
*Users requiring encryption software such as {{Pkg|truecrypt}} should make sure to load it, and mount some encrypted containers to ensure that the needed crypto modules are in the db.<br />
*Try-out different Linux-kernels; they may include modules not enabled in the default/other kernel(s)<br />
<br />
== Suggested Modules ==<br />
*cifs<br />
*ext2<br />
*ext3<br />
*ext4<br />
*fat<br />
*isofs<br />
*loop<br />
*efivars<br />
*vfat<br />
*usb_storage<br />
<br />
== Benefits of modprobed-db with '''make localmodconfig''' in custom kernels==<br />
#Reduced kernel footprint on FS<br />
#Reduced compilation time<br />
<br />
Comparisons using version 3.8.8-1 of the Arch kernel (from ABS):<br />
<br />
{{Note| The modprobed.db on the test machine contains 209 lines; YMMV based on specific usage and needs.}}<br />
<br />
{| border="1"<br />
| '''Machine CPU''' || '''# of threads''' || '''make localmodconfig'''||'''# of Modules''' || '''Modules' Size on HDD''' || '''Compilation Time'''<br />
|-<br />
| Intel i7-3770K @ 4.50 GHz || 8 || No || 3,025 || 129 MB || 7 min 37 sec<br />
|- <br />
| Intel i7-3770K @ 4.50 GHz || 8 || Yes || 230 || 18 MB || 1 min 13 sec<br />
|- <br />
| Intel Q9550 @ 3.40 GHz || 4 || No || 3,025 || 129 MB || 14 min 21 sec<br />
|- <br />
| Intel Q9550 @ 3.40 GHz || 4 || Yes || 230 || 18 MB || 2 min 20 sec<br />
|- <br />
| Intel E5200 @ 3.33 GHz || 2 || No || 3,025 || 129 MB || 34 min 35 sec<br />
|- <br />
| Intel E5200 @ 3.33 GHz || 2 || Yes || 230 || 18 MB || 5 min 46 sec<br />
|- <br />
|}<br />
<br />
*'''13x less modules built'''<br />
*'''7x less space'''<br />
*'''6x less compilation time'''<br />
<br />
Number of modules found by:<br />
find /scratch/linux-3.8 -name '*.ko' | wc -l<br />
<br />
Size on HDD found by:<br />
find /scratch/linux-3.8 -name '*.ko' -print0 | xargs -0 du -ch<br />
<br />
Compilation time found by entering a preconfigured linux-3.8.8 (using stock Arch config):<br />
$ time make -jx modules<br />
<br />
{{Note|The Arch standard is to gzip each module; the numbers shown in the table above are not gzip'ed but the savings ratio will be unaffected by this.}}</div>Jwh7https://wiki.archlinux.org/index.php?title=Dual_boot_with_Windows&diff=634736Dual boot with Windows2020-09-08T18:00:39Z<p>Jwh7: /* Bootloader UEFI vs BIOS limitations */ Add info to help with the limited Windows UEFI partition size</p>
<hr />
<div>[[Category:Boot process]]<br />
[[Category:Installation process]]<br />
[[es:Dual boot with Windows]]<br />
[[ja:Windows と Arch のデュアルブート]]<br />
[[pt:Dual boot with Windows]]<br />
[[ru:Dual boot with Windows]]<br />
[[sk:Dual boot with Windows]]<br />
[[zh-hans:Dual boot with Windows]]<br />
This is an article detailing different methods of Arch/Windows coexistence.<br />
<br />
== Important information ==<br />
<br />
=== Windows UEFI vs BIOS limitations ===<br />
<br />
Microsoft imposes limitations on which firmware boot mode and partitioning style can be supported based on the version of Windows used:<br />
<br />
{{Expansion|UEFI/MBR is not supported by the Windows installer, but Windows can be manually deployed and booted in UEFI/MBR (at least Windows 10 can).}}<br />
<br />
* '''Windows XP''' both '''x86 32-bit''' and '''x86_64''' (also called x64) (RTM and all Service Packs) versions do not support booting in [[UEFI]] mode (IA32 or x86_64) from any disk ([[MBR]] or [[GPT]]) OR in BIOS mode from GPT disk. They support only BIOS boot and only from MBR disk.<br />
* '''Windows Vista''' or '''7''' '''x86 32-bit''' (RTM and all Service Packs) versions support booting in BIOS mode from MBR disks only, not from GPT disks. They do not support x86_64 UEFI or IA32 (x86 32-bit) UEFI boot. They support only BIOS boot and only from MBR disk.<br />
* '''Windows Vista RTM x86_64''' (only RTM) version support booting in BIOS mode from MBR disks only, not from GPT disks. It does not support x86_64 UEFI or IA32 (x86 32-bit) UEFI boot. It supports only BIOS boot and only from MBR disk.<br />
* '''Windows Vista''' (SP1 and above, not RTM) and '''Windows 7''' '''x86_64''' versions support booting in x86_64 UEFI mode from GPT disk only, OR in BIOS mode from MBR disk only. They do not support IA32 (x86 32-bit) UEFI boot from GPT/MBR disk, x86_64 UEFI boot from MBR disk, or BIOS boot from GPT disk.<br />
* '''Windows 8/8.1 x86 32-bit''' support booting in IA32 UEFI mode from GPT disk only, OR in BIOS mode from MBR disk only. They do not support x86_64 UEFI boot from GPT/MBR disk, x86_64 UEFI boot from MBR disk, or BIOS boot from GPT disk. On market, the only systems known to ship with IA32 (U)EFI are some old Intel Macs (pre-2010 models?) and Intel Atom System-on-Chip (Clover trail and Bay Trail) Windows Tablets. in which it boots ONLY in IA32 UEFI mode and ONLY from GPT disk.<br />
* '''Windows 8/8.1''' '''x86_64''' versions support booting in x86_64 UEFI mode from GPT disk only, OR in BIOS mode from MBR disk only. They do not support IA32 UEFI boot, x86_64 UEFI boot from MBR disk, or BIOS boot from GPT disk.<br />
<br />
In case of pre-installed Systems:<br />
<br />
* All systems pre-installed with Windows XP, Vista or 7 32-bit, irrespective of Service Pack level, bitness, edition (SKU) or presence of UEFI support in firmware, boot in BIOS/MBR mode by default.<br />
* MOST of the systems pre-installed with Windows 7 x86_64, irrespective of Service Pack level, bitness or edition (SKU), boot in BIOS/MBR mode by default. Very few recent systems pre-installed with Windows 7 are known to boot in x86_64 UEFI/GPT mode by default.<br />
* ALL systems pre-installed with Windows 8/8.1 boot in UEFI/GPT mode. The firmware bitness matches the bitness of Windows, ie. x86_64 Windows 8/8.1 boot in x86_64 UEFI mode and 32-bit Windows 8/8.1 boot in IA32 UEFI mode.<br />
<br />
The best way to detect the boot mode of Windows is to do the following[http://www.eightforums.com/tutorials/29504-bios-mode-see-if-windows-boot-uefi-legacy-mode.html]:<br />
<br />
* Boot into Windows<br />
* Press {{ic|Win+R}} keys to start the Run dialog<br />
* In the Run dialog type {{ic|msinfo32.exe}} and press Enter<br />
* In the '''System Information''' windows, select ''System Summary'' on the left and check the value of '''BIOS mode''' item on the right<br />
* If the value is {{ic|UEFI}}, Windows boots in UEFI/GPT mode. If the value is {{ic|Legacy}}, Windows boots in BIOS/MBR mode.<br />
<br />
In general, Windows forces type of partitioning depending on the firmware mode used, i.e. if Windows is booted in UEFI mode, it can be installed only to a GPT disk. If the Windows is booted in Legacy BIOS mode, it can be installed only to a MBR disk. This is a limitation enforced by Windows installer, and as of April 2014 there is no officially (Microsoft) supported way of installing Windows in UEFI/MBR or BIOS/GPT configuration. Thus Windows only supports either UEFI/GPT boot or BIOS/MBR configuration.<br />
<br />
{{Tip|Windows 10 version 1703 and newer supports converting from BIOS/MBR to UEFI/GPT using [https://docs.microsoft.com/en-us/windows/deployment/mbr-to-gpt MBR2GPT.EXE].}}<br />
<br />
Such a limitation is not enforced by the Linux kernel, but can depend on which [[boot loader]] is used and/or how the boot loader is configured. The Windows limitation should be considered if the user wishes to boot Windows and Linux from the same disk, since installation procedure of boot loader depends on the firmware type and disk [[partitioning]] configuration. In case where Windows and Linux dual boot from the same disk, it is advisable to follow the method used by Windows, ie. either go for UEFI/GPT boot or BIOS/MBR boot. See https://support.microsoft.com/kb/2581408 for more information.<br />
<br />
=== Install media limitations ===<br />
<br />
Intel Atom System-on-Chip Tablets (Clover trail and Bay Trail) provide only IA32 UEFI firmware without Legacy BIOS (CSM) support (unlike most of the x86_64 UEFI systems), due to Microsoft Connected Standby Guidelines for OEMs. Due to lack of Legacy BIOS support in these systems, and the lack of 32-bit UEFI boot in Arch Official Install ISO ({{Bug|53182}}), the official install media cannot boot on these systems. See [[Unified Extensible Firmware Interface#UEFI firmware bitness]] for more information and available workarounds.<br />
<br />
=== Bootloader UEFI vs BIOS limitations ===<br />
<br />
Most of the linux bootloaders installed for one firmware type cannot launch or chainload bootloaders of the other firmware type. That is, if Arch is installed in UEFI/GPT or UEFI/MBR mode in one disk and Windows is installed in BIOS/MBR mode in another disk, the UEFI bootloader used by Arch cannot chainload the BIOS installed Windows in the other disk. Similarly if Arch is installed in BIOS/MBR or BIOS/GPT mode in one disk and Windows is installed in UEFI/GPT in another disk , the BIOS bootloader used by Arch cannot chainload UEFI installed Windows in the other disk. <br />
<br />
The only exceptions to this are [[GRUB]] in Apple Macs in which GRUB in UEFI mode can boot BIOS installed OS via {{ic|appleloader}} command (does not work in non-Apple systems), and [[rEFInd]] which technically supports booting legacy BIOS OS from UEFI systems, but [http://rodsbooks.com/refind/using.html#legacy does not always work in non-Apple UEFI systems] as per its author Rod Smith. <br />
<br />
However if Arch is installed in BIOS/GPT in one disk and Windows is installed in BIOS/MBR mode in another disk, then the BIOS boot loader used by Arch CAN boot the Windows in the other disk, if the boot loader itself has the ability to chainload from another disk. <br />
<br />
{{Note|To dual-boot with Windows on same disk, Arch should follow the same firmware boot mode and partitioning combination used by the Windows install.}}<br />
<br />
The default Windows {{ic|esp}} partition for UEFI is 100 MB so custom kernel usage is limited. Workarounds include:<br />
*Use a [[Arch_boot_process#Boot_loader|bootloader]] that can have separate {{ic|esp}} and {{ic|boot}} mounts or partitions.<br />
*Expand the EFI partition, typically either by decreasing the Recovery partition size or moving the Windows partition ('''UUID's will change''').<br />
*Backup and delete unneeded fonts in {{ic|''esp''/EFI/Microsoft/Boot/Fonts/}} [https://support.microsoft.com/en-us/help/3086249/we-couldn-t-update-system-reserved-partition-error-installing-windows].<br />
*Backup and delete unneeded language directories in {{ic|''esp''/EFI/Microsoft/Boot/}} (e.g. to only keep {{ic|en-US}}).<br />
<br />
=== UEFI Secure Boot ===<br />
<br />
All pre-installed Windows 8/8.1 systems by default boot in UEFI/GPT mode and have UEFI Secure Boot enabled by default. This is mandated by Microsoft for all OEM pre-installed systems.<br />
<br />
Arch Linux install media does not support Secure Boot. See [[Secure Boot#Booting an installation medium]]. <br />
<br />
It is advisable to disable UEFI Secure Boot in the firmware setup manually before attempting to boot Arch Linux. Windows 8/8.1 SHOULD continue to boot fine even if Secure boot is disabled. The only issue with regards to disabling UEFI Secure Boot support is that it requires physical access to the system to disable secure boot option in the firmware setup, as Microsoft has explicitly forbidden presence of any method to remotely or programmatically (from within OS) disable secure boot in all Windows 8/8.1 pre-installed systems<br />
<br />
=== Fast Startup and hibernation ===<br />
<br />
There are two OSs that can be hibernated, you can hibernate Windows and boot Linux (or another OS), or you can hibernate Linux and boot Windows, or hibernate both OSs.<br />
<br />
{{Warning|Data loss can occur if Windows hibernates and you dual boot into another OS and make changes to files on a filesystem (such as NTFS) that can be read and written to by Windows and Linux, and that has been mounted by Windows [https://superuser.com/questions/39532/hibernating-and-booting-into-another-os-will-my-filesystems-be-corrupted/136814#136814]. Similarly, data loss can occur if Linux hibernates, and you dual boot into another OS etc. Windows may hibernate even when you press shutdown, see section [[#Windows settings]].}}<br />
<br />
For the same reason, if you share one EFI System Partition between Windows and Linux, then the EFI System Partition may be damaged if you hibernate (or shutdown with Fast Startup enabled) and then start Linux, or hibernate Linux and then start Windows.<br />
<br />
{{Pkg|ntfs-3g}} added a [https://sourceforge.net/p/ntfs-3g/ntfs-3g/ci/559270a8f67c77a7ce51246c23d2b2837bcff0c9/ safe-guard] to prevent read-write mounting of hibernated NTFS filesystems, but the NTFS driver within the Linux kernel has no such safeguard.<br />
<br />
Windows cannot read filesystems such as ext4 by default that are commonly used for Linux. These filesystems do not have to be considered, unless you install a Windows driver for them.<br />
<br />
==== Windows settings ====<br />
<br />
Fast Startup is a feature in Windows 8 and above that hibernates the computer rather than actually shutting it down to speed up boot times.<br />
<br />
There are multiple options regarding the Windows settings for Fast Startup and hibernation that are covered in the next sections.<br />
* disable Fast Startup and disable hibernation<br />
* disable Fast Startup and enable hibernation<br />
* enable Fast Startup and enable hibernation<br />
<br />
The procedure of disabling Fast Startup is described [http://www.eightforums.com/tutorials/6320-fast-startup-turn-off-windows-8-a.html here for Windows 8] and [http://www.tenforums.com/tutorials/4189-fast-startup-turn-off-windows-10-a.html here for Windows 10]. In any case if you disable a setting, make sure to disable the setting and then shut down Windows, before installing Linux; note that rebooting is not sufficient.<br />
<br />
===== Disable Fast Startup and disable hibernation =====<br />
<br />
This is the safest option, and recommended if you are unsure about the issue, as it requires the least amount of user awareness when rebooting from one OS into the other. You may share the same EFI System Partition between Windows and Linux.<br />
<br />
===== Disable Fast Startup and enable hibernation =====<br />
<br />
This option requires user awareness when rebooting from one OS into the other.<br />
If you want to start Linux while Windows is hibernated, which is a common use case, then<br />
* you must use a separate EFI System Partition (ESP) for Windows and Linux, and ensure that Windows does not mount the ESP used for Linux. As there can only be one ESP per drive, the ESP used for Linux must be located on a separate drive than the ESP used for Windows. In this case Windows and Linux can still be installed on the same drive in different partitions, if you place the ESP used by linux on another drive than the Linux root partition.<br />
* you can not read-write mount any filesystem in Linux, that is mounted by Windows while Windows is hibernated. You should be extremely careful about this, and also consider [[Automount]] behaviour.<br />
* If you shut down Windows fully, rather than hibernating, then you can read-write mount the filesystem.<br />
<br />
{{Note|You can avoid this issue for a drive by mounting a drive as an external drive in Windows and ejecting the drive in Windows before hibernating.}}<br />
<br />
===== Enable Fast Startup and enable hibernation =====<br />
<br />
The same considerations apply as in case "Disable Fast Startup and enable hibernation", but since Windows can not be shut down fully, only hibernated, you can never read-write mount any filesystem that was mounted by Windows while Windows is hibernated.<br />
<br />
{{Note|Windows updates may re-enable Fast Startup, as reported in [https://tedstechshack.com/2017/07/03/warning-multi-booting-uefi-system-windows-10-fast-startup-doubt-reboot/].}}<br />
<br />
=== Windows filenames limitations ===<br />
<br />
Windows is limited to filepaths being shorter than [http://blogs.msdn.com/b/bclteam/archive/2007/02/13/long-paths-in-net-part-1-of-3-kim-hamilton.aspx 260 characters].<br />
<br />
Windows also puts [https://msdn.microsoft.com/en-us/library/aa365247(VS.85).aspx#naming_conventions certain characters off limits] in filenames for reasons that run all the way back to DOS:<br />
<br />
* {{ic|<}} (less than)<br />
* {{ic|>}} (greater than)<br />
* {{ic|:}} (colon)<br />
* {{ic|"}} (double quote)<br />
* {{ic|/}} (forward slash)<br />
* {{ic|\}} (backslash)<br />
* {{ic|{{!}}}} (vertical bar or pipe)<br />
* {{ic|?}} (question mark)<br />
* {{ic|*}} (asterisk)<br />
<br />
These are limitations of Windows and not NTFS: any other OS using the NTFS partition will be fine. Windows will fail to detect these files and running {{ic|chkdsk}} will most likely cause them to be deleted. This can lead to potential data-loss.<br />
<br />
[[NTFS-3G]] applies Windows restrictions to new file names through the [http://www.tuxera.com/community/ntfs-3g-manual/#4 windows_names] option (see [[fstab]]).<br />
<br />
== Installation ==<br />
<br />
The recommended way to setup a Linux/Windows dual booting system is to first install Windows, only using part of the disk for its partitions. When you have finished the Windows setup, boot into the Linux install environment where you can create and resize partitions for Linux while leaving the existing Windows partitions untouched. The Windows installation will create the [[EFI system partition]] which can be used by your Linux [[boot loader]].<br />
<br />
=== Windows before Linux ===<br />
<br />
==== BIOS systems ====<br />
<br />
===== Using a Linux boot loader =====<br />
<br />
You may use any multi-boot supporting BIOS [[boot loader]].<br />
<br />
===== Using Windows boot loader =====<br />
<br />
With this setup the Windows bootloader loads GRUB which then boots Arch. <br />
<br />
====== Windows Vista/7/8/8.1 boot loader ======<br />
<br />
{{Style|Contains personal comments.}}<br />
<br />
The following section contains excerpts from http://www.iceflatline.com/2009/09/how-to-dual-boot-windows-7-and-linux-using-bcdedit/.<br />
<br />
{{Accuracy|Using ext3 formatted /boot partition, windows bootloader works just fine}}<br />
<br />
In order to have the Windows boot loader see the Linux partition, one of the Linux partitions created needs to be FAT32 (in this case, {{ic|/dev/sda3}}). The remainder of the setup is similar to a typical installation. Some documents state that the partition being loaded by the Windows boot loader must be a primary partition but I have used this without problem on an extended partition.<br />
<br />
* When installing the GRUB boot loader, install it on your {{ic|/boot}} partition rather than the MBR. {{Note|For instance, my {{ic|/boot}} partition is {{ic|/dev/sda5}}. So I installed GRUB at {{ic|/dev/sda5}} instead of {{ic|/dev/sda}}. For help on doing this, see [[GRUB/Tips and tricks#Install to partition or partitionless disk]].}}<br />
<br />
* Under Linux make a copy of the boot info by typing the following at the command shell:<br />
<br />
my_windows_part=/dev/sda3<br />
my_boot_part=/dev/sda5<br />
mkdir /media/win<br />
mount $my_windows_part /media/win<br />
dd if=$my_boot_part of=/media/win/linux.bin bs=512 count=1<br />
<br />
* Boot to Windows and open up and you should be able to see the linux.bin file at {{ic|C:\}}. Now run '''cmd''' with administrator privileges (navigate to ''Start > All Programs > Accessories'', right-click on ''Command Prompt'' and select ''Run as administrator''):<br />
<br />
bcdedit /create /d "Linux" /application BOOTSECTOR<br />
<br />
* BCDEdit will return a [[wikipedia:Universally_unique_identifier|UUID]] for this entry that I will refer to as {ID} in the remaining steps. You will need to replace {ID} by the actual returned identifier. An example of {ID} is {d7294d4e-9837-11de-99ac-f3f3a79e3e93}. <br />
<br />
bcdedit /set {ID} device partition=c:<br />
bcdedit /set {ID} path \linux.bin<br />
bcdedit /displayorder {ID} /addlast<br />
bcdedit /timeout 30<br />
<br />
Reboot and enjoy. In my case I'm using the Windows boot loader so that I can map my Dell Precision M4500's second power button to boot Linux instead of Windows.<br />
<br />
==== UEFI systems ====<br />
<br />
If you already have Windows installed, it will already have created some partitions on a [[GPT]]-formatted disk:<br />
<br />
* a [[Wikipedia:Windows Recovery Environment|Windows Recovery Environment]] partition, generally of size 499 MiB, containing the files required to boot Windows (i.e. the equivalent of Linux's {{ic|/boot}}),<br />
* an [[EFI system partition]] with a [[FAT32]] filesystem,<br />
* a [[Wikipedia:Microsoft Reserved Partition|Microsoft Reserved Partition]], generally of size 128 MiB,<br />
* a Microsoft basic data partition with a NTFS filesystem, which corresponds to {{ic|C:}},<br />
* potentially system recovery and backup partitions and/or secondary data partitions (corresponding often to {{ic|D:}} and above).<br />
<br />
Using the Disk Management utility in Windows, check how the partitions are labelled and which type gets reported. This will help you understand which partitions are essential to Windows, and which others you might repurpose.<br />
<br />
{{Warning|The first 4 partitions in the above list are essential, do not delete them.}}<br />
<br />
You can then proceed with [[partitioning]], depending on your needs.<br />
<br />
Mind that an additional EFI system partition should not be created, as it may [https://support.microsoft.com/en-us/help/2879602/unable-to-boot-if-more-than-one-efi-system-partition-is-present prevent Windows from booting]. Simply [[EFI system partition#Mount the partition|mount the existing partition]].<br />
<br />
{{Note|It only appears when Linux is installed on the second hard disk and a new EFI system partition is created on the second hard disk.}}<br />
<br />
The boot loader needs to support chainloading other EFI applications to do dual boot Windows / Linux.<br />
<br />
{{Tip|[[rEFInd]] and [[systemd-boot]] will autodetect ''Windows Boot Manager'' ({{ic|\EFI\Microsoft\Boot\bootmgfw.efi}}) and show it in their boot menu automatically. For [[GRUB]] follow either [[GRUB#Windows installed in UEFI/GPT mode]] to add boot menu entry manually or [[GRUB#Detecting other operating systems]] for a generated configuration file.}}<br />
<br />
Computers that come with newer versions of Windows often have [[Secure Boot]] enabled. You will need to take extra steps to either disable Secure Boot or to make your installation media compatible with secure boot (see above and in the linked page).<br />
<br />
=== Linux before Windows ===<br />
<br />
Even though the recommended way to setup a Linux/Windows dual booting system is to first install Windows, it can be done the other way around. In contrast to installing Windows before Linux, you will have to set aside a partition for windows, say 40GB or larger, in advance. Or have some unpartitioned disk space, or create and resize partitions for Windows from within the Linux installation, before launching the Windows installation.<br />
<br />
==== UEFI firmware ====<br />
<br />
Windows will use the already existing [[EFI system partition]]. In contrast to what was [[#UEFI systems|stated earlier]], it is unclear if a single partition for Windows, without the Windows Recovery Environment and without Microsoft Reserved Partition, will not do.<br />
<br />
Follows an outline, assuming [[Secure Boot]] is disabled in the firmware.<br />
<br />
# Boot into windows installation. Watch to let it use only the intend partition, but otherwise let it do its work as if there is no Linux installation.<br />
# Follow the [[#Fast Startup and hibernation]] section.<br />
# Fix the ability to load Linux at start up, perhaps by following [[#Cannot boot Linux after installing Windows]]. It was already mentioned in [[#UEFI systems]] that some Linux boot managers will autodetect ''Windows Boot Manager''. Even though newer Windows installations have an advanced restart option, from which you can boot into Linux, it is advised to have other means to boot into Linux, such as an arch installation media or a live CD.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Couldn't create a new partition or locate an existing one ====<br />
<br />
See [[#Windows UEFI vs BIOS limitations]].<br />
<br />
==== Cannot boot Linux after installing Windows ====<br />
<br />
See [[Unified Extensible Firmware Interface#Windows changes boot order]].<br />
<br />
==== Restoring a Windows boot record ====<br />
<br />
By convention (and for ease of installation), Windows is usually installed on the first partition and installs its partition table and reference to its bootloader to the first sector of that partition. If you accidentally install a bootloader like GRUB to the Windows partition or damage the boot record in some other way, you will need to use a utility to repair it. Microsoft includes a boot sector fix utility {{Ic|FIXBOOT}} and an MBR fix utility called {{Ic|FIXMBR}} on their recovery discs, or sometimes on their install discs. Using this method, you can fix the reference on the boot sector of the first partition to the bootloader file and fix the reference on the MBR to the first partition, respectively. After doing this you will have to [[GRUB#Installation|reinstall GRUB]] to the MBR as was originally intended (that is, the GRUB bootloader can be assigned to chainload the Windows bootloader).<br />
<br />
If you wish to revert back to using Windows, you can use the {{Ic|FIXBOOT}} command which chains from the MBR to the boot sector of the first partition to restore normal, automatic loading of the Windows operating system.<br />
<br />
Of note, there is a Linux utility called {{Ic|ms-sys}} (package {{AUR|ms-sys}} in AUR) that can install MBR's. However, this utility is only currently capable of writing new MBRs (all OS's and file systems supported) and boot sectors (a.k.a. boot record; equivalent to using {{Ic|FIXBOOT}}) for FAT file systems. Most LiveCDs do not have this utility by default, so it will need to be installed first, or you can look at a rescue CD that does have it, such as [http://partedmagic.com/ Parted Magic].<br />
<br />
First, write the partition info (table) again by:<br />
<br />
# ms-sys --partition /dev/sda1<br />
<br />
Next, write a Windows 2000/XP/2003 MBR:<br />
<br />
# ms-sys --mbr /dev/sda # Read options for different versions<br />
<br />
Then, write the new boot sector (boot record):<br />
<br />
# ms-sys -(1-6) # Read options to discover the correct FAT record type<br />
<br />
{{Ic|ms-sys}} can also write Windows 98, ME, Vista, and 7 MBRs as well, see {{Ic|ms-sys -h}}.<br />
<br />
== Time standard ==<br />
<br />
* Recommended: Set both Arch Linux and Windows to use UTC, following [[System time#UTC in Windows]]. Some versions of Windows revert the hardware clock back to ''localtime'' if they are set to synchronize the time online. This issue appears to be fixed in Windows 10.<br />
* Not recommended: Set Arch Linux to ''localtime'' and disable all [[System time#Time synchronization|time synchronization daemons]]. This will let Windows take care of hardware clock corrections and you will need to remember to boot into Windows at least two times a year (in Spring and Autumn) when [[Wikipedia:Daylight saving time|DST]] kicks in. So please do not ask on the forums why the clock is one hour behind or ahead if you usually go for days or weeks without booting into Windows.<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=140049 Booting Windows from a desktop shortcut]<br />
* [https://github.com/kaipee/grub-reboot2win One-time boot into Windows partition from desktop shortcut]<br />
* [https://github.com/ValdikSS/windows2usb Windows 7/8/8.1/10 ISO to Flash Drive burning utility for Linux (MBR/GPT, BIOS/UEFI, FAT32/NTFS)]</div>Jwh7https://wiki.archlinux.org/index.php?title=Systemd-boot&diff=634730Systemd-boot2020-09-08T17:31:46Z<p>Jwh7: /* Installation using XBOOTLDR */ Reword to highlight this requires a specific partition type, also add spec link</p>
<hr />
<div>{{lowercase title}}<br />
[[Category:Boot loaders]]<br />
[[de:Systemd-boot]]<br />
[[es:Systemd-boot]]<br />
[[ja:Systemd-boot]]<br />
[[pt:Systemd-boot]]<br />
[[ru:Systemd-boot]]<br />
[[zh-hans:Systemd-boot]]<br />
{{Related articles start}}<br />
{{Related|Arch boot process}}<br />
{{Related|Secure Boot}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related articles end}}<br />
<br />
'''systemd-boot''', previously called '''gummiboot''' (German for: 'rubber dinghy'), is a simple UEFI [[boot manager]] which executes configured EFI images. The default entry is selected by a configured pattern (glob) or an on-screen menu to be navigated via arrow-keys. It is included with {{pkg|systemd}}, which is installed on an Arch system by default.<br />
<br />
It is simple to configure but it can only start EFI executables such as the Linux kernel [[EFISTUB]], UEFI Shell, GRUB, or the Windows Boot Manager.<br />
<br />
== Installation ==<br />
<br />
=== Installing the EFI boot manager ===<br />
<br />
To install the ''systemd-boot'' EFI boot manager, first make sure the system has booted in UEFI mode and that [[Unified Extensible Firmware Interface#UEFI variables|UEFI variables]] are accessible. This can be checked by running the command {{ic|efivar --list}} or, if {{Pkg|efivar}} is not installed, by doing {{ic|ls /sys/firmware/efi/efivars}} (if the directory exists, the system is booted in UEFI mode).<br />
<br />
{{ic|''esp''}} will be used throughout this page to denote the ESP mountpoint, e.g. {{ic|/boot}}, or {{ic|/boot/efi}}, or {{ic|/efi}}. This assumes that you have {{ic|chroot}}ed to your system's mount point.<br />
<br />
With the ESP mounted to {{ic|''esp''}}, use bootctl to install ''systemd-boot'' into the EFI system partition by running: <br />
# bootctl install<br />
This will copy the ''systemd-boot'' boot loader to the EFI partition: on a x64 architecture system the two identical binaries {{ic|''esp''/EFI/systemd/systemd-bootx64.efi}} and {{ic|''esp''/EFI/BOOT/BOOTX64.EFI}} will be transferred to the ESP. It will then set ''systemd-boot'' as the default EFI application (default boot entry) loaded by the EFI Boot Manager. <br />
<br />
To conclude the installation, [[#Configuration|configure]] ''systemd-boot''.<br />
<br />
=== Installation using XBOOTLDR ===<br />
<br />
Since systemd version 242, a separate {{ic|''boot''}} partition of type {{ic|"Linux extended boot"}} can be created to keep the kernel and initramfs separate from the {{ic|''esp''}} partition. XBOOTLDR [https://systemd.io/BOOT_LOADER_SPECIFICATION] must have a partition type GUID of {{ic|"bc13c2ff-59e6-4262-a352-b275fd6f7172"}}.<br />
<br />
This is particularly helpful to [[Dual boot with Windows]] with a default 100 MB [[EFI_system_partition#Check_for_an_existing_partition|EFI system partition]]. Otherwise create an {{ic|''esp''}} partition as normal plus another for {{ic|''boot''}} on the same physical drive. The size of {{ic|''boot''}} should be enough to accommodate all of the kernels you are going to install.<br />
<br />
{{Note|systemd-boot does not do a file system check like it does for the ESP. Hence, it is possible to use other file systems but only if your UEFI implementation can read it during boot.}}<br />
<br />
During install mount {{ic|''esp''}} to {{ic|/mnt/efi}} and {{ic|''boot''}} to {{ic|/mnt/boot}}.<br />
<br />
Once in chroot use the command:<br />
# bootctl --esp-path=/efi --boot-path=/boot install<br />
<br />
To conclude the installation, [[#Configuration|configure]] ''systemd-boot''.<br />
<br />
=== Updating the EFI boot manager ===<br />
<br />
Whenever there is a new version of ''systemd-boot'', the boot manager can be optionally reinstalled by the user. This can be performed manually or the update can be automatically triggered using pacman hooks. The two approaches are described thereafter.<br />
<br />
{{Note|The boot manager is a standalone EFI executable and any version can be used to boot the system (partial updates do not apply, since pacman only installs the systemd-boot installer, not systemd-boot itself). However, new versions may add new features or fix bugs, so it is probably a good idea to update it anyway.}}<br />
<br />
==== Manual update ====<br />
<br />
''bootctl'' must be used to update ''systemd-boot''.<br />
<br />
# bootctl update<br />
<br />
If the ESP is mounted on a different location, check the man page for the options {{ic|1=--esp-path=}} and {{ic|1=--boot-path=}}.<br />
<br />
{{Note|This command with these options are also used when migrating from ''gummiboot'', before removing that package. If that package has already been removed, however, run {{ic|1=bootctl --esp-path=''esp'' install}}.}}<br />
<br />
==== Automatic update ====<br />
<br />
The package {{AUR|systemd-boot-pacman-hook}} provides a [[Pacman hook]] to automate the update process. [[Install|Installing]] the package will add a hook which will be executed every time the {{Pkg|systemd}} package is upgraded.<br />
Alternatively, to replicate what the ''systemd-boot-pacman-hook'' package does without installing it, place the following pacman hook in the {{ic|/etc/pacman.d/hooks/}} directory:<br />
<br />
{{hc|/etc/pacman.d/hooks/100-systemd-boot.hook|2=<br />
[Trigger]<br />
Type = Package<br />
Operation = Upgrade<br />
Target = systemd<br />
<br />
[Action]<br />
Description = Updating systemd-boot<br />
When = PostTransaction<br />
Exec = /usr/bin/bootctl update<br />
}}<br />
<br />
== Configuration ==<br />
<br />
=== Loader configuration ===<br />
<br />
The loader configuration is stored in the file {{ic|''esp''/loader/loader.conf}}. The following settings can be specified:<br />
<br />
* {{ic|default}} – default entry to select as defined in [[#Adding loaders]]; it can be a wildcard like {{ic|arch-*.conf}}.<br />
* {{ic|timeout}} – menu timeout in seconds before the default entry is booted. If this is not set, the menu will only be shown on {{ic|Space}} key (or most other keys actually work too) press during boot.<br />
* {{ic|editor}} – whether to enable the kernel parameters editor or not. {{ic|yes}} (default) is enabled, {{ic|no}} is disabled; since the user can add {{ic|1=init=/bin/bash}} to bypass root password and gain root access, it is strongly recommended to set this option to {{ic|no}} if the machine can be accessed by unauthorized persons.<br />
* {{ic|auto-entries}} – shows automatic entries for Windows, EFI Shell, and Default Loader if set to {{ic|1}} (default), {{ic|0}} to hide;<br />
* {{ic|auto-firmware}} – shows entry for rebooting into UEFI firmware settings if set to {{ic|1}} (default), {{ic|0}} to hide;<br />
* {{ic|console-mode}} – changes UEFI console mode:<br />
** {{ic|0}} for 80x25;<br />
** {{ic|1}} for 80x50;<br />
** {{ic|2}} and above for non-standard modes provided by the device firmware, if any;<br />
** {{ic|auto}} picks a suitable mode automatically;<br />
** {{ic|max}} for highest available mode;<br />
** {{ic|keep}} (default) for the firmware selected mode.<br />
* {{ic|random-seed-mode}} - controls whether to read the random seed from the file {{ic|''esp''/loader/random-seed}}. If set to {{ic|with-system-token}} (default), it loads the seed from file only if the EFI variable {{ic|LoaderSystemToken}} is set; if set to {{ic|always}}, it loads the seed from file even if the EFI variable is unset; and if set to {{ic|off}}, the file is ignored.<br />
For a detailed explanation of the available settings and their corresponding arguments see the {{man|5|loader.conf}} manual. A loader configuration example is provided below:<br />
<br />
{{hc|''esp''/loader/loader.conf|<br />
default arch.conf<br />
timeout 4<br />
console-mode max<br />
editor no<br />
}}<br />
<br />
{{Tip|<br />
* {{ic|default}} and {{ic|timeout}} can be changed in the boot menu itself and changes will be stored as EFI variables {{ic|LoaderEntryDefault}} and {{ic|LoaderConfigTimeout}}, overriding these options. <br />
* {{ic|bootctl set-default ""}} can be used to clear the EFI variable overriding the {{ic|default}} option.<br />
* A basic loader configuration file is located at {{ic|/usr/share/systemd/bootctl/loader.conf}}.}}<br />
<br />
=== Adding loaders ===<br />
<br />
''systemd-boot'' will search for boot menu items in {{ic|''esp''/loader/entries/*.conf}} and additionally in {{ic|boot/loader/entries/*.conf}} if using [[#Installation using XBOOTLDR|XBOOTLDR]].<br />
The possible options are:<br />
<br />
* {{ic|title}} – operating system name. '''Required.'''<br />
* {{ic|version}} – kernel version, shown only when multiple entries with same title exist. Optional.<br />
* {{ic|machine-id}} – machine identifier from {{ic|/etc/machine-id}}, shown only when multiple entries with same title and version exist. Optional.<br />
* {{ic|efi}} – EFI program to start, relative to your ESP ({{ic|''esp''}}); e.g. {{ic|/vmlinuz-linux}}. '''Either''' this parameter or {{ic|linux}} (see below) is '''required'''.<br />
* {{ic|options}} – command line options to pass to the EFI program or [[kernel parameters]]. Optional, but you will need at least {{ic|1=root=''dev''}} if booting Linux. This parameter can be omitted if the root partition is assigned the correct Root Partition Type GUID as defined in [https://systemd.io/DISCOVERABLE_PARTITIONS/ Discoverable Partitions Specification] and if the {{ic|systemd}} [[mkinitcpio]] hook is present.<br />
<br />
For Linux boot, you can also use {{ic|linux}} instead of {{ic|efi}}. Or {{ic|initrd}} in addition to {{ic|options}}. The syntax is:<br />
* {{ic|linux}} and {{ic|initrd}} followed by the relative path of the corresponding files in the ESP; e.g. {{ic|/vmlinuz-linux}}; this will be automatically translated into {{ic|efi ''path''}} and {{ic|1=options initrd=''path''}} – this syntax is only supported for convenience and has no differences in function.<br />
<br />
{{Note|If {{ic|options}} is present in a boot entry and [[Secure Boot]] is disabled, the value of {{ic|options}} will override any {{ic|.cmdline}} string embedded in the EFI image that is specified by {{ic|efi}} or {{ic|linux}} (see [[#Preparing a unified kernel image]]). With Secure Boot, however, {{ic|options}} (and any edits made to the kernel command line in the bootloader UI) will be ignored, and only the embedded {{ic|.cmdline}} will be used. }}<br />
<br />
An example of a loader file to launch Arch from a partition with the label ''arch_os'' and loading the Intel CPU [[microcode]] is:<br />
{{hc|''esp''/loader/entries/arch.conf|2=<br />
title Arch Linux<br />
linux /vmlinuz-linux<br />
initrd /intel-ucode.img<br />
initrd /initramfs-linux.img<br />
options root="LABEL=''arch_os''" rw}}<br />
<br />
''systemd-boot'' will automatically check at boot time for '''Windows Boot Manager''' at the location {{ic|/EFI/Microsoft/Boot/Bootmgfw.efi}}, '''EFI Shell''' {{ic|/shellx64.efi}} and '''EFI Default Loader''' {{ic|/EFI/BOOT/bootx64.efi}}, as well as specially prepared kernel files found in {{ic|/EFI/Linux/}}. When detected, corresponding entries with titles {{ic|auto-windows}}, {{ic|auto-efi-shell}} and {{ic|auto-efi-default}}, respectively, will be generated. These entries do not require manual loader configuration. However, it does not auto-detect other EFI applications (unlike [[rEFInd]]), so for booting the Linux kernel, manual configuration entries must be created.<br />
<br />
{{Note|<br />
* If you dual-boot Windows, it is strongly recommended to disable its default [[Dual boot with Windows#Fast Startup and hibernation|Fast Startup]] option.<br />
* If you have an Intel or AMD CPU, load the ''microcode'' with {{ic|initrd}} before other images, an example is provided in [[Microcode#systemd-boot]].<br />
* The root partition can be identified with its {{ic|LABEL}}, {{ic|PARTUUID}} or {{ic|UUID}} (see [[Persistent block device naming]]). This is required only to identify the root partition, not the {{ic|''esp''}}.<br />
}}<br />
<br />
{{Tip|<br />
* The available boot entries which have been configured can be listed with the command {{ic|bootctl list}}.<br />
* An example entry file is located at {{ic|/usr/share/systemd/bootctl/arch.conf}}.<br />
* The [[kernel parameters]] for scenarios such as [[LVM]], [[LUKS]] or [[dm-crypt]] can be found on the relevant pages.<br />
}}<br />
<br />
==== EFI Shells or other EFI apps ====<br />
<br />
In case you installed [[Unified Extensible Firmware Interface#UEFI Shell|EFI shells]] and [[rEFInd#Tools|other EFI application]] into the ESP, you can use the following snippets.<br />
<br />
{{Note|The file path parameter for the {{ic|efi}} line is relative to your ''esp'' mount point. If you are mounted on {{ic|/boot}} and your EFI binaries reside at {{ic|/boot/EFI/xx.efi}} and {{ic|/boot/yy.efi}}, then you would specify the parameters as {{ic|efi /EFI/xx.efi}} and {{ic|efi /yy.efi}} respectively.}}<br />
<br />
Examples of loading custom UEFI Shell loaders:<br />
<br />
{{hc|''esp''/loader/entries/uefi-shell-v1-x86_64.conf|<br />
title UEFI Shell x86_64 v1<br />
efi /EFI/shellx64_v1.efi<br />
}}<br />
<br />
{{hc|''esp''/loader/entries/uefi-shell-v2-x86_64.conf|<br />
title UEFI Shell x86_64 v2<br />
efi /EFI/shellx64_v2.efi<br />
}}<br />
<br />
=== Booting into EFI Firmware Setup ===<br />
<br />
Most system firmware configured for EFI booting will add its own [[efibootmgr]] entries to boot into UEFI Firmware Setup.<br />
<br />
=== Support hibernation ===<br />
<br />
See [[Suspend and hibernate]].<br />
<br />
=== Kernel parameters editor with password protection ===<br />
<br />
Alternatively you can install {{AUR|systemd-boot-password}} which supports {{ic|password}} basic configuration option. Use {{ic|sbpctl generate}} to generate a value for this option.<br />
<br />
Install ''systemd-boot-password'' with the following command:<br />
<br />
{{bc|1=# sbpctl install ''esp''}}<br />
<br />
With enabled editor you will be prompted for your password before you can edit kernel parameters.<br />
<br />
== Keys inside the boot menu ==<br />
<br />
The following keys are used inside the menu:<br />
* {{ic|Up/Down}} - select entry<br />
* {{ic|Enter}} - boot the selected entry<br />
* {{ic|d}} - select the default entry to boot (stored in a non-volatile EFI variable)<br />
* {{ic|-/T}} - decrease the timeout (stored in a non-volatile EFI variable)<br />
* {{ic|+/t}} - increase the timeout (stored in a non-volatile EFI variable)<br />
* {{ic|e}} - edit the kernel command line. It has no effect if the {{ic|editor}} config option is set to {{ic|0}}.<br />
* {{ic|v}} - show the systemd-boot and UEFI version<br />
* {{ic|Q}} - quit<br />
* {{ic|P}} - print the current configuration<br />
* {{ic|h/?}} - help<br />
<br />
These hotkeys will, when pressed inside the menu or during bootup, directly boot<br />
a specific entry:<br />
<br />
* {{ic|l}} - Linux<br />
* {{ic|w}} - Windows<br />
* {{ic|a}} - OS X<br />
* {{ic|s}} - EFI Shell<br />
* {{ic|1-9}} - number of entry<br />
<br />
== Tips and tricks ==<br />
<br />
=== Choosing next boot ===<br />
<br />
The boot manager is integrated with the systemctl command, allowing you to choose what option you want to boot after a reboot. For example, suppose you have built a custom kernel and created an entry file {{ic|''esp''/loader/entries/arch-custom.conf}} to boot into it, you can just launch<br />
<br />
$ systemctl reboot --boot-loader-entry=arch-custom<br />
<br />
and your system will reboot into that entry maintaining the default option intact for subsequent boots. To see a list of possible entries pass the {{ic|--help}} option.<br />
<br />
If you want to boot into the firmware of your motherboard directly, then you can use this command:<br />
<br />
$ systemctl reboot --firmware-setup<br />
<br />
=== Preparing a unified kernel image ===<br />
<br />
systemd-boot searches in {{ic|''esp''/EFI/Linux/}} for [https://systemd.io/BOOT_LOADER_SPECIFICATION#type-2-efi-unified-kernel-images unified kernel images], which bundle the kernel, the init RAM disk (initrd), the kernel command line, {{ic|/etc/os-release}}, and a splash image into one single file. This file can be easily signed for [[Secure Boot]].<br />
<br />
Put the kernel command line you want to use in a file, and create the bundle file like this:<br />
<br />
{{bc|1=<br />
$ objcopy \<br />
--add-section .osrel="/usr/lib/os-release" --change-section-vma .osrel=0x20000 \<br />
--add-section .cmdline="kernel-command-line.txt" --change-section-vma .cmdline=0x30000 \<br />
--add-section .splash="/usr/share/systemd/bootctl/splash-arch.bmp" --change-section-vma .splash=0x40000 \<br />
--add-section .linux="vmlinuz-file" --change-section-vma .linux=0x2000000 \<br />
--add-section .initrd="initrd-file" --change-section-vma .initrd=0x3000000 \<br />
"/usr/lib/systemd/boot/efi/linuxx64.efi.stub" "''linux''.efi"<br />
}}<br />
<br />
Optionally [[Secure Boot#Signing EFI binaries|sign]] the {{ic|''linux''.efi}} file produced above.<br />
<br />
Copy {{ic|''linux''.efi}} into {{ic|''esp''/EFI/Linux/}}.<br />
<br />
=== Grml on ESP ===<br />
<br />
{{Note|The following instructions are not exclusive to Grml. With slight adjustments, installing other software (e.g., [http://www.system-rescue-cd.org/ SystemRescueCD]) is possible.}}<br />
<br />
[https://grml.org/ Grml] is a small live system with a collection of software for system administration and rescue.<br />
<br />
In order to install Grml on the ESP, we only need to copy the kernel {{ic|vmlinuz}}, the initramfs {{ic|initrd.img}}, and the squashed image {{ic|grml64-small.squashfs}} from the iso file to the ESP. To do so, first download [https://grml.org/ grml64-small.iso] and mount the file (the mountpoint is henceforth denoted ''mnt''); the kernel and initramfs are located in {{ic|''mnt''/boot/grml64small/}}, and the squashed image resides in {{ic|''mnt''/live/grml64-small/}}.<br />
<br />
Next, create a directory for Grml in your ESP,<br />
<br />
# mkdir -p ''esp''/grml<br />
<br />
and copy the above-mentioned files in there:<br />
<br />
# cp ''mnt''/boot/grml64small/vmlinuz ''esp''/grml<br />
# cp ''mnt''/boot/grml64small/initrd.img ''esp''/grml<br />
# cp ''mnt''/live/grml64-small/grml64-small.squashfs ''esp''/grml<br />
<br />
In the last step, create an entry for the systemd-boot loader: In {{ic|''esp''/loader/entries}} create a {{ic|grml.conf}} file with the following content:<br />
<br />
{{hc|''esp''/loader/entries/grml.conf|2=<br />
title Grml Live Linux<br />
linux /grml/vmlinuz<br />
initrd /grml/initrd.img<br />
options apm=power-off boot=live live-media-path=/grml/ nomce net.ifnames=0}}<br />
<br />
For an overview of the avialable boot options, consult the [http://git.grml.org/?p=grml-live.git;a=blob_plain;f=templates/GRML/grml-cheatcodes.txt;hb=HEAD cheatcode for Grml].<br />
<br />
=== systemd-boot on BIOS systems ===<br />
<br />
If you need a bootloader for BIOS systems that follows [https://systemd.io/BOOT_LOADER_SPECIFICATION/ The Boot Loader Specification], then systemd-boot can be pressed into service on BIOS systems. The [[Clover]] boot loader supports booting from BIOS systems and provides a simulated EFI environment.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Installing after booting in BIOS mode ===<br />
<br />
{{Warning|This is not recommended.}}<br />
<br />
If booted in BIOS mode, you can still install ''systemd-boot'', however this process requires you to tell firmware to launch ''systemd-boot'''s EFI file at boot, usually via two ways:<br />
* you have a working EFI Shell somewhere else.<br />
* your firmware interface provides a way of properly setting the EFI file that needs to be loaded at boot time.<br />
<br />
If you can do it, the installation is easier: go into your EFI Shell or your firmware configuration interface and change your machine's default EFI file to {{ic|''esp''/EFI/systemd/systemd-bootx64.efi}} (or {{ic|systemd-bootia32.efi}} depending if your system firmware is 32 bit).<br />
<br />
{{Note|The firmware interface of Dell Latitude series provides everything you need to setup EFI boot but the EFI Shell won't be able to write to the computer's ROM.}}<br />
<br />
=== Manual entry using efibootmgr ===<br />
<br />
If the {{ic|bootctl install}} command failed, you can create a EFI boot entry manually using {{Pkg|efibootmgr}}:<br />
<br />
# efibootmgr --create --disk /dev/sd''X'' --part ''Y'' --loader "\EFI\systemd\systemd-bootx64.efi" --label "Linux Boot Manager" --verbose<br />
<br />
where {{ic|/dev/sd''XY''}} is the [[EFI system partition]].<br />
<br />
{{Note|The path to the EFI image must use the backslash ({{ic|\}}) as the separator}}<br />
<br />
=== Manual entry using bcdedit from Windows ===<br />
<br />
If for any reason you need to create an EFI boot entry from Windows, you can use the following commands from an Administrator prompt:<br />
<br />
# bcdedit /copy {bootmgr} /d "Linux Boot Manager"<br />
# bcdedit /set {guid} path \EFI\systemd\systemd-bootx64.efi<br />
<br />
Replace {{ic|{guid} }} with the id returned by the first command. You can also set it as the default entry using<br />
<br />
# bcdedit /default {guid}<br />
<br />
=== Menu does not appear after Windows upgrade ===<br />
<br />
See [[UEFI#Windows changes boot order]].<br />
<br />
== See also ==<br />
<br />
* https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/<br />
* https://github.com/systemd/systemd/tree/master/src/boot/efi<br />
* https://bbs.archlinux.org/viewtopic.php?id=254374<br />
* https://systemd.io/BOOT_LOADER_SPECIFICATION/</div>Jwh7https://wiki.archlinux.org/index.php?title=Openbox&diff=564131Openbox2019-01-20T19:17:53Z<p>Jwh7: /* Window Decorations */ add file reference</p>
<hr />
<div>[[Category:Stacking WMs]]<br />
[[cs:Openbox]]<br />
[[de:Openbox]]<br />
[[el:Openbox]]<br />
[[es:Openbox]]<br />
[[fr:Openbox]]<br />
[[it:Openbox]]<br />
[[ja:Openbox]]<br />
[[ko:Openbox]]<br />
[[lt:Openbox]]<br />
[[nl:Openbox]]<br />
[[pl:Openbox]]<br />
[[ru:Openbox]]<br />
[[sk:Openbox]]<br />
[[sr:Openbox]]<br />
[[zh-hans:Openbox]]<br />
[[zh-hant:Openbox]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Xdg-menu}}<br />
{{Related|Oblogout}}<br />
{{Related articles end}}<br />
<br />
[http://openbox.org/wiki/Main_Page Openbox] is a lightweight, powerful, and highly configurable ''stacking'' [[window manager]] with extensive standards support. It may be built upon and run independently as the basis of a unique [[desktop environment]], or within other integrated desktop environments such as [[KDE]] and [[Xfce]], as an alternative to the window managers they provide. The [[LXDE]] desktop environment is itself built around Openbox.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|openbox}} package.<br />
<br />
== Starting ==<br />
<br />
=== Standalone ===<br />
<br />
Run {{ic|openbox}} or {{ic|openbox-session}} with [[xinit]]. Note that only {{ic|openbox-session}} provides [[#Autostart]].<br />
<br />
{{Note|After executing openbox-session, there is only a blank grey screen. Try to move your mouse and '''right click''' to get an openbox menu to make sure that it is actually working.}}<br />
<br />
=== Other desktop environments ===<br />
<br />
{{Note|<br />
* When replacing the native window manager of a [[desktop environment]] with Openbox, keep in mind that Openbox does not provide any compositing effects (such as transparency). See [[#Compositing effects]].<br />
* Openbox does work with GNOME applications (but see [[GTK+#Client-side decorations]]). [http://comments.gmane.org/gmane.comp.window-managers.openbox/6595]}}<br />
<br />
See [[Desktop environment#Use a different window manager]].<br />
<br />
== Configuration==<br />
<br />
{{Note|Local configuration files will always override global equivalents.}}<br />
<br />
Four key files form the basis of the [http://openbox.org/wiki/Configuration openbox configuration], each serving a unique role. They are: {{ic|rc.xml}}, {{ic|menu.xml}}, {{ic|autostart}}, and {{ic|environment}}. Although these files are discussed in more detail below, to start configuring Openbox, it will first be necessary to create a '''local''' Openbox profile (i.e for your specific user account) based on them. This can be done by copying them from the '''global''' {{ic|/etc/xdg/openbox}} profile (applicable to any and all users) as a template:<br />
<br />
$ cp -R /etc/xdg/openbox ~/.config/<br />
<br />
=== rc.xml ===<br />
<br />
{{Tip|Custom keyboard shortcuts (keybindings) must be added to the {{ic|<keyboard>}} section of this file, and underneath the {{ic|<nowiki><!-- Keybindings for running aplications --></nowiki>}} heading.}}<br />
<br />
{{ic|~/.config/openbox/rc.xml}} is the main configuration file, responsible for determining the behaviour and settings of the overall session, including:<br />
<br />
* Keyboard shortcuts (e.g. starting applications; controlling the volume)<br />
* Theming<br />
* Desktop and Virtual desktop settings, and<br />
* Application Window settings<br />
<br />
This file is also pre-configured, meaning that it will only be necessary to amend existing content in order to customise behaviour to suit personal preference.<br />
<br />
{{Note|Per-application settings pertaining to fixed placement of applications per monitor will only work if the x & y position have also been defined.}}<br />
<br />
=== menu.xml ===<br />
<br />
{{ic|~/.config/openbox/menu.xml}} defines the type and behaviour of the desktop menu, accessable by right-clicking the background. Although the default provided is a '''static menu''' (meaning that it will not automatically update when new applications are installed), it is possible to employ the use of '''dynamic menus''' that will automatically update as well. <br />
<br />
The available options are discussed extensively below in the [[#Menus]] section.<br />
<br />
=== Autostart ===<br />
<br />
{{ic|openbox-session}} provides two autostart mechanisms: [[XDG Autostart]] (which only works if {{Pkg|python2-xdg}} is installed) and [http://openbox.org/wiki/Help:Autostart Openbox's own autostart mechanism].<br />
<br />
Openbox's own autostart mechanism:<br />
<br />
* sources {{ic|/etc/xdg/openbox/environment}}<br />
* sources {{ic|~/.config/openbox/environment}}<br />
* runs {{ic|/etc/xdg/openbox/autostart}}<br />
* runs {{ic|~/.config/openbox/autostart}}<br />
<br />
Issues regarding commands in {{ic|~/.config/openbox/autostart}} being executed out of order (or skipped altogether) are often resolved by the addition of small delays. For instance:<br />
<br />
xset -b<br />
(sleep 3s && nm-applet) &<br />
(sleep 3s && conky) &<br />
<br />
=== environment ===<br />
<br />
{{ic|~/.config/openbox/environment}} can be used to export and set relevant environmental variables such as to:<br />
<br />
* Define new pathways (e.g. execute commands that would otherwise require the entire pathway to be listed with them)<br />
* Change language settings, and<br />
* Define other variables to be used (e.g. the fix for GTK theming could be listed here)<br />
<br />
=== Themes ===<br />
<br />
Install {{Pkg|obconf}} and {{Pkg|lxappearance-obconf}} for a GUI to configure visual settings and theming.<br />
<br />
A good selection of themes are available in the {{Pkg|openbox-themes}} package or the [[AUR]]. Some [[GTK+#Themes]] come with an Openbox theme as well. Both Openbox-specific and Openbox-compatible themes will be installed to the {{ic|/usr/share/themes}} directory and will also be immediately available for selection.<br />
<br />
[https://www.box-look.org/browse/ord/latest/ box-look.org] is an excellent and well-established source of themes. [http://www.deviantart.com/ deviantART.com] is another excellent resource. Many more can be found online.<br />
<br />
==== Edit or create ====<br />
<br />
{{Tip|It's better to copy a theme to your home directory than to edit those found in {{ic|/usr/share/themes/}}. This will retain the original should anything go wrong and ensure that your changes are not overwritten on update.}}<br />
<br />
The process of creating new or modifying existing themes is covered extensively at the official [http://openbox.org/wiki/Help:Themes openbox.org] website. {{AUR|obtheme}} is a user-friendly GUI for doing so.<br />
<br />
=== GUI configuration ===<br />
<br />
Several GUI applications are available to quickly and easily configure your Openbox desktop.<br />
<br />
* {{App|ObConf|A GTK2 based configuration tool for the Openbox window manager.|http://openbox.org/wiki/ObConf:About|{{Pkg|obconf}}}}<br />
* {{App|LXAppearance ObConf|Plugin for LXAppearance to configure Openbox. Note that not all options to configure Openbox are available in this plugin, so you might want to install obconf anyway.|http://lxde.org|{{Pkg|lxappearance-obconf}}}}<br />
* {{App|LXInput|LXDE keyboard and mouse configuration|http://lxde.org|{{Pkg|lxinput}}}}<br />
* {{App|LXRandR|LXDE monitor configuration.|http://wiki.lxde.org/en/LXRandR|{{Pkg|lxrandr}}}}<br />
* {{App|obkey|Configure Openbox keyboard shortcuts|https://code.google.com/p/obkey/|{{AUR|obkey}}}} <br />
* {{App|ob-autostart|A simple autostart application for Openbox.|http://pastebin.com/012YgXTk|{{AUR|ob-autostart}}}} <br />
* {{App|obapps|Graphical tool for configuring application settings in Openbox.|https://sourceforge.net/projects/obapps/|{{AUR|obapps}}}} <br />
<br />
Programs and applications relating to the configuration of Openbox's desktop menu are discussed in the [[#Menus|Menus]] section.<br />
<br />
== Openbox reconfiguration ==<br />
<br />
{{Tip|where not already present, it would be worthwhile adding this command to a menu and/or as a keybind for convenience.}}<br />
<br />
Openbox will not always automatically reflect any changes made to its configuration files within a session. As a consequence, it will be necessary to manually reload those files after they have been edited. To do so, enter the following command:<br />
<br />
$ openbox --reconfigure<br />
<br />
Where intending to add this command as a keybind to {{ic|~/.config/openbox/rc.xml}}, it will only be necessary to list the command as {{ic|reconfigure}}. An example has been provided below, using the {{ic|Super}}+{{ic|F11}} keybind:<br />
<br />
<keybind key="W-F11"><br />
<action name="Reconfigure"/><br />
</keybind><br />
<br />
== Keybinds ==<br />
<br />
All keybinds must be added to the {{ic|~/.config/openbox/rc.xml}} file, and below the {{ic|<nowiki><!-- Keybindings for running aplications --></nowiki>}} heading. Although a brief overview has been provided here, a more in-depth explanation of keybindings can be found at [http://openbox.org/wiki/Help:Bindings openbox.org]. <br />
<br />
Keybinds can be added to the configuration file using the following syntax:<br />
<br />
<keybind key="'''my-key-combination'''"><br />
<action name="'''my-action'''"><br />
'''...'''<br />
</action><br />
</keybind><br />
<br />
The action name for running an external command is ''Execute''. Use the following syntax to define an external command to execute:<br />
<br />
<action name="Execute"><br />
<command>'''my-command'''</command><br />
</action><br />
<br />
See [http://openbox.org/wiki/Help:Actions the Openbox wiki] for a list of all available actions.<br />
<br />
{{Tip|The {{AUR|obkey}} utility provides a graphical interface for configuring key bindings. Before using ''obkey'', you should use ''obconf'' to create {{ic|~/.config/openbox/rc.xml}}.}}<br />
<br />
While the use of standard alpha-numeric keys for keybindings is self-explanatory, special names are assigned to other types of keys, such as {{ic|modifiers}}, {{ic|multimedia}} and {{ic|navigation}}.<br />
<br />
=== Modifiers ===<br />
<br />
{{ic|Modifier}} keys play an important role in keybindings (e.g. holding down the {{ic|shift}} or {{ic|CTRL / control}} key in combination with another key to undertake an action). Using modifiers helps to prevent conflicting keybinds, whereby two or more actions are linked to the same key or combination of keys. The syntax to use a modifier with another key is:<br />
<br />
"<modifier>-<key>"<br />
<br />
The modifier codes are as follows:<br />
<br />
* {{ic|S}}: Shift<br />
* {{ic|C}}: Control / CTRL<br />
* {{ic|A}}: Alt<br />
* {{ic|W}}: Super / Windows<br />
* {{ic|M}}: Meta<br />
* {{ic|H}}: Hyper (If it is bound to something)<br />
<br />
=== Multimedia keys ===<br />
<br />
Where available, it is possible to set the appropriate {{ic|multimedia}} keys to perform their intended functions, such as to control the volume and/or the screen brightness. These will usually be integrated into the {{ic|function}} keys, and are identified by their appropriate symbols. See [[Extra keyboard keys]] for details.<br />
<br />
The volume and brightness multimedia codes are as follows (note that commands will still have to be assigned to them to actually function):<br />
<br />
* {{ic|XF86AudioRaiseVolume}}: Increase volume<br />
* {{ic|XF86AudioLowerVolume}}: Decrease volume<br />
* {{ic|XF86AudioMute}}: Mute / unmute volume<br />
* {{ic|XF86MonBrightnessUp}}: Increase screen brightness<br />
* {{ic|XF86MonBrightnessDown}}: Decrease screen brightness<br />
<br />
For a full list of XF86 multimedia keys, see the [http://wiki.linuxquestions.org/wiki/XF86_keyboard_symbols LinuxQuestions wiki].<br />
<br />
==== Volume control ====<br />
<br />
What commands should be used for controlling the volume will depend on whether [[ALSA]], [[PulseAudio]], or [[OSS]] is used for sound.<br />
<br />
*ALSA: see [[Advanced Linux Sound Architecture#Keyboard volume control]].<br />
*PulseAudio: see [[PulseAudio#Keyboard volume control]]<br />
*OSS: see [[OSS#Using multimedia keys with OSS]].<br />
<br />
=== Navigation keys ===<br />
<br />
These are the directional / arrow keys, usually used to move the cursor up, down, left, or right. The (self-explanatory) navigation codes are as follows:<br />
<br />
* {{ic|Up}}: Up<br />
* {{ic|Down}}: Down<br />
* {{ic|Left}}: Left<br />
* {{ic|Right}}: Right<br />
<br />
== Menus ==<br />
<br />
It is possible to employ three types of menu in Openbox: {{ic|static}}, {{ic|pipes}} (dynamic), and {{ic|generators}} (static or dynamic). They may also be used alone or in any combination.<br />
<br />
=== Static ===<br />
<br />
As the name would suggest, this default type of menu does not change in any way, and may be manually edited and/or (re)generated automatically through the use on an appropriate software package.<br />
<br />
Fast and efficient, while this type of menu can be used to select applications, it can also be useful to access specific functions and/or perform specific tasks (e.g. desktop configuration), leaving the access of applications to another process (e.g. the {{Pkg|synapse}} or {{Pkg|xfce4-appfinder}} applications).<br />
<br />
The {{ic|~/.config/openbox/menu.xml}} file will be the sole source of static desktop menu content.<br />
<br />
==== menumaker ====<br />
<br />
{{Pkg|menumaker}} automatically generates {{ic|xml}} menus for several window managers, including Openbox, [[Fluxbox]], [[IceWM]] and [[Xfce]]. It will search for all installed executable programs and consequently create a menu file for them. It is also possible to configure MenuMaker to exclude certain application types (e.g. relating to [[GNOME]] or [[KDE]]), if desired.<br />
<br />
Once installed and executed, it will automatically generate a new {{ic|~/.config/openbox/menu.xml}} file. To avoid overwriting an existing file, enter:<br />
<br />
$ mmaker -v OpenBox3<br />
<br />
Otherwise, to overwrite an existing file, add the {{ic|force}} argument ({{ic|f}}):<br />
<br />
$ mmaker -vf OpenBox3<br />
<br />
Once a new {{ic|~/.config/openbox/menu.xml}} file has been generated it may then be manually edited, or configured using a GUI menu editor, such as {{Pkg|obmenu}}.<br />
<br />
==== obmenu ====<br />
<br />
{{Warning|{{ic|obm-xdg}} - a pipe menu to generate a list of [[GTK+]] and [[GNOME]] applications - is also provided with obmenu. However, it has long-running bugs whereby it may produce an invalid output, or even not function at all. Consequently it has been omitted from discussion.}}<br />
<br />
{{Pkg|obmenu}} is a "user-friendly" GUI application to edit {{ic|~/.config/openbox/menu.xml}}, without the need to code in {{ic|xml}}.<br />
<br />
==== xdg-menu ====<br />
<br />
{{Pkg|archlinux-xdg-menu}} will automatically generate a menu based on {{ic|xdg}} files contained within the {{ic|/etc/xdg/}} directory for numerous Window Managers, including Openbox. Review the [[Xdg-menu#OpenBox]] article for further information.<br />
<br />
==== logout menu options ====<br />
<br />
{{Tip|The commands provided can also be attached to [[#Keybinds|keybinds]].}}<br />
<br />
The {{ic|~/.config/openbox/menu.xml}} file can be edited in order to provide a sub-menu with the same options as provided by [[#oblogout|oblogout]]. The sample script below will provide all of these options, with the exception of the ability to lock the screen:<br />
<br />
<menu id="exit-menu" label="Exit"><br />
<item label="Log Out"><br />
<action name="Execute"><br />
<command>openbox --exit</command><br />
</action><br />
</item><br />
<item label="Shutdown"><br />
<action name="Execute"><br />
<command>systemctl poweroff</command><br />
</action><br />
</item><br />
<item label="Restart"><br />
<action name="Execute"><br />
<command>systemctl reboot</command><br />
</action><br />
</item><br />
<item label="Suspend"><br />
<action name="Execute"><br />
<command>systemctl suspend</command><br />
</action><br />
</item><br />
<item label="Hibernate"><br />
<action name="Execute"><br />
<command>systemctl hibernate</command><br />
</action><br />
</item><br />
</menu><br />
<br />
Once the entries have been composed, add the following line to present the sub-menu where desired within the main desktop menu (usually as the last entry):<br />
<br />
<menu id="exit-menu"/><br />
<br />
=== Pipes ===<br />
<br />
{{Tip|It is entirely feasible for a static menu to contain one or more pipe sub-menus. The functionality of some pipe menus may also rely on the installation of relevant software packages.}}<br />
<br />
This type of menu is in essence a script that provides dynamic, refreshed lists on-the-fly as and when run. These lists may be used for multiple purposes, including to list applications, to provide information, and to provide control functions. Pre-configured pipe menus can be installed, although not from the [[official repositories]]. More experienced users can also modify and/or create their own custom scripts. Again, {{ic|~/.config/openbox/menu.xml}} may and commonly will contain several pipe menus.<br />
<br />
==== Examples ====<br />
<br />
* {{AUR|openbox-xdgmenu}}: fast xdg-menu converter to xml-pipe-menu<br />
* {{AUR|obfilebrowser}}: Application and file browser<br />
* {{AUR|obdevicemenu}}: Management of removable media with [[Udisks]]<br />
* [https://bbs.archlinux.org/viewtopic.php?pid=1345031 wifi pipe menu]: Wireless networking using [[Netctl]]<br />
<br />
[http://openbox.org/wiki/Openbox:Pipemenus Openbox.org] also provides a further list of pipe menus.<br />
<br />
=== Generators ===<br />
<br />
This type of menu is akin to those provided by the taskbars of desktop environments such as [[Xfce]] or [[LXDE]]. Automatically updating on-the-fly, this type of menu can be powerful and very convenient. It may also be possible to add custom categories and menu entries; read the documentation for your intended dynamic menu to determine if and how this can be done.<br />
<br />
A menu generator will have to be executed from the {{ic|~/.config/openbox/menu.xml}} file.<br />
<br />
==== obmenu-generator ====<br />
<br />
{{Tip|icons can still be disabled in {{AUR|obmenu-generator}}, even where enabled in {{ic|~/.config/openbox/rc.xml}}.}}<br />
<br />
{{AUR|obmenu-generator}} is highly recommended despite being an unofficial package. With the ability to be used as a static or dynamic menu, it is highly configurable, powerful, and versatile. Menu categories and individual entries may also be easily hidden, customised, and/or added with ease. The [http://trizenx.blogspot.co.uk/2012/02/obmenu-generator.html official homepage] provides further information and screenshots.<br />
<br />
Below is an example of how obmenu-generator would be dynamically executed without icons in {{ic|~/.config/openbox/menu.xml}}:<br />
<br />
<?xml version="1.0" encoding="utf-8"?><br />
<openbox_menu><br />
<menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator"><br />
</menu><br />
</openbox_menu><br />
<br />
To automatically iconify entries, the {{ic|-i}} option would be added:<br />
<br />
<menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator -i"><br />
<br />
==== openbox-menu ====<br />
<br />
{{Tip|If this menu produces an error, it may be solved by enabling icons in {{ic|~/.config/openbox/rc.xml}}.}}<br />
<br />
{{AUR|openbox-menu}} uses the [[LXDE]] [http://sourceforge.net/projects/lxde/files/menu-cache/ menu-cache] to create dynamic menus. The [http://fabrice.thiroux.free.fr/openbox-menu_en.html official homepage] provides further information and screenshots.<br />
<br />
=== Menu icons ===<br />
<br />
To show icons next to menu entries, it will be necessary to ensure they are enabled in the {{ic|<menu>}} section of the {{ic|~/.config/openbox/rc.xml}} file:<br />
<br />
<applicationIcons>yes</applicationIcons><br />
<br />
Where using a static menu, it will then be necessary to edit the {{ic|~/.config/openbox/menu.xml}} file to provide both the {{ic|icon <nowiki>=</nowiki>}} command, along with the full path and icon name for each entry. An example of the syntax used to provide an icon for a category is:<br />
<br />
<menu id="apps-menu" label="[label name]" icon="[pathway to icon]/[icon name]"><br />
<br />
=== Desktop menu as a panel menu ===<br />
<br />
{{Tip|XDoTool can simulate any keybind for any action, and as such, it may therefore be used for many other purposes...}}<br />
<br />
{{Pkg|xdotool}} is a package that can issue commands to simulate key presses / keybinds, meaning that it is possible to use it to invoke keybind-related actions without having to actually press their assigned keys. As this includes the ability to invoke an assigned keybind for the Openbox desktop menu, it is therefore possible to use XDoTool to turn the Openbox desktop menu into a panel menu. Especially where the desktop menu is heavily customised and feature-rich, this may prove very useful to:<br />
<br />
* Replace an existing panel menu<br />
* Implement a panel menu where otherwise not provided or possible (e.g. for [[Tint2]])<br />
* Compensate where losing access to the desktop menu due to the use of an application like {{pkg|xfdesktop}} to manage the [[#Desktop icons and wallpapers|desktop]].<br />
<br />
Once XDoTool has been installed - if not already present - it will be necessary to create a keybind to access the root menu in {{ic|~/.config/openbox/rc.xml}}, and again below the {{ic|<nowiki><</nowiki>!-- Keybindings for running aplications --<nowiki>></nowiki>}} heading. For example, the following code will bring up the menu by pressing {{ic|CTRL}} + {{ic|m}}:<br />
<br />
<keybind key="C-m"><br />
<action name="ShowMenu"><br />
<menu>root-menu</menu><br />
</action><br />
</keybind><br />
<br />
Openbox must then be [[#Openbox reconfiguration|reconfigured]]. In this instance, XDoTool will be used to simulate the {{ic|CTRL}} + {{ic|m}} keypress to access the desktop menu with the following command (note the use of {{ic|+}} in place of {{ic|-}}):<br />
<br />
xdotool key control+m<br />
<br />
How this command may be used as a panel launcher / icon is largely dependent on the features of panel used. While some panels will allow the above command to be executed directly in the process of creating a new launcher, others may require the use of an executable script. As an example, a custom executable script called {{ic|obpanelmenu.sh}} will be created in the {{ic|~/.config}} folder:<br />
<br />
$ ''text editor'' ~/.config/obpanelmenu.sh<br />
<br />
Once the empty file has been opened, the appropriate XDoTool command must be added to the empty file (i.e. to simulate the {{ic|CTRL}} + {{ic|m}} keypress for this example):<br />
<br />
xdotool key control+m<br />
<br />
After the file has been saved and closed, it may then be made into an executable script with the following command:<br />
<br />
$ chmod +x ~/.config/obpanelmenu.sh<br />
<br />
Executing it will bring up the Openbox desktop menu. Consequently, where using a panel that supports drag-and-drop functionality to add new launchers, simply drag the executable script onto it before changing the icon to suit personal taste.<br />
<br />
=== XDG compliant menu ===<br />
<br />
A xdg compliant menu is based on the freedesktop.org standard. The menu is defined in menu-files which reside in /etc/xdg/menus. New applications will occur automatically in the menu.<br />
<br />
==== Examples ====<br />
<br />
* [https://github.com/mlde/californium californium]: xdg menu based on the LXQt main menu and easily themable<br />
<br />
== Tips and tricks ==<br />
<br />
=== Cursor and icon themes ===<br />
<br />
See [[Cursor themes]] and [[Icons]] for details.<br />
<br />
=== Desktop icons and wallpapers ===<br />
<br />
Openbox does not natively support the use of desktop icons or wallpapers.<br />
<br />
See [[PCManFM#Desktop management|PCManFM]], [[SpaceFM#Desktop management|SpaceFM]] and [[Idesk]].<br />
<br />
{{note|You may have to edit {{ic|~/.conkyrc}} and set {{ic|own_window_type}} to {{ic|normal}}.}}<br />
<br />
See [[List of applications#Wallpaper setters]].<br />
<br />
=== Compositing effects ===<br />
<br />
Openbox does not provide native support for [[Wikipedia:Compositing window manager|compositing]], and thus requires an external compositor for this purpose.<br />
<br />
Although compositing is not a necessary component, it may specifically avoid issues such as screen distortion with [[#oblogout|oblogout]], and visual glitches with terminal window transparency. See [[Xorg#Composite]] for common choices.<br />
<br />
=== oblogout ===<br />
<br />
See the [[Oblogout]] article for an overview on how to use this useful, graphical logout script.<br />
<br />
=== Openbox for multihead users ===<br />
<br />
While Openbox provides better than average multihead support on its own, {{AUR|openbox-multihead-git}} provides a development branch called '''Openbox Multihead''' that gives multihead users per-monitor desktops. This model is not commonly found in floating window managers, but exists mainly in tiling window managers. It is explained well on the [http://xmonad.org/tour.html#workspace Xmonad web site]. Also, please see [https://github.com/BurntSushi/openbox-multihead/blob/multihead/README.MULTIHEAD README.MULTIHEAD] for a more comprehensive description of the new features and configuration options found in Openbox Multihead.<br />
<br />
Openbox Multihead will function like normal Openbox when only a single head is available.<br />
<br />
A downside to using Openbox Multihead is that it breaks the EWMH assumption that one and only one desktop is visible at any time. Thus, existing pagers will not work well with it. To remedy this, you can install {{AUR|pager-multihead-git}}{{Broken package link|{{aur-mirror|pager-multihead-git}}}} alongside Openbox Multihead. It will work without Openbox Multihead if only one monitor is active.<br />
<br />
=== Launch a complex command with hotkey ===<br />
<br />
If you need to execute a complex command, use shell functionality.<br />
<br />
Special character replacement are as follows:<br />
<br />
* {{ic|&}}: &amp;amp;<br />
* {{ic|<}}: &amp;lt;<br />
* {{ic|>}}: &amp;gt;<br />
<br />
This example will turn off display immediately and lock screen with {{Pkg|slock}}. It was taken from [https://bbs.archlinux.org/viewtopic.php?pid=903057 this thread].<br />
<keybind key="W-l"><br />
<action name="Execute"><br />
<command>sh -c 'slock &amp;amp; (sleep .5 &amp;amp;&amp;amp; xset dpms force off)'</command><br />
</action><br />
</keybind><br />
<br />
Sometimes one need to specify environment variable for application:<br />
<keybind key="A-F7"><br />
<action name="Execute"><br />
<command>sh -c "LC_ALL=C obconf"</command><br />
</action><br />
</keybind><br />
<br />
Another example will launch application preserving all stdout and stderr output to file:<br />
<keybind key="A-f"><br />
<action name="Execute"><br />
<command>sh -c sh -c "exec gimp &amp;gt;/tmp/gimp.out 2&amp;gt;&amp;amp;1"</command><br />
</action><br />
</keybind><br />
<br />
=== Switch desktops using the mouse ===<br />
<br />
It is possible to switch desktop by moving the mouse cursor to the edges of the screen. First install {{Pkg|xdotool}} and add the following two lines to your {{ic|~/.xinitrc}}:<br />
<br />
xdotool behave_screen_edge --delay 500 left set_desktop --relative -- -1 &<br />
xdotool behave_screen_edge --delay 500 right set_desktop --relative -- +1 &<br />
<br />
=== Set default applications / file associations ===<br />
<br />
See the [[Default applications]] article.<br />
<br />
=== Ad-hoc window transparency ===<br />
<br />
{{Warning|This may not work where other actions are defined within the action group.}}<br />
The program {{Pkg|transset-df}} can enable window transparency on-the-fly.<br />
<br />
For example, using the following code in the {{ic|<mouse>}} section of the {{ic|~/.config/openbox/rc.xml}} file will enable control of application window transparency by hovering the mouse-pointer over the title bar and scrolling with the middle button:<br />
<br />
<context name="Titlebar"><br />
...<br />
<mousebind button="Up" action="Click"><br />
<action name= "Execute" ><br />
<execute>transset-df -p .2 --inc </execute><br />
</action><br />
</mousebind><br />
<mousebind button="Down" action="Click"><br />
<action name= "Execute" ><br />
<execute>transset-df -p .2 --dec </execute><br />
</action><br />
</mousebind><br />
...<br />
</context><br />
<br />
=== Using obxprop for faster configuration ===<br />
<br />
The {{Pkg|openbox}} package provides a {{ic|obxprop}} binary that can parse relevant values for applications settings in {{ic|rc.xml}}. Officially {{ic|<nowiki>obxprop | grep "^_OB_APP"</nowiki>}} is recommended for this task. Start the process by running the command shown, then click a window to see its properties in the terminal.<br />
<br />
=== Xprop values for applications ===<br />
<br />
{{Pkg|xorg-xprop}} can be used to relay property values for selected applications. Where frequently using per-application settings, the following [[Bash#Aliases|Bash Alias]] may be useful:<br />
dy:<br />
<br />
alias xp='xprop | grep "WM_WINDOW_ROLE\|WM_CLASS" && echo "WM_CLASS(STRING) = \"NAME\", \"CLASS\""'<br />
<br />
To use Xorg-XProp, run using the alias given {{ic|xp}}, and click on the active program desired to define with per-application settins. The results displayed will only be the information that Openbox itself requires, namely the {{ic|WM_WINDOW_ROLE}} and {{ic|WM_CLASS}} (name and class) values:<br />
<br />
WM_WINDOW_ROLE(STRING) = "roster"<br />
WM_CLASS(STRING) = "gajim.py", "Gajim.py"<br />
WM_CLASS(STRING) = "NAME", "CLASS"<br />
<br />
=== Switching between keyboard layouts ===<br />
<br />
See the article section [[Keyboard configuration in Xorg#Switching between keyboard layouts|switching between keyboard layouts]] for instructions.<br />
<br />
=== Set grid layout for virtual desktops ===<br />
<br />
Install {{AUR|obsetlayout}}. To set a 2x2 grid for example:<br />
<br />
obsetlayout 0 2 2 0<br />
<br />
Run it without arguments to know what the arguments mean.<br />
<br />
=== Enable Hot Corners ===<br />
<br />
[https://github.com/mlde/lead lead] provides hot corners for openbox and other lightweight window managers. Start the application with a entry in the autostart-file:<br />
<br />
mlde.lead &<br />
<br />
Commands can be edited in the configuration file {{ic|~/.config/mlde/lead.conf}}:<br />
<br />
[eDP1]<br />
bottom=<br />
bottomLeft=chromium<br />
bottomRight=thunar<br />
left=<br />
right=<br />
top=<br />
topLeft=mlde.californium toggle<br />
topRight=skippy-xd<br />
<br />
=== Window snapping ===<br />
<br />
Many desktop environments and window managers support ''window snapping'' (e.g. Windows 7 Aero snap), whereby they will automatically snap into place when moved to the edge of the screen. This effect can also be simulated in Openbox through the use of [[#Keybinds|keybinds]] on focused windows. <br />
<br />
As illustrated in the example below, percentages must be used to determine window sizes (see [http://openbox.org/wiki/Help:Actions openbox.org] for further information). In this instance, The {{ic|super}} key is used in conjunction with the {{ic|navigation}} keys:<br />
<br />
<keybind key="W-Left"><br />
<action name="UnmaximizeFull"/><br />
<action name="MaximizeVert"/><br />
<action name="MoveResizeTo"><br />
<width>50%</width><br />
</action><br />
<action name="MoveToEdge"><direction>west</direction></action><br />
</keybind><br />
<keybind key="W-Right"><br />
<action name="UnmaximizeFull"/><br />
<action name="MaximizeVert"/><br />
<action name="MoveResizeTo"><br />
<width>50%</width><br />
</action><br />
<action name="MoveToEdge"><direction>east</direction></action><br />
</keybind><br />
<br />
However, it should be noted that once a window has been 'snapped' to an edge, it will remain vertically maximised unless subsequently maximised and then restored. The solution is to implement additional keybinds - in this instance using the {{ic|down}} and {{ic|up}} keys - to do so. This will also make pulling 'snapped' windows from screen edges faster as well:<br />
<br />
<keybind key="W-Down"><br />
<action name="Unmaximize"/><br />
</keybind><br />
<keybind key="W-Up"><br />
<action name="Maximize"/><br />
</keybind><br />
<br />
This [http://ubuntuforums.org/showthread.php?t=1796793 Ubuntu forum thread] provides more information. Applications such as {{AUR|opensnap}} are also available to automatically simulate window snapping behaviour without the use of keybinds.<br />
Another option is to use {{AUR|bunsen-utilities-git}} which provides {{ic|bl-aerosnap --left}} and {{ic|bl-aerosnap --right}} commands which will snap active window on left or right edge respectively if it's not snapped and restore it to original size and position otherwise. Just bind these commands to the key combination of your choosing.<br />
<br />
=== Smooth display manager transition ===<br />
<br />
{{Note|This has been confirmed to work with [[LightDM]].}}<br />
<br />
Users of display managers might experience a flickering during the transition between the display manager and the Openbox desktop. The flickering comes from Openbox setting the root window's color during startup. Therefore there's a brief moment when the display flashes in a grey color, between the display manager's background and the desktop's wallpaper.<br />
<br />
Setting the root window's background color can be disabled by editing the Openbox startup script found in {{ic|/usr/lib/openbox/openbox-autostart}}. Simply comment out (or delete) the block starting with {{ic|# Set a background color}}.<br />
<br />
{{Note|Users who don't specifically set their wallpaper will "inherit" the display manager's background automatically if they disable the root window color adjustment.}}<br />
<br />
=== Window Decorations ===<br />
<br />
To remove window decorations for all or particular applications, use the ''<decor>'' option in the ''<applications>'' section of ''rc.xml'' (user: ''~/.config/openbox/'' or system: ''/etc/xdg/openbox/'').<br><br />
Example for Firefox, including variants like Firefox-Beta and Firefox-Nightly:<br />
<application class="Firefox*"><br />
<decor>no</decor><br />
</application><br />
One could also disable decorations for all applications (using class '''"*"'''), then enable them (using '''yes''') for individual ones. To apply the changes, restart your desktop session, and thus Openbox. Reference: [http://openbox.org/wiki/Help:FAQ#How_do_I_remove_the_decorations_from_all_my_windows.3F Openbox FAQ]<br />
<br />
== Troubleshooting ==<br />
<br />
=== Firefox ===<br />
<br />
Mozilla based browsers may ignore application rules (e.g. {{ic|<desktop>}}) unless {{ic|1=class="Firefox"}} is used. See [[#Xprop values for applications]].<br />
<br />
=== Missing themes ===<br />
<br />
If for any reason the newly extracted theme cannot be selected, open the theme directory to first ensure that it is compatible with Openbox - there should be an {{ic|openbox-3}} directory and a {{ic|themerc}} file within it. An {{ic|.obt}} ('''O'''pen'''B'''ox '''T'''heme) file may also be present in some instances, which can then be manually loaded in {{Pkg|obconf}}.<br />
<br />
A theme may also be not accessible due to wrong permissions. See [[File permissions and attributes]] for more.<br />
<br />
=== Stop continuous desktop switching ===<br />
<br />
By default Openbox switches from the last desktop back to the first desktop on mouse wheel scroll. Use {{ic|<wrap>no</wrap>}} in the {{ic|mousebind}} section to disable this behaviour.<br />
<br />
<context name="Desktop"><br />
<mousebind button="Up" action="Click"><br />
<action name="GoToDesktop"><br />
<to>previous</to><br />
<wrap>no</wrap><br />
</action><br />
</mousebind><br />
<mousebind button="Down" action="Click"><br />
<action name="GoToDesktop"><br />
<to>next</to><br />
<wrap>no</wrap><br />
</action><br />
</mousebind><br />
</context><br />
<br />
=== Windows load behind the active window ===<br />
<br />
Some application windows (such as Firefox windows) may load behind the currently active window, causing you to need to switch to the window you just created to focus it. To fix this behavior add this to your {{ic|~/.config/openbox/rc.xml}} file, inbetween the {{ic|1=<openbox_config>}} and {{ic|1=</openbox_config>}} tags:<br />
<br />
{{bc|1=<br />
<applications><br />
<application class="*"><br />
<focus>yes</focus><br />
</application><br />
</applications><br />
}}<br />
<br />
== See also ==<br />
<br />
* [http://openbox.org/ Openbox Website] - Official website<br />
* [http://www.box-look.org/ Box-Look.org] - A good resource for themes and related artwork<br />
* [https://bbs.archlinux.org/viewtopic.php?id=93126 Openbox Hacks and Configs Thread] @ Arch Linux Forums<br />
* [https://bbs.archlinux.org/viewtopic.php?id=45692 Openbox Screenshots Thread] @ Arch Linux Forums<br />
* [http://urukrama.wordpress.com/openbox-guide/ An Openbox guide]</div>Jwh7https://wiki.archlinux.org/index.php?title=Openbox&diff=564130Openbox2019-01-20T19:07:53Z<p>Jwh7: /* Tips and tricks */ - add Window Decorations section</p>
<hr />
<div>[[Category:Stacking WMs]]<br />
[[cs:Openbox]]<br />
[[de:Openbox]]<br />
[[el:Openbox]]<br />
[[es:Openbox]]<br />
[[fr:Openbox]]<br />
[[it:Openbox]]<br />
[[ja:Openbox]]<br />
[[ko:Openbox]]<br />
[[lt:Openbox]]<br />
[[nl:Openbox]]<br />
[[pl:Openbox]]<br />
[[ru:Openbox]]<br />
[[sk:Openbox]]<br />
[[sr:Openbox]]<br />
[[zh-hans:Openbox]]<br />
[[zh-hant:Openbox]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Xdg-menu}}<br />
{{Related|Oblogout}}<br />
{{Related articles end}}<br />
<br />
[http://openbox.org/wiki/Main_Page Openbox] is a lightweight, powerful, and highly configurable ''stacking'' [[window manager]] with extensive standards support. It may be built upon and run independently as the basis of a unique [[desktop environment]], or within other integrated desktop environments such as [[KDE]] and [[Xfce]], as an alternative to the window managers they provide. The [[LXDE]] desktop environment is itself built around Openbox.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|openbox}} package.<br />
<br />
== Starting ==<br />
<br />
=== Standalone ===<br />
<br />
Run {{ic|openbox}} or {{ic|openbox-session}} with [[xinit]]. Note that only {{ic|openbox-session}} provides [[#Autostart]].<br />
<br />
{{Note|After executing openbox-session, there is only a blank grey screen. Try to move your mouse and '''right click''' to get an openbox menu to make sure that it is actually working.}}<br />
<br />
=== Other desktop environments ===<br />
<br />
{{Note|<br />
* When replacing the native window manager of a [[desktop environment]] with Openbox, keep in mind that Openbox does not provide any compositing effects (such as transparency). See [[#Compositing effects]].<br />
* Openbox does work with GNOME applications (but see [[GTK+#Client-side decorations]]). [http://comments.gmane.org/gmane.comp.window-managers.openbox/6595]}}<br />
<br />
See [[Desktop environment#Use a different window manager]].<br />
<br />
== Configuration==<br />
<br />
{{Note|Local configuration files will always override global equivalents.}}<br />
<br />
Four key files form the basis of the [http://openbox.org/wiki/Configuration openbox configuration], each serving a unique role. They are: {{ic|rc.xml}}, {{ic|menu.xml}}, {{ic|autostart}}, and {{ic|environment}}. Although these files are discussed in more detail below, to start configuring Openbox, it will first be necessary to create a '''local''' Openbox profile (i.e for your specific user account) based on them. This can be done by copying them from the '''global''' {{ic|/etc/xdg/openbox}} profile (applicable to any and all users) as a template:<br />
<br />
$ cp -R /etc/xdg/openbox ~/.config/<br />
<br />
=== rc.xml ===<br />
<br />
{{Tip|Custom keyboard shortcuts (keybindings) must be added to the {{ic|<keyboard>}} section of this file, and underneath the {{ic|<nowiki><!-- Keybindings for running aplications --></nowiki>}} heading.}}<br />
<br />
{{ic|~/.config/openbox/rc.xml}} is the main configuration file, responsible for determining the behaviour and settings of the overall session, including:<br />
<br />
* Keyboard shortcuts (e.g. starting applications; controlling the volume)<br />
* Theming<br />
* Desktop and Virtual desktop settings, and<br />
* Application Window settings<br />
<br />
This file is also pre-configured, meaning that it will only be necessary to amend existing content in order to customise behaviour to suit personal preference.<br />
<br />
{{Note|Per-application settings pertaining to fixed placement of applications per monitor will only work if the x & y position have also been defined.}}<br />
<br />
=== menu.xml ===<br />
<br />
{{ic|~/.config/openbox/menu.xml}} defines the type and behaviour of the desktop menu, accessable by right-clicking the background. Although the default provided is a '''static menu''' (meaning that it will not automatically update when new applications are installed), it is possible to employ the use of '''dynamic menus''' that will automatically update as well. <br />
<br />
The available options are discussed extensively below in the [[#Menus]] section.<br />
<br />
=== Autostart ===<br />
<br />
{{ic|openbox-session}} provides two autostart mechanisms: [[XDG Autostart]] (which only works if {{Pkg|python2-xdg}} is installed) and [http://openbox.org/wiki/Help:Autostart Openbox's own autostart mechanism].<br />
<br />
Openbox's own autostart mechanism:<br />
<br />
* sources {{ic|/etc/xdg/openbox/environment}}<br />
* sources {{ic|~/.config/openbox/environment}}<br />
* runs {{ic|/etc/xdg/openbox/autostart}}<br />
* runs {{ic|~/.config/openbox/autostart}}<br />
<br />
Issues regarding commands in {{ic|~/.config/openbox/autostart}} being executed out of order (or skipped altogether) are often resolved by the addition of small delays. For instance:<br />
<br />
xset -b<br />
(sleep 3s && nm-applet) &<br />
(sleep 3s && conky) &<br />
<br />
=== environment ===<br />
<br />
{{ic|~/.config/openbox/environment}} can be used to export and set relevant environmental variables such as to:<br />
<br />
* Define new pathways (e.g. execute commands that would otherwise require the entire pathway to be listed with them)<br />
* Change language settings, and<br />
* Define other variables to be used (e.g. the fix for GTK theming could be listed here)<br />
<br />
=== Themes ===<br />
<br />
Install {{Pkg|obconf}} and {{Pkg|lxappearance-obconf}} for a GUI to configure visual settings and theming.<br />
<br />
A good selection of themes are available in the {{Pkg|openbox-themes}} package or the [[AUR]]. Some [[GTK+#Themes]] come with an Openbox theme as well. Both Openbox-specific and Openbox-compatible themes will be installed to the {{ic|/usr/share/themes}} directory and will also be immediately available for selection.<br />
<br />
[https://www.box-look.org/browse/ord/latest/ box-look.org] is an excellent and well-established source of themes. [http://www.deviantart.com/ deviantART.com] is another excellent resource. Many more can be found online.<br />
<br />
==== Edit or create ====<br />
<br />
{{Tip|It's better to copy a theme to your home directory than to edit those found in {{ic|/usr/share/themes/}}. This will retain the original should anything go wrong and ensure that your changes are not overwritten on update.}}<br />
<br />
The process of creating new or modifying existing themes is covered extensively at the official [http://openbox.org/wiki/Help:Themes openbox.org] website. {{AUR|obtheme}} is a user-friendly GUI for doing so.<br />
<br />
=== GUI configuration ===<br />
<br />
Several GUI applications are available to quickly and easily configure your Openbox desktop.<br />
<br />
* {{App|ObConf|A GTK2 based configuration tool for the Openbox window manager.|http://openbox.org/wiki/ObConf:About|{{Pkg|obconf}}}}<br />
* {{App|LXAppearance ObConf|Plugin for LXAppearance to configure Openbox. Note that not all options to configure Openbox are available in this plugin, so you might want to install obconf anyway.|http://lxde.org|{{Pkg|lxappearance-obconf}}}}<br />
* {{App|LXInput|LXDE keyboard and mouse configuration|http://lxde.org|{{Pkg|lxinput}}}}<br />
* {{App|LXRandR|LXDE monitor configuration.|http://wiki.lxde.org/en/LXRandR|{{Pkg|lxrandr}}}}<br />
* {{App|obkey|Configure Openbox keyboard shortcuts|https://code.google.com/p/obkey/|{{AUR|obkey}}}} <br />
* {{App|ob-autostart|A simple autostart application for Openbox.|http://pastebin.com/012YgXTk|{{AUR|ob-autostart}}}} <br />
* {{App|obapps|Graphical tool for configuring application settings in Openbox.|https://sourceforge.net/projects/obapps/|{{AUR|obapps}}}} <br />
<br />
Programs and applications relating to the configuration of Openbox's desktop menu are discussed in the [[#Menus|Menus]] section.<br />
<br />
== Openbox reconfiguration ==<br />
<br />
{{Tip|where not already present, it would be worthwhile adding this command to a menu and/or as a keybind for convenience.}}<br />
<br />
Openbox will not always automatically reflect any changes made to its configuration files within a session. As a consequence, it will be necessary to manually reload those files after they have been edited. To do so, enter the following command:<br />
<br />
$ openbox --reconfigure<br />
<br />
Where intending to add this command as a keybind to {{ic|~/.config/openbox/rc.xml}}, it will only be necessary to list the command as {{ic|reconfigure}}. An example has been provided below, using the {{ic|Super}}+{{ic|F11}} keybind:<br />
<br />
<keybind key="W-F11"><br />
<action name="Reconfigure"/><br />
</keybind><br />
<br />
== Keybinds ==<br />
<br />
All keybinds must be added to the {{ic|~/.config/openbox/rc.xml}} file, and below the {{ic|<nowiki><!-- Keybindings for running aplications --></nowiki>}} heading. Although a brief overview has been provided here, a more in-depth explanation of keybindings can be found at [http://openbox.org/wiki/Help:Bindings openbox.org]. <br />
<br />
Keybinds can be added to the configuration file using the following syntax:<br />
<br />
<keybind key="'''my-key-combination'''"><br />
<action name="'''my-action'''"><br />
'''...'''<br />
</action><br />
</keybind><br />
<br />
The action name for running an external command is ''Execute''. Use the following syntax to define an external command to execute:<br />
<br />
<action name="Execute"><br />
<command>'''my-command'''</command><br />
</action><br />
<br />
See [http://openbox.org/wiki/Help:Actions the Openbox wiki] for a list of all available actions.<br />
<br />
{{Tip|The {{AUR|obkey}} utility provides a graphical interface for configuring key bindings. Before using ''obkey'', you should use ''obconf'' to create {{ic|~/.config/openbox/rc.xml}}.}}<br />
<br />
While the use of standard alpha-numeric keys for keybindings is self-explanatory, special names are assigned to other types of keys, such as {{ic|modifiers}}, {{ic|multimedia}} and {{ic|navigation}}.<br />
<br />
=== Modifiers ===<br />
<br />
{{ic|Modifier}} keys play an important role in keybindings (e.g. holding down the {{ic|shift}} or {{ic|CTRL / control}} key in combination with another key to undertake an action). Using modifiers helps to prevent conflicting keybinds, whereby two or more actions are linked to the same key or combination of keys. The syntax to use a modifier with another key is:<br />
<br />
"<modifier>-<key>"<br />
<br />
The modifier codes are as follows:<br />
<br />
* {{ic|S}}: Shift<br />
* {{ic|C}}: Control / CTRL<br />
* {{ic|A}}: Alt<br />
* {{ic|W}}: Super / Windows<br />
* {{ic|M}}: Meta<br />
* {{ic|H}}: Hyper (If it is bound to something)<br />
<br />
=== Multimedia keys ===<br />
<br />
Where available, it is possible to set the appropriate {{ic|multimedia}} keys to perform their intended functions, such as to control the volume and/or the screen brightness. These will usually be integrated into the {{ic|function}} keys, and are identified by their appropriate symbols. See [[Extra keyboard keys]] for details.<br />
<br />
The volume and brightness multimedia codes are as follows (note that commands will still have to be assigned to them to actually function):<br />
<br />
* {{ic|XF86AudioRaiseVolume}}: Increase volume<br />
* {{ic|XF86AudioLowerVolume}}: Decrease volume<br />
* {{ic|XF86AudioMute}}: Mute / unmute volume<br />
* {{ic|XF86MonBrightnessUp}}: Increase screen brightness<br />
* {{ic|XF86MonBrightnessDown}}: Decrease screen brightness<br />
<br />
For a full list of XF86 multimedia keys, see the [http://wiki.linuxquestions.org/wiki/XF86_keyboard_symbols LinuxQuestions wiki].<br />
<br />
==== Volume control ====<br />
<br />
What commands should be used for controlling the volume will depend on whether [[ALSA]], [[PulseAudio]], or [[OSS]] is used for sound.<br />
<br />
*ALSA: see [[Advanced Linux Sound Architecture#Keyboard volume control]].<br />
*PulseAudio: see [[PulseAudio#Keyboard volume control]]<br />
*OSS: see [[OSS#Using multimedia keys with OSS]].<br />
<br />
=== Navigation keys ===<br />
<br />
These are the directional / arrow keys, usually used to move the cursor up, down, left, or right. The (self-explanatory) navigation codes are as follows:<br />
<br />
* {{ic|Up}}: Up<br />
* {{ic|Down}}: Down<br />
* {{ic|Left}}: Left<br />
* {{ic|Right}}: Right<br />
<br />
== Menus ==<br />
<br />
It is possible to employ three types of menu in Openbox: {{ic|static}}, {{ic|pipes}} (dynamic), and {{ic|generators}} (static or dynamic). They may also be used alone or in any combination.<br />
<br />
=== Static ===<br />
<br />
As the name would suggest, this default type of menu does not change in any way, and may be manually edited and/or (re)generated automatically through the use on an appropriate software package.<br />
<br />
Fast and efficient, while this type of menu can be used to select applications, it can also be useful to access specific functions and/or perform specific tasks (e.g. desktop configuration), leaving the access of applications to another process (e.g. the {{Pkg|synapse}} or {{Pkg|xfce4-appfinder}} applications).<br />
<br />
The {{ic|~/.config/openbox/menu.xml}} file will be the sole source of static desktop menu content.<br />
<br />
==== menumaker ====<br />
<br />
{{Pkg|menumaker}} automatically generates {{ic|xml}} menus for several window managers, including Openbox, [[Fluxbox]], [[IceWM]] and [[Xfce]]. It will search for all installed executable programs and consequently create a menu file for them. It is also possible to configure MenuMaker to exclude certain application types (e.g. relating to [[GNOME]] or [[KDE]]), if desired.<br />
<br />
Once installed and executed, it will automatically generate a new {{ic|~/.config/openbox/menu.xml}} file. To avoid overwriting an existing file, enter:<br />
<br />
$ mmaker -v OpenBox3<br />
<br />
Otherwise, to overwrite an existing file, add the {{ic|force}} argument ({{ic|f}}):<br />
<br />
$ mmaker -vf OpenBox3<br />
<br />
Once a new {{ic|~/.config/openbox/menu.xml}} file has been generated it may then be manually edited, or configured using a GUI menu editor, such as {{Pkg|obmenu}}.<br />
<br />
==== obmenu ====<br />
<br />
{{Warning|{{ic|obm-xdg}} - a pipe menu to generate a list of [[GTK+]] and [[GNOME]] applications - is also provided with obmenu. However, it has long-running bugs whereby it may produce an invalid output, or even not function at all. Consequently it has been omitted from discussion.}}<br />
<br />
{{Pkg|obmenu}} is a "user-friendly" GUI application to edit {{ic|~/.config/openbox/menu.xml}}, without the need to code in {{ic|xml}}.<br />
<br />
==== xdg-menu ====<br />
<br />
{{Pkg|archlinux-xdg-menu}} will automatically generate a menu based on {{ic|xdg}} files contained within the {{ic|/etc/xdg/}} directory for numerous Window Managers, including Openbox. Review the [[Xdg-menu#OpenBox]] article for further information.<br />
<br />
==== logout menu options ====<br />
<br />
{{Tip|The commands provided can also be attached to [[#Keybinds|keybinds]].}}<br />
<br />
The {{ic|~/.config/openbox/menu.xml}} file can be edited in order to provide a sub-menu with the same options as provided by [[#oblogout|oblogout]]. The sample script below will provide all of these options, with the exception of the ability to lock the screen:<br />
<br />
<menu id="exit-menu" label="Exit"><br />
<item label="Log Out"><br />
<action name="Execute"><br />
<command>openbox --exit</command><br />
</action><br />
</item><br />
<item label="Shutdown"><br />
<action name="Execute"><br />
<command>systemctl poweroff</command><br />
</action><br />
</item><br />
<item label="Restart"><br />
<action name="Execute"><br />
<command>systemctl reboot</command><br />
</action><br />
</item><br />
<item label="Suspend"><br />
<action name="Execute"><br />
<command>systemctl suspend</command><br />
</action><br />
</item><br />
<item label="Hibernate"><br />
<action name="Execute"><br />
<command>systemctl hibernate</command><br />
</action><br />
</item><br />
</menu><br />
<br />
Once the entries have been composed, add the following line to present the sub-menu where desired within the main desktop menu (usually as the last entry):<br />
<br />
<menu id="exit-menu"/><br />
<br />
=== Pipes ===<br />
<br />
{{Tip|It is entirely feasible for a static menu to contain one or more pipe sub-menus. The functionality of some pipe menus may also rely on the installation of relevant software packages.}}<br />
<br />
This type of menu is in essence a script that provides dynamic, refreshed lists on-the-fly as and when run. These lists may be used for multiple purposes, including to list applications, to provide information, and to provide control functions. Pre-configured pipe menus can be installed, although not from the [[official repositories]]. More experienced users can also modify and/or create their own custom scripts. Again, {{ic|~/.config/openbox/menu.xml}} may and commonly will contain several pipe menus.<br />
<br />
==== Examples ====<br />
<br />
* {{AUR|openbox-xdgmenu}}: fast xdg-menu converter to xml-pipe-menu<br />
* {{AUR|obfilebrowser}}: Application and file browser<br />
* {{AUR|obdevicemenu}}: Management of removable media with [[Udisks]]<br />
* [https://bbs.archlinux.org/viewtopic.php?pid=1345031 wifi pipe menu]: Wireless networking using [[Netctl]]<br />
<br />
[http://openbox.org/wiki/Openbox:Pipemenus Openbox.org] also provides a further list of pipe menus.<br />
<br />
=== Generators ===<br />
<br />
This type of menu is akin to those provided by the taskbars of desktop environments such as [[Xfce]] or [[LXDE]]. Automatically updating on-the-fly, this type of menu can be powerful and very convenient. It may also be possible to add custom categories and menu entries; read the documentation for your intended dynamic menu to determine if and how this can be done.<br />
<br />
A menu generator will have to be executed from the {{ic|~/.config/openbox/menu.xml}} file.<br />
<br />
==== obmenu-generator ====<br />
<br />
{{Tip|icons can still be disabled in {{AUR|obmenu-generator}}, even where enabled in {{ic|~/.config/openbox/rc.xml}}.}}<br />
<br />
{{AUR|obmenu-generator}} is highly recommended despite being an unofficial package. With the ability to be used as a static or dynamic menu, it is highly configurable, powerful, and versatile. Menu categories and individual entries may also be easily hidden, customised, and/or added with ease. The [http://trizenx.blogspot.co.uk/2012/02/obmenu-generator.html official homepage] provides further information and screenshots.<br />
<br />
Below is an example of how obmenu-generator would be dynamically executed without icons in {{ic|~/.config/openbox/menu.xml}}:<br />
<br />
<?xml version="1.0" encoding="utf-8"?><br />
<openbox_menu><br />
<menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator"><br />
</menu><br />
</openbox_menu><br />
<br />
To automatically iconify entries, the {{ic|-i}} option would be added:<br />
<br />
<menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator -i"><br />
<br />
==== openbox-menu ====<br />
<br />
{{Tip|If this menu produces an error, it may be solved by enabling icons in {{ic|~/.config/openbox/rc.xml}}.}}<br />
<br />
{{AUR|openbox-menu}} uses the [[LXDE]] [http://sourceforge.net/projects/lxde/files/menu-cache/ menu-cache] to create dynamic menus. The [http://fabrice.thiroux.free.fr/openbox-menu_en.html official homepage] provides further information and screenshots.<br />
<br />
=== Menu icons ===<br />
<br />
To show icons next to menu entries, it will be necessary to ensure they are enabled in the {{ic|<menu>}} section of the {{ic|~/.config/openbox/rc.xml}} file:<br />
<br />
<applicationIcons>yes</applicationIcons><br />
<br />
Where using a static menu, it will then be necessary to edit the {{ic|~/.config/openbox/menu.xml}} file to provide both the {{ic|icon <nowiki>=</nowiki>}} command, along with the full path and icon name for each entry. An example of the syntax used to provide an icon for a category is:<br />
<br />
<menu id="apps-menu" label="[label name]" icon="[pathway to icon]/[icon name]"><br />
<br />
=== Desktop menu as a panel menu ===<br />
<br />
{{Tip|XDoTool can simulate any keybind for any action, and as such, it may therefore be used for many other purposes...}}<br />
<br />
{{Pkg|xdotool}} is a package that can issue commands to simulate key presses / keybinds, meaning that it is possible to use it to invoke keybind-related actions without having to actually press their assigned keys. As this includes the ability to invoke an assigned keybind for the Openbox desktop menu, it is therefore possible to use XDoTool to turn the Openbox desktop menu into a panel menu. Especially where the desktop menu is heavily customised and feature-rich, this may prove very useful to:<br />
<br />
* Replace an existing panel menu<br />
* Implement a panel menu where otherwise not provided or possible (e.g. for [[Tint2]])<br />
* Compensate where losing access to the desktop menu due to the use of an application like {{pkg|xfdesktop}} to manage the [[#Desktop icons and wallpapers|desktop]].<br />
<br />
Once XDoTool has been installed - if not already present - it will be necessary to create a keybind to access the root menu in {{ic|~/.config/openbox/rc.xml}}, and again below the {{ic|<nowiki><</nowiki>!-- Keybindings for running aplications --<nowiki>></nowiki>}} heading. For example, the following code will bring up the menu by pressing {{ic|CTRL}} + {{ic|m}}:<br />
<br />
<keybind key="C-m"><br />
<action name="ShowMenu"><br />
<menu>root-menu</menu><br />
</action><br />
</keybind><br />
<br />
Openbox must then be [[#Openbox reconfiguration|reconfigured]]. In this instance, XDoTool will be used to simulate the {{ic|CTRL}} + {{ic|m}} keypress to access the desktop menu with the following command (note the use of {{ic|+}} in place of {{ic|-}}):<br />
<br />
xdotool key control+m<br />
<br />
How this command may be used as a panel launcher / icon is largely dependent on the features of panel used. While some panels will allow the above command to be executed directly in the process of creating a new launcher, others may require the use of an executable script. As an example, a custom executable script called {{ic|obpanelmenu.sh}} will be created in the {{ic|~/.config}} folder:<br />
<br />
$ ''text editor'' ~/.config/obpanelmenu.sh<br />
<br />
Once the empty file has been opened, the appropriate XDoTool command must be added to the empty file (i.e. to simulate the {{ic|CTRL}} + {{ic|m}} keypress for this example):<br />
<br />
xdotool key control+m<br />
<br />
After the file has been saved and closed, it may then be made into an executable script with the following command:<br />
<br />
$ chmod +x ~/.config/obpanelmenu.sh<br />
<br />
Executing it will bring up the Openbox desktop menu. Consequently, where using a panel that supports drag-and-drop functionality to add new launchers, simply drag the executable script onto it before changing the icon to suit personal taste.<br />
<br />
=== XDG compliant menu ===<br />
<br />
A xdg compliant menu is based on the freedesktop.org standard. The menu is defined in menu-files which reside in /etc/xdg/menus. New applications will occur automatically in the menu.<br />
<br />
==== Examples ====<br />
<br />
* [https://github.com/mlde/californium californium]: xdg menu based on the LXQt main menu and easily themable<br />
<br />
== Tips and tricks ==<br />
<br />
=== Cursor and icon themes ===<br />
<br />
See [[Cursor themes]] and [[Icons]] for details.<br />
<br />
=== Desktop icons and wallpapers ===<br />
<br />
Openbox does not natively support the use of desktop icons or wallpapers.<br />
<br />
See [[PCManFM#Desktop management|PCManFM]], [[SpaceFM#Desktop management|SpaceFM]] and [[Idesk]].<br />
<br />
{{note|You may have to edit {{ic|~/.conkyrc}} and set {{ic|own_window_type}} to {{ic|normal}}.}}<br />
<br />
See [[List of applications#Wallpaper setters]].<br />
<br />
=== Compositing effects ===<br />
<br />
Openbox does not provide native support for [[Wikipedia:Compositing window manager|compositing]], and thus requires an external compositor for this purpose.<br />
<br />
Although compositing is not a necessary component, it may specifically avoid issues such as screen distortion with [[#oblogout|oblogout]], and visual glitches with terminal window transparency. See [[Xorg#Composite]] for common choices.<br />
<br />
=== oblogout ===<br />
<br />
See the [[Oblogout]] article for an overview on how to use this useful, graphical logout script.<br />
<br />
=== Openbox for multihead users ===<br />
<br />
While Openbox provides better than average multihead support on its own, {{AUR|openbox-multihead-git}} provides a development branch called '''Openbox Multihead''' that gives multihead users per-monitor desktops. This model is not commonly found in floating window managers, but exists mainly in tiling window managers. It is explained well on the [http://xmonad.org/tour.html#workspace Xmonad web site]. Also, please see [https://github.com/BurntSushi/openbox-multihead/blob/multihead/README.MULTIHEAD README.MULTIHEAD] for a more comprehensive description of the new features and configuration options found in Openbox Multihead.<br />
<br />
Openbox Multihead will function like normal Openbox when only a single head is available.<br />
<br />
A downside to using Openbox Multihead is that it breaks the EWMH assumption that one and only one desktop is visible at any time. Thus, existing pagers will not work well with it. To remedy this, you can install {{AUR|pager-multihead-git}}{{Broken package link|{{aur-mirror|pager-multihead-git}}}} alongside Openbox Multihead. It will work without Openbox Multihead if only one monitor is active.<br />
<br />
=== Launch a complex command with hotkey ===<br />
<br />
If you need to execute a complex command, use shell functionality.<br />
<br />
Special character replacement are as follows:<br />
<br />
* {{ic|&}}: &amp;amp;<br />
* {{ic|<}}: &amp;lt;<br />
* {{ic|>}}: &amp;gt;<br />
<br />
This example will turn off display immediately and lock screen with {{Pkg|slock}}. It was taken from [https://bbs.archlinux.org/viewtopic.php?pid=903057 this thread].<br />
<keybind key="W-l"><br />
<action name="Execute"><br />
<command>sh -c 'slock &amp;amp; (sleep .5 &amp;amp;&amp;amp; xset dpms force off)'</command><br />
</action><br />
</keybind><br />
<br />
Sometimes one need to specify environment variable for application:<br />
<keybind key="A-F7"><br />
<action name="Execute"><br />
<command>sh -c "LC_ALL=C obconf"</command><br />
</action><br />
</keybind><br />
<br />
Another example will launch application preserving all stdout and stderr output to file:<br />
<keybind key="A-f"><br />
<action name="Execute"><br />
<command>sh -c sh -c "exec gimp &amp;gt;/tmp/gimp.out 2&amp;gt;&amp;amp;1"</command><br />
</action><br />
</keybind><br />
<br />
=== Switch desktops using the mouse ===<br />
<br />
It is possible to switch desktop by moving the mouse cursor to the edges of the screen. First install {{Pkg|xdotool}} and add the following two lines to your {{ic|~/.xinitrc}}:<br />
<br />
xdotool behave_screen_edge --delay 500 left set_desktop --relative -- -1 &<br />
xdotool behave_screen_edge --delay 500 right set_desktop --relative -- +1 &<br />
<br />
=== Set default applications / file associations ===<br />
<br />
See the [[Default applications]] article.<br />
<br />
=== Ad-hoc window transparency ===<br />
<br />
{{Warning|This may not work where other actions are defined within the action group.}}<br />
The program {{Pkg|transset-df}} can enable window transparency on-the-fly.<br />
<br />
For example, using the following code in the {{ic|<mouse>}} section of the {{ic|~/.config/openbox/rc.xml}} file will enable control of application window transparency by hovering the mouse-pointer over the title bar and scrolling with the middle button:<br />
<br />
<context name="Titlebar"><br />
...<br />
<mousebind button="Up" action="Click"><br />
<action name= "Execute" ><br />
<execute>transset-df -p .2 --inc </execute><br />
</action><br />
</mousebind><br />
<mousebind button="Down" action="Click"><br />
<action name= "Execute" ><br />
<execute>transset-df -p .2 --dec </execute><br />
</action><br />
</mousebind><br />
...<br />
</context><br />
<br />
=== Using obxprop for faster configuration ===<br />
<br />
The {{Pkg|openbox}} package provides a {{ic|obxprop}} binary that can parse relevant values for applications settings in {{ic|rc.xml}}. Officially {{ic|<nowiki>obxprop | grep "^_OB_APP"</nowiki>}} is recommended for this task. Start the process by running the command shown, then click a window to see its properties in the terminal.<br />
<br />
=== Xprop values for applications ===<br />
<br />
{{Pkg|xorg-xprop}} can be used to relay property values for selected applications. Where frequently using per-application settings, the following [[Bash#Aliases|Bash Alias]] may be useful:<br />
dy:<br />
<br />
alias xp='xprop | grep "WM_WINDOW_ROLE\|WM_CLASS" && echo "WM_CLASS(STRING) = \"NAME\", \"CLASS\""'<br />
<br />
To use Xorg-XProp, run using the alias given {{ic|xp}}, and click on the active program desired to define with per-application settins. The results displayed will only be the information that Openbox itself requires, namely the {{ic|WM_WINDOW_ROLE}} and {{ic|WM_CLASS}} (name and class) values:<br />
<br />
WM_WINDOW_ROLE(STRING) = "roster"<br />
WM_CLASS(STRING) = "gajim.py", "Gajim.py"<br />
WM_CLASS(STRING) = "NAME", "CLASS"<br />
<br />
=== Switching between keyboard layouts ===<br />
<br />
See the article section [[Keyboard configuration in Xorg#Switching between keyboard layouts|switching between keyboard layouts]] for instructions.<br />
<br />
=== Set grid layout for virtual desktops ===<br />
<br />
Install {{AUR|obsetlayout}}. To set a 2x2 grid for example:<br />
<br />
obsetlayout 0 2 2 0<br />
<br />
Run it without arguments to know what the arguments mean.<br />
<br />
=== Enable Hot Corners ===<br />
<br />
[https://github.com/mlde/lead lead] provides hot corners for openbox and other lightweight window managers. Start the application with a entry in the autostart-file:<br />
<br />
mlde.lead &<br />
<br />
Commands can be edited in the configuration file {{ic|~/.config/mlde/lead.conf}}:<br />
<br />
[eDP1]<br />
bottom=<br />
bottomLeft=chromium<br />
bottomRight=thunar<br />
left=<br />
right=<br />
top=<br />
topLeft=mlde.californium toggle<br />
topRight=skippy-xd<br />
<br />
=== Window snapping ===<br />
<br />
Many desktop environments and window managers support ''window snapping'' (e.g. Windows 7 Aero snap), whereby they will automatically snap into place when moved to the edge of the screen. This effect can also be simulated in Openbox through the use of [[#Keybinds|keybinds]] on focused windows. <br />
<br />
As illustrated in the example below, percentages must be used to determine window sizes (see [http://openbox.org/wiki/Help:Actions openbox.org] for further information). In this instance, The {{ic|super}} key is used in conjunction with the {{ic|navigation}} keys:<br />
<br />
<keybind key="W-Left"><br />
<action name="UnmaximizeFull"/><br />
<action name="MaximizeVert"/><br />
<action name="MoveResizeTo"><br />
<width>50%</width><br />
</action><br />
<action name="MoveToEdge"><direction>west</direction></action><br />
</keybind><br />
<keybind key="W-Right"><br />
<action name="UnmaximizeFull"/><br />
<action name="MaximizeVert"/><br />
<action name="MoveResizeTo"><br />
<width>50%</width><br />
</action><br />
<action name="MoveToEdge"><direction>east</direction></action><br />
</keybind><br />
<br />
However, it should be noted that once a window has been 'snapped' to an edge, it will remain vertically maximised unless subsequently maximised and then restored. The solution is to implement additional keybinds - in this instance using the {{ic|down}} and {{ic|up}} keys - to do so. This will also make pulling 'snapped' windows from screen edges faster as well:<br />
<br />
<keybind key="W-Down"><br />
<action name="Unmaximize"/><br />
</keybind><br />
<keybind key="W-Up"><br />
<action name="Maximize"/><br />
</keybind><br />
<br />
This [http://ubuntuforums.org/showthread.php?t=1796793 Ubuntu forum thread] provides more information. Applications such as {{AUR|opensnap}} are also available to automatically simulate window snapping behaviour without the use of keybinds.<br />
Another option is to use {{AUR|bunsen-utilities-git}} which provides {{ic|bl-aerosnap --left}} and {{ic|bl-aerosnap --right}} commands which will snap active window on left or right edge respectively if it's not snapped and restore it to original size and position otherwise. Just bind these commands to the key combination of your choosing.<br />
<br />
=== Smooth display manager transition ===<br />
<br />
{{Note|This has been confirmed to work with [[LightDM]].}}<br />
<br />
Users of display managers might experience a flickering during the transition between the display manager and the Openbox desktop. The flickering comes from Openbox setting the root window's color during startup. Therefore there's a brief moment when the display flashes in a grey color, between the display manager's background and the desktop's wallpaper.<br />
<br />
Setting the root window's background color can be disabled by editing the Openbox startup script found in {{ic|/usr/lib/openbox/openbox-autostart}}. Simply comment out (or delete) the block starting with {{ic|# Set a background color}}.<br />
<br />
{{Note|Users who don't specifically set their wallpaper will "inherit" the display manager's background automatically if they disable the root window color adjustment.}}<br />
<br />
=== Window Decorations ===<br />
<br />
To remove window decorations for all or particular applications, use the ''<decor>'' option in the ''<applications>'' section. Example for Firefox, including variants like Firefox-Beta:<br />
<application class="Firefox*"><br />
<decor>no</decor><br />
</application><br />
One could also disable decorations for all applications (using class '''"*"'''), then enable them (using '''yes''') for individual ones. To apply the changes, restart your desktop session, and thus Openbox. Reference: [http://openbox.org/wiki/Help:FAQ#How_do_I_remove_the_decorations_from_all_my_windows.3F Openbox FAQ]<br />
<br />
== Troubleshooting ==<br />
<br />
=== Firefox ===<br />
<br />
Mozilla based browsers may ignore application rules (e.g. {{ic|<desktop>}}) unless {{ic|1=class="Firefox"}} is used. See [[#Xprop values for applications]].<br />
<br />
=== Missing themes ===<br />
<br />
If for any reason the newly extracted theme cannot be selected, open the theme directory to first ensure that it is compatible with Openbox - there should be an {{ic|openbox-3}} directory and a {{ic|themerc}} file within it. An {{ic|.obt}} ('''O'''pen'''B'''ox '''T'''heme) file may also be present in some instances, which can then be manually loaded in {{Pkg|obconf}}.<br />
<br />
A theme may also be not accessible due to wrong permissions. See [[File permissions and attributes]] for more.<br />
<br />
=== Stop continuous desktop switching ===<br />
<br />
By default Openbox switches from the last desktop back to the first desktop on mouse wheel scroll. Use {{ic|<wrap>no</wrap>}} in the {{ic|mousebind}} section to disable this behaviour.<br />
<br />
<context name="Desktop"><br />
<mousebind button="Up" action="Click"><br />
<action name="GoToDesktop"><br />
<to>previous</to><br />
<wrap>no</wrap><br />
</action><br />
</mousebind><br />
<mousebind button="Down" action="Click"><br />
<action name="GoToDesktop"><br />
<to>next</to><br />
<wrap>no</wrap><br />
</action><br />
</mousebind><br />
</context><br />
<br />
=== Windows load behind the active window ===<br />
<br />
Some application windows (such as Firefox windows) may load behind the currently active window, causing you to need to switch to the window you just created to focus it. To fix this behavior add this to your {{ic|~/.config/openbox/rc.xml}} file, inbetween the {{ic|1=<openbox_config>}} and {{ic|1=</openbox_config>}} tags:<br />
<br />
{{bc|1=<br />
<applications><br />
<application class="*"><br />
<focus>yes</focus><br />
</application><br />
</applications><br />
}}<br />
<br />
== See also ==<br />
<br />
* [http://openbox.org/ Openbox Website] - Official website<br />
* [http://www.box-look.org/ Box-Look.org] - A good resource for themes and related artwork<br />
* [https://bbs.archlinux.org/viewtopic.php?id=93126 Openbox Hacks and Configs Thread] @ Arch Linux Forums<br />
* [https://bbs.archlinux.org/viewtopic.php?id=45692 Openbox Screenshots Thread] @ Arch Linux Forums<br />
* [http://urukrama.wordpress.com/openbox-guide/ An Openbox guide]</div>Jwh7