https://wiki.archlinux.org/api.php?action=feedcontributions&user=Iaz3&feedformat=atomArchWiki - User contributions [en]2024-03-29T07:31:33ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=795986Bluetooth headset2024-01-04T07:20:38Z<p>Iaz3: /* Tips and tricks */ Add tip for disabling/enabling AVRCP media controls</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
[[ja:Bluetooth ヘッドセット]]<br />
[[ru:Bluetooth headset]]<br />
[[zh-hans:Bluetooth headset]]<br />
{{Related articles start}}<br />
{{Related|Bluetooth}}<br />
{{Related articles end}}<br />
<br />
There are three Bluetooth audio systems:<br />
* A2DP (advanced audio distribution) provides music-grade stereo output (sink), typically without input (source).<br />
** A2DP can use a variety of codecs. The standard SBC has a poor quality-bitrate tradeoff, but much better, open-source alternatives (LDAC, AptX) have become widespread.<br />
** AVRCP is used on top of A2DP to provide playback control.<br />
* HFP/HSP (hands-free/headset) provides voice-grade mono output and input. HFP builds on top of HSP.<br />
* LE Audio is a low-energy audio standard announced in 2020. The standard codec is LC3.<br />
<br />
The kernel, BlueZ 5, and PipeWire support all three profiles. Older sound servers such as PulseAudio and ALSA only support A2DP and HFP/HSP. Although Bluetooth is infamous for being unreliable[https://xkcd.com/2055/], many implementations have seen massive improvements, making it a somewhat less excruciating experience on well-established hardware like Intel Bluetooth chips.<br />
<br />
== Headset via PipeWire ==<br />
<br />
[[PipeWire]] acts as a drop-in replacement for [[PulseAudio]] and offers an easy way to set up Bluetooth headsets. It includes out-of-the-box support for A2DP sink profiles using SBC/SBC-XQ, AptX, LDAC or AAC codecs, and HFP/HSP.<br />
<br />
[[Install]] {{Pkg|pipewire-pulse}} (which replaces {{Pkg|pulseaudio}} and {{Pkg|pulseaudio-bluetooth}}).<br />
<br />
The daemon will be started automatically as a [[systemd/User|user service]]. Use {{Pkg|pavucontrol}} or your desktop environment's settings for configuration. For more information, see [[PipeWire#Bluetooth devices]].<br />
<br />
== Headset via Bluez5/PulseAudio ==<br />
<br />
{{Merge|Bluetooth|Significant redundancy with general setup on Bluetooth page. Should be merged there. Headset-specific info would stay on this page.|Talk:Bluetooth#Merging general setup from Keyboard, Mouse, Headset pages}}<br />
<br />
[[Install]] the {{Pkg|pulseaudio-alsa}}, {{Pkg|pulseaudio-bluetooth}} and {{Pkg|bluez-utils}} packages, the last of which provides the {{ic|bluetoothctl}} utility.<br />
<br />
{{Note|Before continuing, ensure that the bluetooth device is not blocked by [[rfkill]].}}<br />
<br />
=== Configuration via CLI ===<br />
<br />
[[Start]] {{ic|bluetooth.service}}.<br />
<br />
Now we can use the ''bluetoothctl'' command line utility to pair and connect. For troubleshooting and more detailed explanations of ''bluetoothctl'' see the [[Bluetooth]] article. Run<br />
<br />
$ bluetoothctl<br />
<br />
to be greeted by its internal command prompt. Then enter:<br />
<br />
[bluetooth]# power on<br />
[bluetooth]# agent on<br />
[bluetooth]# default-agent<br />
[bluetooth]# scan on<br />
<br />
Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,<br />
<br />
[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10<br />
<br />
shows a device that calls itself ''"Lasmex LBT10"'' and has MAC address ''"00:1D:43:6D:03:26"''. We will now use that MAC address to initiate the pairing:<br />
<br />
[bluetooth]# pair 00:1D:43:6D:03:26<br />
<br />
After pairing, you also need to explicitly connect the device (if this does not work, try the {{ic|trust}} command below ''before'' attempting to connect):<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
<br />
If you are getting a connection error {{ic|org.bluez.Error.Failed}} retry by killing existing PulseAudio daemon first:<br />
<br />
$ pulseaudio -k<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
<br />
Finally, if you want to automatically connect to this device in the future:<br />
<br />
[bluetooth]# trust 00:1D:43:6D:03:26<br />
<br />
If everything works correctly, you now have a separate output device in [[PulseAudio]].<br />
<br />
{{Note|The device may be off by default. Select its audio profile ({{ic|OFF}}, {{ic|A2DP}}, {{ic|HFP}}) in the "Configuration" tab of {{Pkg|pavucontrol}}.}}<br />
<br />
You can now redirect any audio through that device using the "Playback" and "Recording" tabs of {{Pkg|pavucontrol}}.<br />
<br />
You can now disable scanning again and exit the program:<br />
<br />
[bluetooth]# scan off<br />
[bluetooth]# exit<br />
<br />
==== Setting up auto connection ====<br />
<br />
To make your headset auto connect you need to enable PulseAudio's switch-on-connect module. Do this by adding the following lines to {{ic|/etc/pulse/default.pa}}:<br />
<br />
{{hc|/etc/pulse/default.pa|<br />
### Automatically switch to newly-connected devices<br />
load-module module-switch-on-connect<br />
}}<br />
<br />
{{Note|Make sure that your bluetooth audio device is ''trusted'', otherwise repeated pairing will fail. See [[Bluetooth#Pairing]] for details.}}<br />
<br />
=== Configuration via GNOME Bluetooth ===<br />
<br />
{{Note| The A2DP profile will not activate using this method with pulseaudio 9/10 due to an ongoing bug, leading to possible low quality mono sound. See [[#A2DP not working with PulseAudio]] for a possible solution.}}<br />
<br />
You can use [[Bluetooth#Graphical|GNOME Bluetooth]] graphical front-end to easily configure your bluetooth headset. <br />
<br />
First, you need to be sure that {{ic|bluetooth.service}} systemd unit is running. <br />
<br />
Open GNOME Bluetooth and activate the bluetooth. After scanning for devices, you can connect to your headset selecting it on the device list. You can directly access to sound configuration panel from the device menu. On the sound panel, a new sink should appear when your device is connected.<br />
<br />
=== LDAC/aptX ===<br />
<br />
[[Wikipedia:LDAC_(codec)|LDAC]]/[[Wikipedia:aptX|aptX]] codecs are supported as of [https://www.freedesktop.org/wiki/Software/PulseAudio/Notes/15.0/#supportforldacandaptxbluetoothcodecsplussbcxqsbcwithhigher-qualityparameters PulseAudio 15.0]. You can verify the codec you are using for connection as follows:<br />
<br />
$ pactl list | grep a2dp_codec<br />
<br />
=== Troubleshooting ===<br />
<br />
{{Note|Many users report frustration with getting A2DP/Bluetooth Headsets to work. see [[#Switch between HSP/HFP and A2DP setting]] for additional information.}}<br />
<br />
==== Bad sound / Static noise / "Muddy" sound ====<br />
<br />
If you experience bad sound quality with your headset, it could in all likelihood be because your headset is not set to the correct profile.<br />
See [[#Switch between HSP/HFP and A2DP setting]] to solve the problem.<br />
<br />
If you suspect the bad sound quality is due to a poor bluetooth connection, you might compensate for it by switching to a lower bit-rate and lower audio quality codec such as SBC or aptX using {{ic|pactl}}:<br />
<br />
$ pactl send-message /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez switch-codec '"sbc"'<br />
<br />
where a list of available codecs can be obtained by:<br />
<br />
$ pactl send-message /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez list-codecs<br />
<br />
==== Selected audio profile, but headset inactive and audio cannot be redirected ====<br />
<br />
Deceptively, this menu is available before the device has been connected; annoyingly it will have no effect. The menu seems to be created as soon as the receiver recognizes the device.<br />
<br />
Make sure to run {{ic|bluetoothctl}} as root and connect the device manually. There may be configuration options to remove the need to do this each time, but neither pairing nor trusting induce automatic connecting for me.<br />
<br />
==== Pairing fails with AuthenticationFailed ====<br />
<br />
If pairing fails, you can try enabling or [https://stackoverflow.com/questions/12888589/linux-command-line-howto-accept-pairing-for-bluetooth-device-without-pin disabling SSPMode] with:<br />
<br />
# btmgmt ssp off<br />
<br />
or<br />
<br />
# btmgmt ssp on<br />
<br />
You may need to turn off BlueTooth while you run this command.<br />
<br />
==== Pairing works, but connecting does not ====<br />
<br />
You might see the following error in ''bluetoothctl'':<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
Attempting to connect to 00:1D:43:6D:03:26<br />
Failed to connect: org.bluez.Error.Failed<br />
<br />
To further investigate, check the [[unit status]] of {{ic|bluetooth.service}} or have a look at the log as follows:<br />
<br />
# journalctl -n 20<br />
<br />
You might see a message like this:<br />
<br />
bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available<br />
<br />
This may be due to the {{Pkg|pulseaudio-bluetooth}} package not being installed. Install it if it missing, then restart pulseaudio.<br />
<br />
It can also be due to permission, especially if starting pulseaudio as root allows you to connect. Add your user to the ''lp'' group, then restart pulseaudio.<br />
See {{ic|/etc/dbus-1/system.d/bluetooth.conf}} for reference.<br />
<br />
If the issue is not due to the missing package, the problem in this case is that PulseAudio is not catching up. A common solution to this problem is to restart PulseAudio. Note that it is perfectly fine to run ''bluetoothctl'' as root while PulseAudio runs as user. After restarting PulseAudio, retry to connect. It is not necessary to repeat the pairing.<br />
<br />
If restarting PulseAudio does not work, you need to load module-bluetooth-discover.<br />
<br />
# pactl load-module module-bluetooth-discover<br />
<br />
The same load-module command can be added to {{ic|/etc/pulse/default.pa}}.<br />
<br />
If that still does not work, or you are using PulseAudio's system-wide mode, also load the following PulseAudio modules (again these can be loaded via your {{ic|default.pa}} or {{ic|system.pa}}):<br />
<br />
module-bluetooth-policy<br />
module-bluez5-device<br />
module-bluez5-discover<br />
<br />
It is also possible there are no write [[permissions]] for the owner of {{ic|/var/lib/bluetooth/}}. If this is the case, you may get the device to work by removing and re-pairing it, but the issue will return after rebooting. Restoring write permissions fixes this issue:<br />
<br />
# chmod -R u+w /var/lib/bluetooth<br />
<br />
==== Connecting works, but there are sound glitches all the time ====<br />
<br />
This is very likely to occur when the Bluetooth and the WiFi share the same chip as they share the same physical antenna and possibly band range (2.4GHz). Although this works seamlessly on Windows, this is not the case on Linux.<br />
<br />
A possible solution is to move your WiFi network to 5GHz so that there will be no interference. If your card/router does not support this, you can upgrade your WiFi drivers/firmware. This approach works on Realtek 8723BE and latest rtl drivers for this chip from AUR.<br />
<br />
If nothing of the previous is possible, a less effective mitigation is to tweak the fragment size and the latency on PulseAudio output port, trying to compensate interference. Reasonable values must be chosen, because these settings can make the audio out of sync (e.g. when playing videos). To change the latency of the bluetooth headset's port (e.g. to 125000 microseconds in the following example):<br />
<br />
$ pactl set-port-latency-offset <bluez_card> headset-output '''125000'''<br />
<br />
where the identifier of the card can be found with<br />
<br />
$ pacmd list-sinks | grep -Eo 'bluez_card[^>]*'<br />
<br />
The fragment size can be set in {{ic|/etc/pulse/daemon.conf}} and takes effect after a restart of PulseAudio (for more details please see [[PulseAudio/Troubleshooting#Setting the default fragment number and buffer size in PulseAudio]]).<br />
<br />
Perhaps it will help to add {{ic|1=options ath9k btcoex_enable=1}} to the {{ic|/etc/modprobe.d/ath9k.conf}} (with the appropriate bluetooth adapter):<br />
<br />
{{hc|1=/etc/modprobe.d/ath9k.conf|2=<br />
# possibly fix for sound glitches<br />
options ath9k btcoex_enable=1<br />
}}<br />
<br />
Then restart.<br />
<br />
==== Connecting works, but there is no sound ====<br />
<br />
Make sure that you see the following messages in your system log:<br />
<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink<br />
<br />
If you see a message similar to this, you can go on and investigate your PulseAudio configuration. Otherwise, go back and ensure the connection is successful.<br />
<br />
{{Merge|PulseAudio/Troubleshooting|2=The following seems to be general issue: [https://wiki.archlinux.org/index.php?title=PulseAudio/Troubleshooting&diff=next&oldid=421986]}}<br />
<br />
When using [[GDM]], another instance of PulseAudio is started, which "captures" your bluetooth device connection. This can be prevented by [[mask]]ing the pulseaudio socket for the GDM user by doing the following:<br />
<br />
# mkdir -p /var/lib/gdm/.config/systemd/user<br />
# ln -s /dev/null /var/lib/gdm/.config/systemd/user/pulseaudio.socket<br />
<br />
On next reboot the second instance of PulseAudio will not be started.<br />
<br />
It may happen that bluez wrongly considers an headset as not a2dp capable. In this case, search the index of the bluetooth device with<br />
<br />
$ pacmd ls<br />
<br />
Among the output there should be a section related to the bluetooth headset, containing something similar to<br />
<br />
{{hc|1=$ pacmd ls|2=<br />
index: 2<br />
name: <bluez_card.XX_XX_XX_XX_XX_XX><br />
driver: <module-bluez5-device.c><br />
owner module: 27<br />
properties:<br />
device.description = "SONY MDR-100ABN"<br />
device.string = "XX:XX:XX:XX:XX:XX"<br />
device.api = "bluez"<br />
device.class = "sound"<br />
...<br />
}}<br />
<br />
To manually set the profile, run<br />
<br />
$ pacmd set-card-profile 2 a2dp_sink<br />
<br />
where 2 is the index of the device retrieved through {{ic|pacmd ls}}.<br />
<br />
==== Connecting works, but the device does not show up in PulseAudio sinks ====<br />
<br />
If the headphones connect successfully (which can be [[Bluetooth#Pairing|confirmed]] via {{ic|bluetoothctl}}) but do not show up as an output/input sink in {{ic|pavucontrol}}, you can try adding the following policy to your Bluetooth configuration file {{ic|/etc/bluetooth/main.conf}}:<br />
<br />
{{hc|/etc/bluetooth/main.conf|2=<br />
[General]<br />
Enable=Control,Gateway,Headset,Media,Sink,Socket,Source<br />
}}<br />
<br />
Some users [https://bbs.archlinux.org/viewtopic.php?id=234790 report] that this has solved their problem.<br />
<br />
==== Connecting works, sound plays fine until headphones become idle, then stutters ====<br />
<br />
If the headphones play sound correctly until they become idle and then stutter on resume (e.g. because the sound is paused, or because no sound is played for a while), try disabling PulseAudio's automatic sink/source suspension on idle.<br />
<br />
Some user [https://bbs.archlinux.org/viewtopic.php?id=117420 reports] huge delays or even no sound when the Bluetooth connection does not send any data. This is due to the {{ic|module-suspend-on-idle}} module, which automatically suspends sinks/sources on idle. As this can cause problems with headset, the responsible module can be deactivated.<br />
<br />
To disable loading of the {{ic|module-suspend-on-idle}} module, comment out the following line in the configuration file in use ({{ic|~/.config/pulse/default.pa}} or {{ic|/etc/pulse/default.pa}}):<br />
<br />
{{hc|~/.config/pulse/default.pa|<br />
### Automatically suspend sinks/sources that become idle for too long<br />
#load-module module-suspend-on-idle<br />
}}<br />
<br />
Finally restart PulseAudio to apply the changes.<br />
<br />
==== UUIDs has unsupported type ====<br />
<br />
During pairing you might see this output in ''bluetoothctl'':<br />
<br />
[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type<br />
<br />
This message is a very common one and can be ignored.<br />
<br />
==== PC shows device as paired, but is not recognized by device ====<br />
<br />
This might be due to the device not supporting bluetooth LE for pairing. <br />
<br />
Try setting {{ic|1=ControllerMode = bredr}} in {{ic|/etc/bluetooth/main.conf}}. See [https://unix.stackexchange.com/questions/292189/pairing-bose-qc-35-over-bluetooth-on-fedora].<br />
<br />
==== Device connects, then disconnects after a few moments ====<br />
<br />
If you see messages like the following in the [[journal]], and your device fails to connect or disconnects shortly after connecting:<br />
<br />
bluetoothd: Unable to get connect data for Headset Voice gateway: getpeername: Transport endpoint is not connected (107)<br />
bluetoothd: connect error: Connection refused (111)<br />
<br />
This may be because you have already paired the device with another operating system using the same bluetooth adapter (e.g., dual-booting). Some devices cannot handle multiple pairings associated with the same MAC address (i.e., bluetooth adapter). You can fix this by re-pairing the device. Start by removing the device:<br />
<br />
$ bluetoothctl<br />
[bluetooth]# devices<br />
Device XX:XX:XX:XX:XX:XX My Device<br />
[bluetooth]# remove XX:XX:XX:XX:XX:XX<br />
<br />
Then [[restart]] {{ic|bluetooth.service}}, turn on your bluetooth adapter, make your device discoverable, re-scan for devices, and re-pair your device. Depending on your bluetooth manager, you may need to perform a full reboot in order to re-discover the device.<br />
<br />
==== Apple AirPods have low volume ====<br />
<br />
Create a [[drop-in file]] for {{ic|bluetooth.service}} with the following contents:<br />
<br />
{{hc|/etc/systemd/system/bluetooth.service.d/noplugin-avrc.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/lib/bluetooth/bluetoothd --noplugin=avrcp<br />
}}<br />
<br />
Then, [[restart]] {{ic|bluetooth.service}}, [[reload]] its configuration, and reconnect your headset.<br />
<br />
Additionally, for AirPods Pro, disable the spatial audio and enable Mono in the settings of your iPhone.<br />
<br />
This can also solve issues with some devices that are unable to be controlled through AVRCP.<br />
<br />
==== Apple AirPods Pro working with PulseAudio as A2DP Sink but not with HSP/HFP ====<br />
<br />
If you find that AirPods Pro are working with PulseAudio, but are incapable of using the HSP/HFP configurations (in ''pavucontrol''<nowiki/>'s ''Configurations'' tab, usually listed as unavailable), try switching to {{Pkg|pipewire-pulse}}.<br />
<br />
Note that switching to ''pipewire-pulse'' (and restarting your computer or the appropriate user-level ''systemd'' services) should enable HSP/HFP, but may also disable A2DP. (When selecting ''A2DP Sink'' in the ''Configurations'' tab, the option is instantly deselected and becomes ''Off''.) If you encounter this issue, try removing/renaming the {{ic|/var/lib/bluetooth}} folder like so:<br />
<br />
# mv /var/lib/bluetooth /var/lib/bluetooth.bak<br />
<br />
Re-pair your AirPods Pro (and other devices) afterwards. This should make all configurations (HSP/HFP and A2DP) available again and easily accessible from ''pavucontrol'' and ''pacmd''.<br />
<br />
==== HSP problem: the bluetooth sink and source are created, but no audio is being transmitted ====<br />
<br />
You may be missing firmware or the SCO (audio protocol of HSP and HFP) routing might be wrong. See [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Bluetooth/#index10h3] - the firmware for BCM20702 can be installed via {{AUR|bcm20702a1-firmware}} or {{AUR|bcm20702b0-firmware}}.<br />
<br />
==== Error: Failed to start discovery org.bluez.Error.InProgress ====<br />
<br />
If your headset is discovered, but fails to connect with the error "Failed to start discovery org.bluez.Error.InProgress", install {{AUR|bluez-hciconfig}} and run<br />
<br />
$ hciconfig hci''X'' up<br />
$ hciconfig hci''X'' reset<br />
<br />
where ''X'' is the identifier of your computer's bluetooth device (typically 0).<br />
<br />
You should then be able to connect following the steps in [[#Configuration via CLI]].<br />
<br />
==== High audio volume due to synchronization between headphones and PulseAudio ====<br />
<br />
As of [https://www.freedesktop.org/wiki/Software/PulseAudio/Notes/15.0/#supportforbluetootha2dpavrcpabsolutevolume PulseAudio 15], "Absolute Volume" interlocks the audio volume of your headphones with PulseAudio, making it impossible to change one without the other. On some headphones, e.g. on the Hoco W25, this may result in irritating loudness. To disable "Absolute Volume", edit {{ic|/etc/pulse/default.pa}} and change the line<br />
load-module module-bluetooth-discover<br />
to<br />
load-module module-bluetooth-discover avrcp_absolute_volume=false<br />
<br />
== Switch between HSP/HFP and A2DP setting ==<br />
<br />
This can easily be achieved by the following command where the {{ic|''card_number''}} can be obtained by running {{ic|pacmd list-cards}}.<br />
<br />
$ pacmd set-card-profile ''card_number'' a2dp_sink<br />
<br />
For enabling automatic profile switching from A2DP to HSP when a recording stream appears without any role set, you can append {{ic|1=auto_switch=2}} to {{ic|load-module module-bluetooth-policy}} in {{ic|/etc/pulse/default.pa}}.<br />
<br />
For more information about PulseAudio profiles, see [https://freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Bluetooth/#index1h2 PulseAudio Documentation].<br />
<br />
=== A2DP not working with PulseAudio ===<br />
<br />
==== Socket interface problem ====<br />
<br />
If PulseAudio fails when changing the profile to A2DP with bluez 4.1+ and PulseAudio 3.0+, you can try disabling the Socket interface from {{ic|/etc/bluetooth/main.conf}} by removing the line {{ic|1=Enable=Socket}} and adding line {{ic|1=Disable=Socket}}.<br />
<br />
==== A2DP sink profile is unavailable ====<br />
<br />
When the A2DP sink profile is unavailable it will not be possible to switch to the A2DP sink (output) with a PulseAudio front-end and the A2DP sink will not even be listed. This can be confirmed with {{ic|pactl}}.<br />
<br />
$ pactl list | grep -C2 A2DP<br />
Profiles:<br />
headset_head_unit: Headset Head Unit (HSP/HFP) (sinks: 1, sources: 1, priority: 30, available: yes)<br />
a2dp_sink: High Fidelity Playback (A2DP Sink) (sinks: 1, sources: 0, priority: 40, available: no)<br />
off: Off (sinks: 0, sources: 0, priority: 0, available: yes)<br />
Active Profile: headset_head_unit<br />
<br />
Trying to manually set the card profile with {{ic|pacmd}} will fail.<br />
<br />
$ pacmd set-card-profile bluez_card.C4_45_67_09_12_00 a2dp_sink<br />
Failed to set card profile to 'a2dp_sink'.<br />
<br />
This is known to happen from version 10.0 of PulseAudio when connecting to Bluetooth headphones via Bluedevil or another BlueZ front-end. See [https://gitlab.freedesktop.org/pulseaudio/pulseaudio/issues/525 related bug report.]<br />
<br />
This issue also appears after initial pairing of Headphones with some Bluetooth controllers (e.g. {{ic|0a12:0001, Cambridge Silicon Radio}}) which might default to the {{ic|Handsfree}} or {{ic|Headset - HS}} service and will not allow switching to the A2DP PulseAudio sink that requires the {{ic|AudioSink}} service.<br />
<br />
Possible solutions:<br />
<br />
* For some headsets, using the headset's volume or play/pause controls while connected can trigger the A2DP profile to become available.<br />
* It is possible that connecting to a headset via {{ic|bluetoothctl}} from {{pkg|bluez-utils}} will make the A2DP sink profile available. There is an automation for this every time a bluetooth device is connected: {{AUR|fix-bt-a2dp}} ([https://github.com/pastleo/fix-bt-a2dp#usage detailed usage])<br />
<br />
[bluetooth]# connect ''headset_MAC_address''<br />
<br />
* Manually switching to Bluetooth's {{ic|AudioSink}} service which would make the A2DP profile and its A2DP PulseAudio sink available. This can be done with blueman-manager which included in {{pkg|blueman}} or by registering the UUID of the AudioSink service with {{ic|bluetoothctl}}.<br />
<br />
$ bluetoothctl<br />
[bluetooth]# menu gatt<br />
[bluetooth]# register-service 0000110b-0000-1000-8000-00805f9b34fb<br />
[bluetooth]# quit<br />
<br />
* Disable the headset profile<br />
<br />
{{hc|/etc/bluetooth/main.conf|2=<br />
[General]<br />
Disable=Headset<br />
}}<br />
<br />
* Enable MultiProfile support. This may help with headsets that support A2DP as well as Headset audio.<br />
<br />
{{hc|/etc/bluetooth/main.conf|2=<br />
[General]<br />
MultiProfile=multiple<br />
}}<br />
<br />
* Sometimes, none of the steps above will work. You may have tried rebooting and powering bluetooth off and on to no avail. In this case, try [[restart]]ing the {{ic|bluetooth.service}}.<br />
* For some headphone models with audio control panel, the A2DP profile must be enabled by pressing the ''Play/Pause'' button on the panel.<br />
<br />
==== Gnome with GDM ====<br />
<br />
{{Merge|#Connecting works, but I cannot play sound|duplicate instructions}}<br />
<br />
The instructions below were tested on Gnome 3.24.2 and PulseAudio 10.0 however they may still be applicable and useful for other versions.<br />
<br />
If PulseAudio fails when changing the profile to A2DP while using GNOME with GDM, you need to prevent GDM from starting its own instance of PulseAudio:<br />
<br />
* Prevent PulseAudio clients from automatically starting a server if one is not running by adding the following:<br />
<br />
{{hc|/var/lib/gdm/.config/pulse/client.conf|2=<br />
autospawn = no<br />
daemon-binary = /bin/true<br />
}}<br />
<br />
* Prevent systemd from starting PulseAudio anyway with socket activation:<br />
<br />
$ sudo -ugdm mkdir -p /var/lib/gdm/.config/systemd/user<br />
$ sudo -ugdm ln -s /dev/null /var/lib/gdm/.config/systemd/user/pulseaudio.socket<br />
<br />
* Restart, and check that there is no PulseAudio process for the {{ic|gdm}} user using:<br />
<br />
$ pgrep -u gdm pulseaudio<br />
<br />
Further discussion about this problem and alternative fixes can be found at [https://bbs.archlinux.org/viewtopic.php?id=194006] and [https://bbs.archlinux.org/viewtopic.php?id=196689]. Alternatively, one may try and install {{AUR|fix-bt-a2dp}}.<br />
<br />
=== HFP not working with PulseAudio ===<br />
<br />
{{Note|Some users have reported success in enabling HFP support by replacing PulseAudio with PipeWire for Bluetooth support. [https://www.reddit.com/r/archlinux/comments/w69mij/hfp_audio_is_no_longer_available_stuck_on/] See [[#Headset via PipeWire]] for installation instructions.}}<br />
<br />
HFP-only bluetooth headsets may not be usable in the standard configuration of PulseAudio. The respective profiles occur, but they are not available:<br />
<br />
{{hc|bluetoothctl info|<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)<br />
}}<br />
<br />
{{hc|pactl list|<br />
...<br />
Profiles:<br />
...<br />
headset_head_unit: Headset Head Unit (HSP/HFP) (sinks: 1, sources: 1, priority: 30, available: no)<br />
}}<br />
<br />
To solve the respective issue, update PulseAudio and BlueZ to latest versions. Then [[install]] {{AUR|ofono}} and {{AUR|phonesim}} then create / activate a fake modem as described here [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Bluetooth/#index1h3]:<br />
<br />
{{Note|The steps following the creation of {{ic|phonesim.conf}} should be done ''every time'' you want to connect the headset.}}<br />
<br />
* Create {{ic|/etc/ofono/phonesim.conf}} with:<br />
<br />
[phonesim]<br />
Address=127.0.0.1<br />
Driver=phonesim<br />
Port=12345<br />
<br />
* Start as user:<br />
<br />
$ phonesim -p 12345 /usr/share/phonesim/default.xml &<br />
<br />
* [[Enable/start]] the {{ic|ofono.service}}.<br />
* Power modem:<br />
<br />
$ dbus-send --print-reply --system --dest=org.ofono /phonesim org.ofono.Modem.SetProperty string:"Powered" variant:boolean:true<br />
<br />
* Activate modem:<br />
<br />
$ dbus-send --print-reply --system --dest=org.ofono /phonesim org.ofono.Modem.SetProperty string:"Online" variant:boolean:true<br />
<br />
* To check the results, use the test commands from {{AUR|ofono}} installed in {{ic|/usr/lib/ofono/test/}}. To power, activate, and test the modem you can use:<br />
<br />
$ /usr/lib/ofono/test/enable-modem /phonesim<br />
$ /usr/lib/ofono/test/online-modem /phonesim<br />
$ /usr/lib/ofono/test/list-modems<br />
<br />
The output of the respective modem section should read like this:<br />
<br />
...<br />
[ /phonesim ]<br />
Online = 1<br />
Powered = 1<br />
Lockdown = 0<br />
Emergency = 0<br />
Manufacturer = MeeGo<br />
...<br />
<br />
* Finally, restart PulseAudio and reconnect headset. Now, HFP should be available:<br />
<br />
headset_head_unit: Headset Head Unit (HSP/HFP) (sinks: 1, sources: 1, priority: 30, available: yes)<br />
<br />
{{Note|HFP support is not stable and may cause glitches with switching to A2DP; try reconnecting, if the needed mode is not available.}}<br />
<br />
=== Disable PulseAudio auto switching headset to HSP/HFP ===<br />
<br />
When using a bluetooth headset that supports multiple profiles, some applications switch to HSP/HFP profile automatically. If this behaviour is undesired you can disable this by appending the auto_switch=false parameter to the bluetooth-policy module:<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
load-module module-bluetooth-policy auto_switch=false<br />
}}<br />
<br />
=== Disable PipeWire HSP/HFP profile ===<br />
<br />
Unlike PulseAudio, [[PipeWire#Automatic profile selection|PipeWire does not automatically switch between A2DP and HSP/HFP]] in response to input events. However, rather than to enable automatically switching to the (lower audio quality) HSP/HFP profile if A2DP fails, you may prefer to disable the former altogether. To do so, make a copy of {{ic|/usr/share/wireplumber/bluetooth.lua.d/50-bluez-config.lua}} [https://www.reddit.com/r/archlinux/comments/x29emb/purge_hsphfp_support/] as shown below.<br />
<br />
{{Note|HSP mode is required for built-in microphones to work [https://www.reddit.com/r/pop_os/comments/otofgt/bluetooth_headphone_switches_to_hsphfp_when/].}}<br />
<br />
{{hc|/etc/wireplumber/bluetooth.lua.d/50-bluez-config.lua (or ~/.config/wireplumber/bluetooth.lua.d/50-bluez-config.lua)|2=<br />
...<br />
bluez_monitor.properties = {<br />
...<br />
'''["bluez5.roles"] = "[ a2dp_sink ]",'''<br />
...<br />
'''["bluez5.hfphsp-backend"] = "none",'''<br />
}<br />
...<br />
bluez_monitor.rules = {<br />
{<br />
...<br />
apply_properties = {<br />
...<br />
'''["bluez5.auto-connect"] = "[ a2dp_sink ]",'''<br />
...<br />
''' ["bluez5.hw-volume"] = "[ a2dp_sink ]",'''<br />
},<br />
...<br />
},<br />
}<br />
}}<br />
<br />
=== Alternative: A2DP duplex channel ===<br />
<br />
FastStream, AptX LL, and "Opus 05 Pro" ([https://gitlab.freedesktop.org/pipewire/pipewire/-/merge_requests/1322 a pipewire invention]) have a "duplex" channel that allows for sending microphone audio back without needing to go into HSP/HFP and tolerate the sound quality degradation. PipeWire, but not PulseAudio, has support for this feature. Support is automatic upon feature detection. Interaction with existing profile switcher (WirePlumber) is unknown.<br />
<br />
== Tips and tricks ==<br />
<br />
The following applies to both PipeWire and PulseAudio.<br />
<br />
=== Battery level reporting ===<br />
<br />
{{Note|This is an experimental feature. Enabling it may prevent some Bluetooth mice from connecting automatically (see [https://github.com/bluez/bluez/issues/236 GitHub issue]).}}<br />
<br />
To get the current battery level of your headset reported to {{Pkg|upower}}, you must enable bluez' D-Bus experimental features as described in [[Bluetooth#Enabling experimental features]].<br />
<br />
=== Media controls ===<br />
<br />
To use the media controls they may be forwarded to MPRIS, where they can be picked up by media players that support MPRIS for external control. See [[MPRIS#Bluetooth]] for details.<br />
<br />
=== AVRCP Media controls ===<br />
<br />
This may be desired for bluetooth headsets with overly sensitive touch controls, and AVRCP playback controls can be disabled through the {{ic|inhibited}} sysfs file corresponding to the virtual AVRCP input device, for example {{ic|/sys/devices/virtual/input/input877/inhibited}}. The correct virtual input can be identified via the {{ic|name}} attribute, {{ic|/sys/devices/virtual/input/input877/name}}, which may for example be "Soundcore Life P3 (AVRCP)". Echoing {{ic|1}} to this file inhibits/disables AVRCP, and echoing {{ic|0}} re-enables it. This can be changed dynamically at runtime without restarting bluetoothd or disconnecting your device.<br />
<br />
This will be reset on device disconnect and reconnect, so it is likely desired to automatically set it via a [[udev]] rule such as:<br />
<br />
SUBSYSTEM=="input" ATTR{name}=="Soundcore Life P3 (AVRCP)" ATTR{inhibited}="1"<br />
<br />
If you want to be able to change this attribute as a regular user, see [[udev#Allowing_regular_users_to_use_devices]]</div>Iaz3https://wiki.archlinux.org/index.php?title=KDE&diff=793730KDE2023-12-01T21:28:34Z<p>Iaz3: /* Plasma cursor sometimes shown incorrectly */ Fix formatting issue</p>
<hr />
<div>[[Category:KDE]]<br />
[[de:KDE]]<br />
[[es:KDE]]<br />
[[fa:KDE]]<br />
[[it:KDE]]<br />
[[ja:KDE]]<br />
[[pt:KDE]]<br />
[[ru:KDE]]<br />
[[zh-hans:KDE]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|Window manager}}<br />
{{Related|Qt}}<br />
{{Related|SDDM}}<br />
{{Related|Dolphin}}<br />
{{Related|KDE Wallet}}<br />
{{Related|KDevelop}}<br />
{{Related|Trinity}}<br />
{{Related|Uniform look for Qt and GTK applications}}<br />
{{Related|Official repositories#kde-unstable}}<br />
{{Related articles end}}<br />
<br />
KDE is a software project currently comprising a [[desktop environment]] known as Plasma, a collection of libraries and frameworks (KDE Frameworks) and several applications (KDE Applications) as well. KDE upstream has a well maintained [https://userbase.kde.org/ UserBase wiki]. Detailed information about most KDE applications can be found there.<br />
<br />
== Installation ==<br />
<br />
=== Plasma ===<br />
<br />
Before installing Plasma, make sure you have a working [[Xorg]] installation on your system.<br />
<br />
[[Install]] the {{Pkg|plasma-meta}} meta-package or the {{Grp|plasma}} group. For differences between {{Pkg|plasma-meta}} and {{Grp|plasma}} reference [[Package group]]. Alternatively, for a more minimal Plasma installation, install the {{Pkg|plasma-desktop}} package. Upstream KDE has [https://community.kde.org/Distributions/Packaging_Recommendations package and setup recommendations] to get a fully-featured Plasma session.<br />
<br />
To enable support for [[Wayland]] in Plasma, also [[install]] the {{Pkg|plasma-wayland-session}} package. If you are an [[NVIDIA]] user with the proprietary {{Pkg|nvidia}} driver, also enable the [[NVIDIA#DRM kernel mode setting|DRM kernel mode setting]]. If that does not work, too, check the instructions on the [https://community.kde.org/Plasma/Wayland/Nvidia KDE wiki].<br />
<br />
=== Plasma Mobile ===<br />
<br />
[[Install]] {{AUR|plasma-mobile}}.<br />
<br />
=== KDE applications ===<br />
<br />
To install the full set of KDE Applications, install the {{Grp|kde-applications}} group or the {{Pkg|kde-applications-meta}} meta-package. If you only want KDE applications for a certain category such as games or education, install the relevant dependency of {{Pkg|kde-applications-meta}}. Note that this will only install applications, it will not install any version of Plasma.<br />
<br />
=== Unstable releases ===<br />
<br />
See [[Official repositories#kde-unstable]] for beta releases.<br />
<br />
== Starting Plasma ==<br />
<br />
{{Note|Although it is possible to launch Plasma under [[Wayland]], there are some missing features and known problems. See [https://community.kde.org/Plasma/Wayland_Showstoppers Wayland Showstoppers] for a list of issues and the [https://phabricator.kde.org/project/board/99/ Plasma on Wayland workboard] for the current state of development. Use [[Xorg]] for the most complete and stable experience.}}<br />
<br />
Plasma can be started either using a [[display manager]], or from the console.<br />
<br />
=== Using a display manager ===<br />
<br />
{{Tip|The preferred [[display manager]] is [[SDDM]].}}<br />
<br />
* Select ''Plasma (X11)'' to launch a new session in [[Xorg]].<br />
* Select ''Plasma (Wayland)'' to launch a new session in [[Wayland]].<br />
* Select ''Plasma Mobile (Wayland)'' to launch a new Plasma Mobile session in [[Wayland]].<br />
<br />
=== From the console ===<br />
<br />
* To start Plasma with [[xinit|xinit/startx]], append {{ic|1=export DESKTOP_SESSION=plasma}} and {{ic|exec startplasma-x11}} to your {{ic|.xinitrc}} file. If you want to start Xorg at login, please see [[Start X at login]].<br />
* To start a Plasma on Wayland session from a console, run {{ic|1=startplasma-wayland}}[https://community.kde.org/KWin/Wayland#Start_a_Plasma_session_on_Wayland]. Manually starting a dbus-session through {{ic|1=dbus-run-session}} should not be needed [https://invent.kde.org/plasma/plasma-workspace/-/merge_requests/128].<br />
<br />
== Configuration ==<br />
<br />
Most settings for KDE applications are stored in {{ic|~/.config/}}. However, configuring KDE is primarily done through the '''System Settings''' application. It can be started from a terminal by executing {{ic|systemsettings}}.<br />
<br />
=== Personalization ===<br />
<br />
==== Plasma desktop ====<br />
<br />
===== Themes =====<br />
<br />
There are different types of KDE themes, varying by scope of what they modify:<br />
<br />
* [https://store.kde.org/browse?cat=121 Global themes], comprehensive packages that can include Plasma themes, application styles, colors, fonts, icons, cursors, splash screens, SDDM themes, and Konsole color schemes.<br />
* [https://store.kde.org/browse?cat=104 Plasma themes], modifying the look of Plasma panels and widgets. These often have a recommended accompanying Kvantum or Aurorae theme to complete the look.<br />
* [https://store.kde.org/browse?cat=421 Application styles], modifying the look of programs.<br />
* Application styles that use [[Uniform look for Qt and GTK applications#Theme engines|theme engines]] such as [[Uniform look for Qt and GTK applications#Kvantum|Kvantum]], [[Qt#Styles in Qt 5|QtCurve]] [https://store.kde.org/browse?cat=119], [https://github.com/DexterMagnific/QSvgStyle QSvgStyle] [https://store.kde.org/browse?cat=622], and [https://store.kde.org/p/1167275/ Aurorae].<br />
* [[#Icon themes]], providing icons for applications, files, and actions.<br />
<br />
For easy system-wide installation and updating, some themes are available in both the [https://archlinux.org/packages/?sort=&q=kde+theme&maintainer=&flagged= official repositories] and the [https://aur.archlinux.org/packages?O=0&K=kde+theme AUR].<br />
<br />
Global themes can also be installed through ''System Settings > Appearance > Global Theme > Get New Global Themes...''.<br />
<br />
====== GTK application appearance ======<br />
<br />
{{Tip|For Qt and GTK theme consistency, see [[Uniform look for Qt and GTK applications]].}}<br />
<br />
The recommended theme for a pleasant appearance in GTK applications is {{Pkg|breeze-gtk}}, a GTK theme designed to mimic the appearance of Plasma's Breeze theme.<br />
Install {{Pkg|kde-gtk-config}} (part of the {{grp|plasma}} group) and select {{ic|Breeze}} as the GTK theme in ''System Settings > Appearance > Application Style > Configure GNOME/GTK Application Style...''.<br />
<br />
{{Out of date|The Plasma GTKd background service overwrites GTK settings on Plasma startup.}}<br />
<br />
In some themes, tooltips in GTK applications have white text on white backgrounds making it difficult to read. To change the colors in GTK2 applications, find the section for tooltips in the {{ic|.gtkrc-2.0}} file and change it. For GTK3 application two files need to be changed, {{ic|gtk.css}} and {{ic|settings.ini}}.<br />
<br />
Some GTK2 programs like {{AUR|vuescan-bin}} still look hardly usable due to invisible checkboxes with the Breeze or Adwaita skin in a Plasma session. To workaround this, install and select e.g. the Numix-Frost-Light skin of the {{AUR|numix-frost-themes}} under ''System Settings > Appearance > Application Style > Configure GNOME/GTK Application Style... > GTK theme''. Numix-Frost-Light looks similar to Breeze.<br />
<br />
===== Faces =====<br />
<br />
Plasma and [[SDDM]] will both use images found at {{ic|/var/lib/AccountsService/icons/}} as users' avatars. To configure with a graphical interface, you can use ''System Settings > Users'', which may first need to be [[install]]ed (see the {{Pkg|plasma-desktop}} package). The file corresponding to your username can be removed to restore the default avatar.<br />
<br />
===== Widgets =====<br />
<br />
[https://store.kde.org/browse?cat=418 Plasmoids] are widgets for plasma desktop shell designed to enhance the functionality of desktop, they can be found on the [https://aur.archlinux.org/packages?K=plasma5-applet AUR].<br />
<br />
Plasmoid scripts can also be installed by right-clicking onto a panel or the desktop and choosing ''Add Widgets > Get New Widgets... > Download New Plasma Widgets''. This will present a front-end for https://store.kde.org/ that allows you to install, uninstall, or update third-party Plasmoid scripts with just one click.<br />
<br />
===== Sound applet in the system tray =====<br />
<br />
[[Install]] {{Pkg|plasma-pa}} or {{Pkg|kmix}} (start Kmix from the Application Launcher). {{Pkg|plasma-pa}} is now installed by default with {{Grp|plasma}}, no further configuration needed.<br />
<br />
{{Note|1=To adjust the [https://bugs.kde.org/show_bug.cgi?id=313579#c28 step size of volume increments/decrements], add e.g. {{ic|1=VolumePercentageStep=1}} in the {{ic|[Global]}} section of {{ic|~/.config/kmixrc}}.}}<br />
<br />
===== Disable panel shadow =====<br />
<br />
As the Plasma panel is on top of other windows, its shadow is drawn over them. [https://bbs.archlinux.org/viewtopic.php?pid=1228394#p1228394] To disable this behaviour without impacting other shadows, [[install]] {{Pkg|xorg-xprop}} and run:<br />
<br />
$ xprop -remove _KDE_NET_WM_SHADOW<br />
<br />
then select the panel with the plus-sized cursor. [https://forum.kde.org/viewtopic.php%3Ff=285&t=121592.html] For automation, install {{Pkg|xorg-xwininfo}} and create the following script:<br />
<br />
{{hc|/usr/local/bin/kde-no-shadow|<nowiki><br />
#!/bin/bash<br />
for WID in $(xwininfo -root -tree | sed '/"Plasma": ("plasmashell" "plasmashell")/!d; s/^ *\([^ ]*\) .*/\1/g'); do<br />
xprop -id $WID -remove _KDE_NET_WM_SHADOW<br />
done<br />
</nowiki>}}<br />
<br />
Make the script [[executable]].<br />
<br />
The script can be run on login with ''Add Script'' in ''Autostart'':<br />
<br />
$ kcmshell5 autostart<br />
<br />
===== Display scaling / High DPI displays =====<br />
<br />
See [[HiDPI#KDE Plasma]].<br />
<br />
==== Plasma Mobile ====<br />
<br />
To use Plasma Mobile on small screens, [https://invent.kde.org/plasma-mobile/plasma-phone-settings plasma-phone-settings] contains several settings which can be applied globally ({{ic|/etc/xdg}}) and/or per user {{ic|~/.config}}.<br />
<br />
===== Applications blacklist =====<br />
<br />
{{ic|/etc/xdg/applications-blacklistrc}} (or {{ic|~/.config/applications-blacklistrc}}) removes applications from the applications menu/launcher to unclutter it.<br />
<br />
===== KDE globals =====<br />
<br />
{{ic|/etc/xdg/kdeglobals}} (or {{ic|~/.config/kdeglobals}}) does the following:<br />
<br />
* Sets the webbrowser to [https://apps.kde.org/angelfish/ Angelfish].<br />
* Sets the look and feel ([https://invent.kde.org/plasma/plasma-mobile/-/tree/master/look-and-feel org.kde.plasma.phone]) such that e.g. windows are maximized and do not have a titlebar.<br />
<br />
===== Lock screen =====<br />
<br />
{{ic|/etc/xdg/kscreenlockerrc}} (or {{ic|~/.config/kscreenlockerrc}}) locks the screen immediately after login. This is useful in combination with [[SDDM#Autologin]].<br />
<br />
===== KWin =====<br />
<br />
{{ic|/etc/xdg/kwinrc}} (or {{ic|~/.config/kwinrc}}) does the following:<br />
<br />
* Disables blur to improve performance.<br />
* Enables the [https://maliit.github.io/ Maliit] virtual keyboard.<br />
<br />
==== Window decorations ====<br />
<br />
[https://store.kde.org/browse/cat/114/ Window decorations] can be found in the [https://aur.archlinux.org/packages?K=kde+window+decoration AUR].<br />
<br />
They can be changed in ''System Settings > Appearance > Window Decorations'', there you can also directly download and install more themes with one click.<br />
<br />
==== Icon themes ====<br />
<br />
Icon themes can be installed and changed on ''System Settings > Appearance > Icons''.<br />
<br />
{{Note|Although all modern Linux desktops share the same icon theme format, desktops like [[GNOME]] use fewer icons (esp. in menus and toolbars). Themes developed for such desktops usually lack icons required by Plasma and KDE applications. It is recommended to install Plasma compatible icon themes instead.}}<br />
<br />
{{Tip|Since some icon themes do not inherit from the default icon theme, some icons may be missing. <br />
To inherit from the Breeze, add {{ic|breeze}} to the {{ic|1=Inherits=}} array in {{ic|/usr/share/icon/''theme-name''/index.theme}}, for example: {{ic|1=Inherits=breeze,hicolor}}. You need to reapply this patch after every update to the icon theme, consider using [[Pacman hooks]] to automate the process.}}<br />
<br />
==== Space efficiency ====<br />
<br />
The Plasma Netbook shell has been dropped from Plasma 5, see the following [https://forum.kde.org/viewtopic.php%3Ff=289&t=126631.html#p335947 KDE forum post]. However, you can achieve something similar by editing the file {{ic|~/.config/kwinrc}} adding {{ic|1=BorderlessMaximizedWindows=true}} in the {{ic|[Windows]}} section.<br />
<br />
==== Thumbnail generation ====<br />
<br />
To allow thumbnail generation for media or document files on the desktop and in Dolphin, install {{Pkg|kdegraphics-thumbnailers}} and {{Pkg|ffmpegthumbs}}.<br />
<br />
Then enable the thumbnail categories for the desktop via ''right click'' on the ''desktop background'' > ''Configure Desktop and Wallpaper...'' > ''Icons'' > ''Configure Preview Plugins...''.<br />
<br />
In ''Dolphin'', navigate to ''Configure > Configure Dolphin... > General > Previews''.<br />
<br />
=== Night Color ===<br />
<br />
Plasma provides a [[Redshift]]-like feature (working on both [[Xorg]] and [[Wayland]]) called Night Color. It makes the colors on the screen warmer to reduce eye strain at the time of your choosing. It can be enabled in ''System Settings > Display and Monitor > Night Color''.<br />
<br />
{{Tip|To have a handy System Tray on/off button for night color you need the {{Pkg|kdeplasma-addons}} and then you can add it.}}<br />
<br />
=== Printing ===<br />
<br />
{{Tip|Use the [[CUPS]] web interface for faster configuration. Printers configured in this way can be used in KDE applications. }}<br />
<br />
You can also configure printers in ''System Settings > Printers''. To use this method, you must first install the following packages {{Pkg|print-manager}}, {{Pkg|cups}}, {{Pkg|system-config-printer}}. See [[CUPS#Configuration]].<br />
<br />
=== Samba/Windows support ===<br />
<br />
If you want to have access to Windows services, install [[Samba]] (package {{Pkg|samba}}).<br />
<br />
The Dolphin share functionality requires the package {{Pkg|kdenetwork-filesharing}} and usershares, which the stock {{ic|smb.conf}} does not have enabled. Instructions to add them are in [[Samba#Enable Usershares]], after which sharing in Dolphin should work out of the box after restarting Samba.<br />
<br />
{{Tip|Use {{ic|*}} (asterisk) for both username and password when accessing a Windows share without authentication in Dolphin's prompt.}}<br />
<br />
Unlike GTK file browsers which utilize GVfs also for the launched program, opening files from Samba shares in Dolphin via KIO makes Plasma copy the whole file to the local system first with most programs (VLC is an exception).<br />
To workaround this, you can use a GTK based file browser like {{Pkg|thunar}} with {{Pkg|gvfs}} and {{Pkg|gvfs-smb}} (and {{Pkg|gnome-keyring}} for saving login credentials) to access SMB shares in a more able way.<br />
<br />
Another possibility is to [[mount]] a Samba share via {{Pkg|cifs-utils}} to make it look to Plasma like if the SMB share was just a normal local folder and thus can be accessed normally.<br />
See [[Samba#Manual mounting]] and [[Samba#Automatic mounting]].<br />
<br />
An GUI solution is available with {{AUR|samba-mounter-git}}, which offers basically the same functionality via an easy to use option located at ''System Settings'' > ''Network Drivers''. However, it might break with new KDE Plasma versions.<br />
<br />
=== KDE Desktop activities ===<br />
<br />
[https://userbase.kde.org/Plasma#Activities KDE Desktop Activities] are special workspaces where you can select specific settings for each activity that apply only when you are using said activity.<br />
<br />
=== Power management ===<br />
<br />
[[Install]] {{Pkg|powerdevil}} for an integrated Plasma power managing service. This service offers additional power saving features, monitor brightness control (if supported) and battery reporting including peripheral devices.<br />
<br />
{{Tip|Integration with [https://pointieststick.com/2021/07/23/this-week-in-kde-power-profiles-and-a-more-polished-kickoff/ power profiles] requires the [[power-profiles-daemon]] optional dependency.<br />
}}<br />
<br />
{{Accuracy|1=Regarding the note below, it might be that the problem is the logind setting ''LidSwitchIgnoreInhibited'' which defaults to ''yes''. [https://bbs.archlinux.org/viewtopic.php?pid=1649022#p1649022]}}<br />
<br />
{{Note|Power Devil may not [[Power management#Power managers|inhibit]] all logind settings (such as the lid close action for laptops). In these cases, the logind setting itself will need to be changed - see [[Power management#Power management]].}}<br />
<br />
=== Autostart ===<br />
<br />
Plasma can autostart applications and run scripts on startup and shutdown. To autostart an application, navigate to ''System Settings > Startup and Shutdown > Autostart'' and add the program or shell script of your choice. For applications, a ''.desktop'' file will be created, for login scripts, a ''.desktop'' file launching the script will be created.<br />
<br />
{{Note|<br />
* Programs can be autostarted on login only, whilst shell scripts can also be run on shutdown or even before Plasma itself starts.<br />
* Shell scripts will only be run if they are marked [[executable]].<br />
* Shell scripts previously placed in {{ic|~/.config/autostart-scripts/}} will get [https://invent.kde.org/plasma/plasma-workspace/-/merge_requests/736 automatically migrated to .desktop files].<br />
}}<br />
<br />
* Place [[Desktop entries]] (i.e. ''.desktop'' files) in the appropriate [[XDG Autostart]] directory.<br />
* Place or symlink shell scripts in one of the following directories:<br />
** {{ic|~/.config/plasma-workspace/env/}}: for executing scripts at login before launching Plasma.<br />
** {{ic|~/.config/plasma-workspace/shutdown/}}: for executing scripts when Plasma exits.<br />
<br />
See [https://docs.kde.org/stable5/en/plasma-workspace/kcontrol/autostart/index.html official documentation].<br />
<br />
=== Phonon ===<br />
<br />
From [[Wikipedia:Phonon (software)|Wikipedia]]:<br />
<br />
:Phonon is the multimedia API provided by KDE and is the standard abstraction for handling multimedia streams within KDE software and also used by several Qt applications.<br />
<br />
:Phonon was originally created to allow KDE and Qt software to be independent of any single multimedia framework such as GStreamer or xine and to provide a stable API for a major version's lifetime.<br />
<br />
Phonon is being widely used within KDE, for both audio (e.g., the System notifications or KDE audio applications) and video (e.g., the [[Dolphin]] video thumbnails). It can use the following backends:<br />
<br />
* [[VLC]]: {{Pkg|phonon-qt5-vlc}}<br />
* [[GStreamer]]: {{Pkg|phonon-qt5-gstreamer}}, see [[GStreamer#Installation]] for additional codec support<br />
* [[mpv]]: {{AUR|phonon-qt5-mpv}}, {{AUR|phonon-qt5-mpv-git}}<br />
<br />
KDE [https://community.kde.org/Distributions/Packaging_Recommendations#Non-Plasma_packages recommends only the VLC backend]. The GStreamer backend is [https://invent.kde.org/libraries/phonon-gstreamer/-/issues/1 unmaintained] but prominent Linux distributions (Kubuntu and Fedora-KDE for example) use it as default because that allows them to easily leave out patented MPEG codecs from the default installation.<br />
<br />
{{Note|1=<br><br />
* Multiple backends can be installed at once and prioritized via the ''phononsettings'' application.<br />
* According to the [https://forum.kde.org/viewtopic.php%3Ff=250&t=126476.html#p335080 KDE forums], the VLC backend lacks support for [[wikipedia:ReplayGain|ReplayGain]].<br />
* If using the VLC backend, you may experience crashes every time Plasma wants to send you an audible warning and in quite a number of other cases as well [https://forum.kde.org/viewtopic.php%3Ff=289&t=135956.html]. A possible fix is to rebuild the VLC plugins cache:<br />
{{bc|# /usr/lib/vlc/vlc-cache-gen /usr/lib/vlc/plugins}}<br />
}}<br />
<br />
=== Backup and restore ===<br />
<br />
KDE Plasma 5 stores personalized desktop settings as configuration files in the [[XDG Base Directory#Specification|XDG_CONFIG_HOME]] folder. Use the [https://github.com/shalva97/kde-configuration-files detail of configuration files] to select and choose a [https://www.addictivetips.com/ubuntu-linux-tips/backup-kde-plasma-5-desktop-linux/ method of backup and restore].<br />
<br />
=== systemd startup ===<br />
<br />
Plasma uses a [[systemd/User|systemd user]] instance to launch and manage all the Plasma services. This is the default startup method since Plasma 5.25, but can be [https://invent.kde.org/plasma/plasma-workspace/-/wikis/Plasma-and-the-systemd-boot disabled to use boot scripts instead] with the following command (however this may stop working in a future release):<br />
<br />
$ kwriteconfig5 --file startkderc --group General --key systemdBoot false<br />
<br />
More details about the implementation can be read in [https://blog.davidedmundson.co.uk/blog/plasma-and-the-systemd-startup/ Edmundson's blog: plasma and the systemd startup].<br />
<br />
=== Spell checking ===<br />
<br />
KDE applications use {{Pkg|sonnet}} for spell checking. See its optional dependencies for the supported [[spell checker]]s.<br />
<br />
Configure it in ''System Settings > Regional Settings > Spell Check''.<br />
<br />
=== Running kwin wayland on NVIDIA ===<br />
<br />
See https://community.kde.org/Plasma/Wayland/Nvidia.<br />
<br />
== Applications ==<br />
<br />
The KDE project provides a suite of applications that integrate with the Plasma desktop. See the {{Grp|kde-applications}} group for a full listing of the available applications. Also see [[:Category:KDE]] for related KDE application pages.<br />
<br />
Aside from the programs provided in KDE Applications, there are many other applications available that can complement the Plasma desktop. Some of these are discussed below.<br />
<br />
=== System administration ===<br />
<br />
==== Terminate Xorg server through KDE System Settings ====<br />
<br />
Navigate to the submenu ''System Settings > Input Devices > Keyboard > Advanced (tab) > "Key Sequence to kill the X server"'' and ensure that the checkbox is ticked.<br />
<br />
==== KCM ====<br />
<br />
KCM stands for ''KC''onfig ''M''odule. KCMs can help you configure your system by providing interfaces in System Settings, or through the command line with ''kcmshell5''.<br />
<br />
* {{App|sddm-kcm|KDE Configuration Module for [[SDDM]].|https://invent.kde.org/plasma/sddm-kcm|{{Pkg|sddm-kcm}}}}<br />
* {{App|kde-gtk-config|GTK2 and GTK3 Configurator for KDE.|https://invent.kde.org/plasma/kde-gtk-config|{{Pkg|kde-gtk-config}}}}<br />
* {{App|System policies|Set of configuration modules which allows administrator to change [[PolicyKit]] settings.|https://invent.kde.org/system/polkit-kde-kcmodules-1|{{AUR|kcm-polkit-kde-git}}}}<br />
* {{App|wacom tablet|KDE GUI for the Wacom Linux Drivers.|https://www.linux-apps.com/p/1127862/|{{Pkg|kcm-wacomtablet}}}}<br />
* {{App|Kcmsystemd|systemd control module for KDE.|https://github.com/rthomsen/kcmsystemd|{{AUR|systemd-kcm}}}}<br />
<br />
More KCMs can be found at [https://www.linux-apps.com/find?search=kcm linux-apps.com].<br />
<br />
=== Desktop search ===<br />
<br />
KDE implements desktop search with a software called [[Baloo]], a file indexing and searching solution.<br />
<br />
=== Web browsers ===<br />
<br />
The following web browsers can integrate with Plasma:<br />
<br />
* {{App|[[Wikipedia:Konqueror|Konqueror]]|Part of the KDE project, supports two rendering engines – KHTML and the [[Chromium]]-based Qt WebEngine.|https://konqueror.org/|{{Pkg|konqueror}}}}<br />
* {{App|[[Wikipedia:Falkon|Falkon]]|A Qt web browser with Plasma integration features, previously known as Qupzilla. It uses Qt WebEngine.|https://userbase.kde.org/Falkon/|{{Pkg|falkon}}}}<br />
* {{App|[[Chromium]]|Chromium and its proprietary variant Google Chrome have limited Plasma integration. [[KDE Wallet#KDE Wallet for Chrome and Chromium|They can use KWallet]] and KDE Open/Save windows.|https://www.chromium.org/|{{Pkg|chromium}}}}<br />
* {{App|[[Firefox]]|Firefox can be configured to better integrate with Plasma. See [[Firefox#KDE integration]] for details.|https://mozilla.org/firefox|{{Pkg|firefox}}}}<br />
<br />
{{Tip|Starting from Plasma 5.13, one can integrate [[Firefox]] or [[Chrome]] with Plasma: providing media playback control from the Plasma tray, download notifications and find open tabs in KRunner. [[Install]] {{pkg|plasma-browser-integration}} and the corresponding browser add-on. Chrome/Chromium support should already be included, for Firefox add-on see [[Firefox#KDE integration]].}}<br />
<br />
=== PIM ===<br />
<br />
KDE offers its own stack for [[Wikipedia:Personal information management|personal information management]] (PIM). This includes emails, contacts, calendar, etc. To install all the PIM packages, you could use the {{Grp|kde-pim}} package group or the {{Pkg|kde-pim-meta}} meta package.<br />
<br />
==== Akonadi ====<br />
<br />
Akonadi is a system meant to act as a local cache for PIM data, regardless of its origin, which can be then used by other applications. This includes the user's emails, contacts, calendars, events, journals, alarms, notes, and so on. Akonadi does not store any data by itself: the storage format depends on the nature of the data (for example, contacts may be stored in vCard format).<br />
<br />
Install {{Pkg|akonadi}}. For additional addons, install {{Pkg|kdepim-addons}}.<br />
<br />
{{Note|<br />
* If you wish to use a database engine other than [[MariaDB]], then when installing the {{Pkg|akonadi}} package, use the following command to skip installing the {{Pkg|mariadb}} dependencies: {{bc|# pacman -S akonadi --assume-installed mariadb}} See also {{Bug|32878}}.<br />
* If Akonadi cannot find {{ic|/usr/bin/mysqld}} upon first start, it will fall back to using SQLite.<br />
}}<br />
<br />
===== MySQL =====<br />
<br />
By default Akonadi will use {{ic|/usr/bin/mysqld}} ([[MariaDB]] by default, see [[MySQL]] for alternative providers) to run a managed MySQL instance with the database stored in {{ic|~/.local/share/akonadi/db_data/}}.<br />
<br />
====== System-wide MySQL instance ======<br />
<br />
Akonadi supports using the system-wide [[MySQL]] for its database.[https://techbase.kde.org/KDE_PIM/Akonadi#Can_Akonadi_use_a_normal_MySQL_server_running_on_my_system.3F]<br />
<br />
{{Expansion|Add instructions.}}<br />
<br />
{{hc|~/.config/akonadi/akonadiserverrc|2=<br />
[%General]<br />
Driver=QMYSQL<br />
<br />
[QMYSQL]<br />
Host=<br />
Name=akonadi_''username''<br />
Options="UNIX_SOCKET=/run/mysqld/mysqld.sock"<br />
StartServer=false<br />
}}<br />
<br />
===== PostgreSQL =====<br />
<br />
Akonadi supports either using the existing system-wide [[PostgreSQL]] instance, i.e. {{ic|postgresql.service}}, or running a PostgreSQL instance with user privileges and the database in {{ic|~/.local/share/akonadi/db_data/}}.<br />
<br />
====== Per-user PostgreSQL instance ======<br />
<br />
[[Install]] {{Pkg|postgresql}} and {{Pkg|postgresql-old-upgrade}}.<br />
<br />
Edit Akonadi configuration file so that it has the following contents:<br />
<br />
{{hc|~/.config/akonadi/akonadiserverrc|2=<br />
[%General]<br />
Driver=QPSQL<br />
}}<br />
<br />
{{Note|<br />
* When Akonadi starts, it will create the {{ic|[QPSQL]}} section and set the appropriate variables in it.<br />
* The database will be stored in {{ic|~/.local/share/akonadi/db_data/}}.<br />
}}<br />
<br />
Start Akonadi with {{ic|akonadictl start}}, and check its status: {{ic|akonadictl status}}.<br />
<br />
{{Note|<br />
* Starting with {{Pkg|akonadi}} 19.08.0-1 the PostgreSQL database cluster in {{ic|~/.local/share/akonadi/db_data/}} will get automatically upgraded when a major PostgreSQL version upgrade is detected.<br />
* For previous {{Pkg|akonadi}} versions major PostgreSQL version upgrades will require a manual database upgrade. Follow the [https://userbase.kde.org/Akonadi/Postgres_update update instructions on KDE UserBase Wiki]. Make sure to adjust the paths to PostgreSQL binaries to those used by {{Pkg|postgresql}} and {{Pkg|postgresql-old-upgrade}}, see [[PostgreSQL#Upgrading PostgreSQL]].<br />
}}<br />
<br />
====== System-wide PostgreSQL instance ======<br />
<br />
This requires an already configured and running [[PostgreSQL]].<br />
<br />
Create a PostgreSQL user account for your user:<br />
<br />
[postgres]$ createuser ''username''<br />
<br />
Create a database for Akonadi:<br />
<br />
[postgres]$ createdb -O ''username'' -E UTF8 --locale=C -T template0 akonadi-''username''<br />
<br />
Configure Akonadi to use the system-wide PostgreSQL:<br />
<br />
{{hc|~/.config/akonadi/akonadiserverrc|2=<br />
[%General]<br />
Driver=QPSQL<br />
<br />
[QPSQL]<br />
Host=/run/postgresql<br />
Name=akonadi-''username''<br />
StartServer=false<br />
}}<br />
<br />
{{Note|Custom port, username and password can be specified with options {{ic|1=Port=}}, {{ic|1=User=}}, {{ic|1=Password=}} in the {{ic|[QPSQL]}} section.}}<br />
<br />
Start Akonadi with {{ic|akonadictl start}}, and check its status: {{ic|akonadictl status}}.<br />
<br />
===== SQLite =====<br />
<br />
To use [[SQLite]], edit the Akonadi configuration file to match the configuration below:<br />
<br />
{{hc|~/.config/akonadi/akonadiserverrc|2=<br />
[%General]<br />
Driver=QSQLITE<br />
}}<br />
<br />
{{Note|<br />
* When Akonadi starts, it will create the {{ic|[QSQLITE]}} section and set the appropriate variables in it.<br />
* The database will be stored as {{ic|~/.local/share/akonadi/akonadi.db}}.<br />
}}<br />
<br />
===== Disabling Akonadi =====<br />
<br />
Users who want to disable Akonadi would need to not start any KDE applications that rely on it. See this [https://userbase.kde.org/Akonadi#Disabling_the_Akonadi_subsystem section in the KDE userbase] for more information.<br />
<br />
=== KDE Connect ===<br />
<br />
[https://community.kde.org/KDEConnect KDE Connect] provides several features to connect your [[Android]] or [[iOS]] phone with your Linux desktop:<br />
<br />
* Share files and URLs to/from KDE from/to any app, without wires.<br />
* Touchpad emulation: Use your phone screen as your computer's touchpad.<br />
* Notifications sync (4.3+): Read your Android notifications from the desktop.<br />
* Shared clipboard: copy and paste between your phone and your computer.<br />
* Multimedia remote control: Use your phone as a remote for Linux media players.<br />
* WiFi connection: no usb wire or bluetooth needed.<br />
* RSA Encryption: your information is safe.<br />
<br />
You will need to install KDE Connect both on your computer and on your phone. For PC, [[install]] {{Pkg|kdeconnect}} package. For Android, install KDE Connect from [https://play.google.com/store/apps/details?id=org.kde.kdeconnect_tp Google Play] or from [https://f-droid.org/packages/org.kde.kdeconnect_tp/ F-Droid]. If you want to browse your phone's filesystem, you need to [[install]] {{Pkg|sshfs}} as well and configure filesystem exposes in your Android app. For iOS, install KDE Connect from the [https://apps.apple.com/app/kde-connect/id1580245991 App Store]. Not all features from the Android version are available on the iOS version.<br />
<br />
To use remote input functionality on a Plasma Wayland session, the {{Pkg|xdg-desktop-portal}} package is required.<br />
<br />
It is possible to use KDE Connect even if you do not use the Plasma desktop. For GNOME users, better integration can be achieved by installing {{AUR|gnome-shell-extension-gsconnect}} instead of {{Pkg|kdeconnect}}. To start the KDE Connect daemon manually, execute {{ic|/usr/lib/kdeconnectd}}.<br />
<br />
If you use a [[firewall]], you need to open UDP and TCP ports {{ic|1714}} through {{ic|1764}}.<br />
<br />
Sometimes, KDE Connect will not detect a phone. You can restart the services by running {{ic|killall kdeconnectd}} and then opening kdeconnect in system settings or running {{ic|kdeconnect-cli --refresh}} followed by {{ic|kdeconnect-cli -l}}. You can also use ''Pair new device > Add devices by IP'' on KDE Connect for Android.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Use a different window manager ===<br />
<br />
It is possible to use a window manager other than KWin with Plasma. This allows you to combine the functionality of the KDE desktop with the utility of a [[tiling window manager]], which may be more fleshed out than KWin tiling scripts.<br />
<br />
The component chooser settings in Plasma [https://github.com/KDE/plasma-desktop/commit/2f83a4434a888cd17b03af1f9925cbb054256ade no longer allows changing the window manager], but you are still able to swap KWin via other methods.<br />
<br />
{{Note|When replacing Kwin with a window manager which does not provide a Compositor (such as Openbox), any desktop compositing effects e.g. transparency will be lost. In this case, install and run a separate Composite manager to provide the effects such as [[Xcompmgr]] or [[picom]].}}<br />
<br />
==== Replacing KWin service ====<br />
<br />
Since KDE 5.25, [https://blog.davidedmundson.co.uk/blog/plasma-and-the-systemd-startup/ Plasma's systemd based startup] is enabled by default.<br />
<br />
To replace KWin in this startup, you must first [[mask]] the {{ic|plasma-kwin_x11.service}} for the current user to prevent it from starting.<br />
<br />
Then, [[create]] a new systemd [[user unit]] to start your preferred WM [https://bugs.kde.org/show_bug.cgi?id=439481#c2]:<br />
<br />
{{hc|1=~/.config/systemd/user/plasma-custom-wm.service|2=<br />
[Install]<br />
WantedBy=plasma-workspace.target<br />
<br />
[Unit]<br />
Description=Plasma Custom Window Manager<br />
Before=plasma-workspace.target<br />
<br />
[Service]<br />
ExecStart=''/path/to/other/wm''<br />
Slice=session.slice<br />
Restart=on-failure<br />
}}<br />
<br />
To use it, do (as [[user unit]]s) a [[daemon-reload]], make sure you have [[mask]]ed {{ic|plasma-kwin_x11.service}} then [[enable]] the newly created {{ic|plasma-custom-wm.service}}.<br />
<br />
{{Note|When using i3 window manager with Plasma, it may be necessary to manually set dialogs to open in floating mode in order for them to correctly appear. For more information, see [[i3#Correct handling of floating dialogs]].}}<br />
<br />
==== Using script-based boot and KDEWM ====<br />
<br />
Plasma's script-based boot is used by disabling [[#systemd startup]]. If you have done so, you can change the window manager by setting the {{ic|KDEWM}} [[environment variable]] before Plasma is invoked.<br />
<br />
===== System-wide =====<br />
<br />
{{Merge|Environment variables#Globally|This technique should be moved into a new section there (2.1.3: Using Xsession), and then this section merged with the previous one.}}<br />
<br />
If you have root access, you can also add an XSession that will be available to all users as an option on the login screen. <br />
<br />
First, create a script with execution permissions as follows:<br />
<br />
{{hc|1=/usr/local/bin/plasma-i3.sh|2=<br />
#!/bin/sh<br />
export KDEWM=/usr/bin/i3<br />
/usr/bin/startplasma-x11<br />
}}<br />
<br />
Replace {{ic|/usr/bin/i3}} to the path to your preferred WM. Ensure the path is correctly set. If KDE is unable to start the window manager, the session will fail and the user will be returned to the login screen.<br />
<br />
Then, to add an XSession, add a file in {{ic|/usr/share/xsessions}} with the following content:<br />
<br />
{{hc|1=/usr/share/xsessions/plasma-i3.desktop|2=<br />
[Desktop Entry]<br />
Type=XSession<br />
Exec=/usr/local/bin/plasma-i3.sh<br />
DesktopNames=KDE<br />
Name=Plasma (i3)<br />
Comment=KDE Plasma with i3 as the WM}}<br />
<br />
==== KDE/Openbox session ====<br />
<br />
The {{Pkg|openbox}} package provides a session for using KDE with [[Openbox]]. To make use of this session, select ''KDE/Openbox'' from the [[display manager]] menu.<br />
<br />
For those starting the session manually, add the following line to your [[xinit]] configuration:<br />
<br />
{{hc|~/.xinitrc|<br />
exec openbox-kde-session<br />
}}<br />
<br />
=== KWin tiling window scripts ===<br />
<br />
{{Style|Use [[Template:App]].}}<br />
<br />
[https://github.com/Bismuth-Forge/bismuth Bismuth], [https://github.com/zeroxoneafour/polonium Polonium] and [https://github.com/esjeon/krohnkite Kröhnkite] are Kwin extensions that tile windows automatically and lets you manage them via keyboard.<br />
<br />
[https://github.com/codeswhite/kzones KZones] is a KWin script that mimicks the behavior of the "Fancy Zones" feature of Microsoft PowerToys.<br />
<br />
=== Configuring monitor resolution / multiple monitors ===<br />
<br />
To enable display resolution management and multiple monitors in Plasma, install {{Pkg|kscreen}}. This provides additional options to ''System Settings > Display and Monitor''.<br />
<br />
=== Configuring ICC profiles ===<br />
<br />
To enable [[ICC profiles]] in Plasma, [[install]] {{Pkg|colord-kde}}. This provides additional options to ''System Settings > Color Corrections''.<br />
<br />
ICC profiles can be imported using ''Add Profile''.<br />
<br />
=== Disable opening application launcher with Super key (Windows key) ===<br />
<br />
To disable this feature you currently can run the following command:<br />
<br />
$ kwriteconfig5 --file kwinrc --group ModifierOnlyShortcuts --key Meta ""<br />
<br />
=== Disable bookmarks showing in application menu ===<br />
<br />
With the Plasma Browser integration installed, KDE will show bookmarks in the application launcher.<br />
<br />
To disable this feature, you can run the following commands:<br />
<br />
$ mkdir ~/.local/share/kservices5<br />
$ sed 's/EnabledByDefault=true$/EnabledByDefault=false/' /usr/share/kservices5/plasma-runner-bookmarks.desktop > ~/.local/share/kservices5/plasma-runner-bookmarks.desktop<br />
<br />
=== IBus Integration ===<br />
<br />
[[IBus]] is an [[Input method#Input method framework|input method framework]] and can be integrated into KDE. See [[IBus#Integration]] for details.<br />
<br />
Using [[IBus]] may be required when using KDE on [[Wayland]] to offer accented characters and dead keys support [https://bugs.kde.org/show_bug.cgi?id=411729].<br />
<br />
=== Enable hotspot in plasma-nm ===<br />
<br />
See [[NetworkManager#Sharing internet connection over Wi-Fi]].<br />
<br />
=== Restore previous saved session ===<br />
<br />
If you have ''System Settings > Startup and Shutdown > Desktop Session > When logging in: Restore previous saved session'' (default) selected, ksmserver (KDE's session manager) will automatically save/load all open applications to/from {{ic|~/.config/ksmserverrc}} on logout/login.<br />
<br />
{{Note|Currently, native Wayland windows cannot be restored. See [https://community.kde.org/Plasma/Wayland_Showstoppers Wayland Showstoppers] for the current state of development.}}<br />
<br />
=== Receive local mail in KMail ===<br />
<br />
If you have set up local mail delivery with a [[mail server]] that uses the [[Wikipedia:Maildir|Maildir]] format, you may want to receive this mail in KMail. To do so, you can re-use KMail's default receiving account "Local Folders" that stores mail in {{ic|~/.local/share/local-mail/}}.<br />
<br />
Symlink the {{ic|~/Maildir}} directory (where Maildir format mail is commonly delivered) to the Local Folders' inbox:<br />
<br />
$ ln -s .local/share/local-mail/inbox ~/Maildir<br />
<br />
Alternatively, add a new receiving account with the type ''Maildir'' and set {{ic|~/Maildir}} as its directory.<br />
<br />
=== Configure Plasma for all users ===<br />
<br />
Edit {{ic|config/main.xml}} files in the {{ic|/usr/share/plasma}}. For example, to configure the Application Launcher for all users, edit {{ic|/usr/share/plasma/plasmoids/org.kde.plasma.kickoff/contents/config/main.xml}}. To prevent the files from being overwritten with package updates, add the files to [[Pacman#Skip file from being upgraded|Pacman's NoUpgrade]]<br />
<br />
=== Disable hibernate ===<br />
<br />
{{Merge|Power management|This is not specific to KDE. Merge and then either leave this section as a stub linking to that one.}}<br />
<br />
Properly disable the hibernate feature and hide it from the menu with a Polkit policy rule.<br />
<br />
{{hc|/etc/polkit-1/rules.d/99-disable-hibernate.rules|<nowiki><br />
// Disable hibernate for all users<br />
polkit.addRule(function(action, subject) {<br />
if ((action.id == "org.freedesktop.login1.hibernate")) {<br />
return polkit.Result.NO;<br />
}<br />
});<br />
polkit.addRule(function(action, subject) {<br />
if ((action.id == "org.freedesktop.login1.hibernate-multiple-sessions")) {<br />
return polkit.Result.NO;<br />
}<br />
});<br />
</nowiki>}}<br />
<br />
Alternatively, add the following lines to a file in {{ic|/etc/systemd/sleep.conf.d/}}:<br />
<br />
{{hc|/etc/systemd/sleep.conf.d/00-disable-hibernation.conf|2=<br />
[Sleep]<br />
AllowHibernation=no<br />
AllowSuspendThenHibernate=no<br />
AllowHybridSleep=no<br />
}}<br />
<br />
=== Using window rules ===<br />
<br />
Kwin has the ability to specify rules for specific windows/applications. For example, you can force enable the window titlebar even if the application developer decided that there should not be one. You can set such rules as specific starting position, size, minimize state, keeping above/below others and so on.<br />
<br />
To create a rule you can press {{ic|Alt+F3}} when the window of interest is in focus. Then, in ''More Actions > Configure special application/window settings'', you can set the desired property. A list of created rules is available from ''System Settings > Window Management > Window Rules''.<br />
<br />
=== Virtual keyboard ===<br />
<br />
There are no virtual keyboards installed by default. Choose an appropriate one from [[List of applications/Utilities#On-screen keyboards]], for example the Maliit keyboard, and install it. Then enable it in System Settings.<br />
<br />
== Troubleshooting ==<br />
<br />
=== qt5ct and kvantum bugs after upgrade ===<br />
<br />
{{Out of date|This was added 2021-02-15 : the "latest update" is one year old, is this fixed ?}}<br />
<br />
Latest update might cause incompatible HiDPI scaling that made some interfaces becomes too big for your screen, some icons are missing or can not be displayed, and missing panels or widgets.<br />
<br />
Try to remove {{Pkg|qt5ct}} and {{Pkg|kvantum}} related package, then apply default global Plasma theme. If the problem persists, try clearing all your KDE configuration and reinstalling {{Grp|plasma}} to overwrite the configuration. Be sure to check HiDPI scaling in KDE system settings as well.<br />
<br />
=== Fonts ===<br />
<br />
==== Fonts in a Plasma session look poor ====<br />
<br />
Try installing the {{Pkg|ttf-dejavu}} and {{Pkg|ttf-liberation}} packages.<br />
<br />
After the installation, be sure to log out and back in. You should not have to modify anything in ''System Settings > Appearance > Fonts''. If you are using {{Pkg|qt5ct}}, the settings in Qt5 Configuration Tool may override the font settings in System Settings.<br />
<br />
If you have personally set up how your [[Fonts]] render, be aware that System Settings may alter their appearance. When you go ''System Settings > Appearance > Fonts'' System Settings will likely alter your font configuration file ({{ic|fonts.conf}}).<br />
<br />
There is no way to prevent this, but, if you set the values to match your {{ic|fonts.conf}} file, the expected font rendering will return (it will require you to restart your application or in a few cases restart your desktop). Note that Gnome's Font Preferences also does this.<br />
<br />
==== Fonts are huge or seem disproportional ====<br />
<br />
Try to force font DPI to {{ic|'''96'''}} in ''System Settings > Appearance > Fonts''.<br />
<br />
If that does not work, try setting the DPI directly in your Xorg configuration as documented in [[Xorg#Setting DPI manually]].<br />
<br />
=== Configuration related ===<br />
<br />
Many problems in KDE are related to its configuration.<br />
<br />
==== Plasma desktop behaves strangely ====<br />
<br />
Plasma problems are usually caused by unstable ''Plasma widgets'' (colloquially called ''plasmoids'') or ''Plasma themes''. First, find which was the last widget or theme you had installed and disable or uninstall it.<br />
<br />
So, if your desktop suddenly exhibits "locking up", this is likely caused by a faulty installed widget. If you cannot remember which widget you installed before the problem began (sometimes it can be an irregular problem), try to track it down by removing each widget until the problem ceases. Then you can uninstall the widget, and file a bug report on the [https://bugs.kde.org/ KDE bug tracker] '''only if it is an official widget'''. If it is not, it is recommended to find the entry on the [https://store.kde.org/ KDE Store] and inform the developer of that widget about the problem (detailing steps to reproduce, etc.).<br />
<br />
If you cannot find the problem, but you do not want ''all'' the settings to be lost, navigate to {{ic|~/.config/}} and run the following command:<br />
<br />
$ for j in plasma*; do mv -- "$j" "${j%}.bak"; done<br />
<br />
This command will rename '''all''' Plasma related configuration files to ''*.bak'' (e.g. {{ic|plasmarc.bak}}) of your user and when you will relogin into Plasma, you will have the default settings back. To undo that action, remove the ''.bak'' file extension. If you already have ''*.bak'' files, rename, move, or delete them first. It is highly recommended that you create regular backups anyway. See [[Synchronization and backup programs]] for a list of possible solutions.<br />
<br />
==== Clean cache to resolve upgrade problems ====<br />
<br />
The [https://bbs.archlinux.org/viewtopic.php?id=135301 problem] may be caused by old cache. Sometimes, after an upgrade, the old cache might introduce strange, hard to debug behaviour such as unkillable shells, hangs when changing various settings, Ark being unable to extract archives or Amarok not recognizing any of your music. This solution can also resolve problems with KDE and Qt applications looking bad after an update.<br />
<br />
Rebuild the cache using the following commands:<br />
<br />
$ rm ~/.config/Trolltech.conf<br />
$ kbuildsycoca5 --noincremental<br />
<br />
Optionally, empty the {{ic|~/.cache/}} folder contents, however, this will also clear the cache of other applications:<br />
<br />
$ rm -rf ~/.cache/*<br />
<br />
==== Plasma desktop does not respect locale/language settings ====<br />
<br />
Plasma desktop may use different settings than you set at KDE System Settings panel, or in {{ic|locale.conf}} (per [[Locale#Variables]]). First thing to do is log out and log in after removing {{ic|~/.config/plasma-localerc}}, if this does not fix the issue, try to edit the file manually. For example, to set {{ic|LANG}} variable to {{ic|es_ES.UTF-8}} and the {{ic|LC_MESSAGES}} variable to {{ic|en_US.UTF-8}}:<br />
<br />
{{hc|~/.config/plasma-localerc|2=<br />
[Formats]<br />
LANG=es_ES.UTF-8<br />
<br />
[Translations]<br />
LANGUAGE=en_US<br />
}}<br />
<br />
==== Cannot change theme, icons, fonts, colors in systemsettings; most icons are not displayed ====<br />
<br />
Make sure that {{ic|QT_QPA_PLATFORMTHEME}} [[environment variable]] is unset, the command {{ic|printenv QT_QPA_PLATFORMTHEME}} should show empty output. Otherwise if you had an environment set (most likely qt5ct) the variable will force qt5ct settings upon Qt applications, the command {{ic|1=export QT_QPA_PLATFORMTHEME=}} should unset the environment.<br />
<br />
An easier (and more reliable) solution can be to uninstall completely qt5ct.<br />
<br />
==== Volume control, notifications or multimedia keys do not work ====<br />
<br />
Hiding certain items in the System Tray settings (e.g. Audio Volume, Media Player or Notifications) also disables related features. Hiding the ''Audio Volume'' disables volume control keys, ''Media Player'' disables multimedia keys (rewind, stop, pause) and hiding ''Notifications'' disables showing notifications.<br />
<br />
==== Login Screen KCM does not sync cursor settings to SDDM ====<br />
<br />
The Login Screen KCM reads your cursor settings from {{ic|~/.config/kcminputrc}}, without this file no settings are synced. The easiest way to generate this file is to change your cursor theme in ''System Settings > Cursors'', then change it back to your preferred cursor theme.<br />
<br />
==== Missing panels/widgets ====<br />
<br />
A crash or hardware change can modify the screen numbers, even on a single monitor setup. The panels/widgets can be missing after such an event, this can be fixed in the {{ic|~/.config/plasma-org.kde.plasma.desktop-appletsrc}} file by changing the {{ic|lastScreen}} values.<br />
<br />
=== Graphical problems ===<br />
<br />
Make sure you have the proper driver for your GPU installed. See [[Xorg#Driver installation]] for more information. If you have an older card, it might help to [[#Disable desktop effects manually or automatically for defined applications]] or [[#Disable compositing]].<br />
<br />
==== Getting current state of KWin for support and debug purposes ====<br />
<br />
This command prints out a summary of the current state of KWin including used options, used compositing backend and relevant OpenGL driver capabilities. See more on [https://blog.martin-graesslin.com/blog/2012/03/on-getting-help-for-kwin-and-helping-kwin/ Martin's blog].<br />
<br />
$ qdbus org.kde.KWin /KWin org.kde.KWin.supportInformation<br />
<br />
==== Disable desktop effects manually or automatically for defined applications ====<br />
<br />
Plasma has desktop effects enabled by default and e.g. not every game will disable them automatically. You can disable desktop effects in ''System Settings > Workspace Behavior > Desktop Effects'' and you can toggle desktop effects with {{ic|Alt+Shift+F12}}. <br />
<br />
Additionally, you can create custom KWin rules to automatically disable/enable compositing when a certain application/window starts under ''System Settings > Window Management > Window Rules''.<br />
<br />
==== Enable transparency ====<br />
<br />
If you use a transparent background without enabling the compositor, you will get the message:<br />
<br />
This color scheme uses a transparent background which does not appear to be supported on your desktop<br />
<br />
In ''System Settings > Display and Monitor > Compositor'', check ''Compositing: Enable on startup'' and restart Plasma.<br />
<br />
==== Disable compositing ====<br />
<br />
In ''System Settings > Display and Monitor > Compositor'', uncheck ''Compositing: Enable on startup'' and restart Plasma.<br />
<br />
==== Flickering in fullscreen when compositing is enabled ====<br />
<br />
In ''System Settings > Display and Monitor > Compositor'', uncheck ''Compositing: Allow applications to block compositing''. This may harm performance.<br />
<br />
==== Plasma cursor sometimes shown incorrectly ====<br />
<br />
Create the directory {{ic|~/.icons/default}} and inside a file named {{ic|index.theme}} with the following contents:<br />
<br />
{{hc|~/.icons/default/index.theme|2=<br />
[Icon Theme]<br />
Inherits=breeze_cursors<br />
}}<br />
<br />
Execute the following command:<br />
<br />
$ ln -s /usr/share/icons/breeze_cursors/cursors ~/.icons/default/cursors<br />
<br />
On Wayland, it is neccessary for {{Pkg|xdg-desktop-portal-gtk}} to be be installed for GTK/Gnome apps to correctly apply cursor themes.<br />
<br />
===== Firefox and Thunderbird ignore cursor theme =====<br />
If you have enabled [[Firefox#Wayland]] support, Firefox and Thunderbird will refer to GSettings to determine which cursor to display.<br />
<br />
To sync KDE settings to GTK applications, install {{Pkg|kde-gtk-config}}.<br />
<br />
If you do not want to install an extra package, you can set the cursor theme manually:<br />
<br />
$ gsettings set org.gnome.desktop.interface cursor-theme ''cursor-theme-name''<br />
<br />
==== Cursor jerking/flicking when changing roles (e.g., when mousing over hyperlinks) ====<br />
<br />
Try installing the appropriate 2D acceleration driver for your system and window manager.<br />
<br />
==== Unusable screen resolution set ====<br />
<br />
Your local configuration settings for kscreen can override those set in {{ic|xorg.conf}}. Look for kscreen configuration files in {{ic|~/.local/share/kscreen/}} and check if mode is being set to a resolution that is not supported by your monitor.<br />
<br />
==== Blurry icons in system tray ====<br />
<br />
In order to add icons to tray, applications often make use of the library appindicator. If your icons are blurry, check which version of libappindicator you have installed. If you only have {{Pkg|libappindicator-gtk2}} installed, you can install {{Pkg|libappindicator-gtk3}} as an attempt to get clear icons.<br />
<br />
==== Cannot change screen resolution when running in a virtual machine ====<br />
<br />
When running Plasma in a [[VMware]], [[VirtualBox]] or [[QEMU]] virtual machine, kscreen may not allow changing the guest's screen resolution to a resolution higher than 800×600.<br />
<br />
The workaround is to set the {{ic|PreferredMode}} option in {{man|5|xorg.conf.d}}. Alternatively try using a different graphics adapter in the VM, e.g. VBoxSVGA instead of VMSVGA for VirtualBox and Virtio instead of QXL for QEMU. See [https://bugs.kde.org/show_bug.cgi?id=407058 KDE Bug 407058] for details.<br />
<br />
==== Dolphin, Kate, etc. stuck long time when opening ====<br />
<br />
Check whether your user directories ({{ic|Documents}}, {{ic|Downloads}}, etc.) are read-only.<br />
<br />
==== Spectacle screenshot uses old screen state ====<br />
<br />
In ''System Settings > Display and Monitor > Compositor'', change ''Keep window thumbnails'' from ''Only from Shown windows'' to ''Never''. If you're on Intel graphics, ensure that {{Pkg|xf86-video-intel}} is [[Intel graphics#Installation|not installed]].<br />
<br />
=== Sound problems ===<br />
<br />
{{Note|First make sure you have {{Pkg|alsa-utils}} installed.}}<br />
<br />
==== No sound after suspend ====<br />
<br />
If there is no sound after suspending and KMix does not show audio devices which should be there, restarting plasmashell and pulseaudio may help:<br />
<br />
$ killall plasmashell<br />
$ systemctl --user restart pulseaudio.service<br />
$ plasmashell<br />
<br />
Some applications may also need to be restarted in order for sound to play from them again.<br />
<br />
==== MP3 files cannot be played when using the GStreamer Phonon backend ====<br />
<br />
This can be solved by installing the GStreamer libav plugin (package {{Pkg|gst-libav}}). If you still encounter problems, you can try changing the Phonon backend used by installing another such as {{AUR|phonon-qt4-vlc}} or {{Pkg|phonon-qt5-vlc}}.<br />
<br />
Then, make sure the backend is preferred via ''System Settings > Multimedia > Audio and Video > Backend''.<br />
<br />
If the settings does not show any, try {{ic|phononsettings}} in your terminal.<br />
<br />
==== No volume control icon in tray and cannot adjust sound by function key ====<br />
<br />
Check if you have {{Pkg|plasma-pa}} installed.<br />
<br />
==== No sound after a short time ====<br />
<br />
If {{ic|journalctl -p4 -t pulseaudio}} contains entries saying {{ic|Failed to create sink input: sink is suspended}}, try commenting the following line in in {{ic|/etc/pulse/default.pa}}:<br />
<br />
#load-module module-suspend-on-idle<br />
<br />
If the issue persists, {{Pkg|plasma-meta}} or {{Grp|plasma}} may have installed {{Pkg|pulseaudio}} alongside {{Pkg|wireplumber}}. To fix the issue, replace {{Pkg|pulseaudio}} with {{Pkg|pipewire-pulse}}. If {{Pkg|pulseaudio}} is preferred, replace {{Pkg|wireplumber}} with {{Pkg|pipewire-media-session}}. See [[PipeWire#PulseAudio clients]] and [https://bbs.archlinux.org/viewtopic.php?id=276308 this forum thread] for more details.<br />
<br />
=== Power management ===<br />
<br />
==== No Suspend/Hibernate options ====<br />
<br />
If your system is able to suspend or hibernate using [[systemd]] but do not have these options shown in KDE, make sure {{Pkg|powerdevil}} is installed.<br />
<br />
==== No power profile options ====<br />
<br />
Make sure you [[install]]ed {{Pkg|powerdevil}} and {{Pkg|power-profiles-daemon}}.<br />
Run ''powerprofilesctl'' and check the driver. If it is {{ic|intel_pstate}} or {{ic|amd_pstate}}, you are done, otherwise see [[CPU frequency scaling#Scaling drivers]] for more information on enabling them.<br />
<br />
=== KMail ===<br />
<br />
==== Clean Akonadi configuration to fix KMail ====<br />
<br />
See [https://userbase.kde.org/KMail/FAQs_Hints_and_Tips#Clean_start_after_a_failed_migration] for details.<br />
<br />
If you want a backup, copy the following configuration directories:<br />
<br />
$ cp -a ~/.local/share/akonadi ~/.local/share/akonadi-old<br />
$ cp -a ~/.config/akonadi ~/.config/akonadi-old<br />
<br />
==== Empty IMAP inbox in KMail ====<br />
<br />
For some IMAP accounts KMail will show the inbox as a top-level container (so it will not be possible to read messages there) with all other folders of this account inside.[https://bugs.kde.org/show_bug.cgi?id=284172]. To solve this problem simply disable the server-side subscriptions in the KMail account settings.<br />
<br />
==== Authorization error for EWS account in KMail ====<br />
<br />
While setting up EWS account in KMail, you may keep getting errors about failed authorization even for valid and fully working credentials. This is likely caused by broken communication between [[KWallet]] and KMail. To workaround the issue set a passsword via qdbus:<br />
<br />
$ qdbus org.freedesktop.Akonadi.Resource.akonadi_ews_resource_0 /Settings org.kde.Akonadi.Ews.Wallet.setPassword "XXX"<br />
<br />
=== Aggressive QXcbConnection / kscreen.xcb.helper journal logging ===<br />
<br />
See [[Qt#Disable/Change Qt journal logging behaviour]].<br />
<br />
=== KF5/Qt 5 applications do not display icons in i3/FVWM/awesome ===<br />
<br />
See [[Qt#Configuration of Qt 5 applications under environments other than KDE Plasma]].<br />
<br />
=== Problems with saving credentials and persistently occurring KWallet dialogs ===<br />
<br />
It is not recommended to turn off the [[KWallet]] password saving system in the user settings as it is required to save encrypted credentials like WiFi passphrases for each user. Persistently occuring KWallet dialogs can be the consequence of turning it off.<br />
<br />
In case you find the dialogs to unlock the wallet annoying when applications want to access it, you can let the [[Display manager|display managers]] [[SDDM]] and [[LightDM]] unlock the wallet at login automatically, see [[KDE Wallet#Unlock KDE Wallet automatically on login]]. The first wallet needs to be generated by KWallet (and not user-generated) in order to be usable for system program credentials.<br />
<br />
In case you want the wallet credentials not to be opened in memory for every application, you can restrict applications from accessing it with {{Pkg|kwalletmanager}} in the KWallet settings.<br />
<br />
If you do not care for credential encryption at all, you can simply leave the password forms blank when KWallet asks for the password while creating a wallet. In this case, applications can access passwords without having to unlock the wallet first.<br />
<br />
=== Discover does not show any applications ===<br />
<br />
This can be solved by installing {{Pkg|packagekit-qt5}}.<br />
<br />
{{Warning|As explained in a [https://github.com/archlinux/archinstall/issues/1321#issuecomment-1151343223 GitHub comment] by a Package Maintainer, "Handling system packages via packagekit is just fundamentally incompatible with our high-maintenance rolling release distro, where any update might leave the system in an unbootable or otherwise unusable state if the user does not take care reading pacman's logs or merging pacnew files before rebooting."}}<br />
<br />
=== Discover stops showing updates from Arch repositories ===<br />
<br />
Discover sometimes will not remove its PackageKit alpm lock. To release it, remove {{ic|/var/lib/PackageKit/alpm/db.lck}}. Use "Refresh" in Discover and updates should appear (if there are any updates pending).<br />
<br />
=== High CPU usage of kscreenlocker_greet with NVIDIA drivers ===<br />
<br />
As described in [https://bugs.kde.org/show_bug.cgi?id=347772 KDE Bug 347772] NVIDIA OpenGL drivers and QML may not play well together with Qt 5. This may lead {{ic|kscreenlocker_greet}} to high CPU usage after unlocking the session. To work around this issue, set the {{ic|QSG_RENDERER_LOOP}} [[environment variable]] to {{ic|basic}}.<br />
<br />
Then kill previous instances of the greeter with {{ic|killall kscreenlocker_greet}}.<br />
<br />
=== OS error 22 when running Akonadi on ZFS ===<br />
<br />
If your home directory is on a [[ZFS]] pool, create a {{ic|~/.config/akonadi/mysql-local.conf}} file with the following contents:<br />
<br />
[mysqld]<br />
innodb_use_native_aio = 0<br />
<br />
See [[MariaDB#OS error 22 when running on ZFS]].<br />
<br />
=== Some programs are unable to scroll when their windows are inactive ===<br />
<br />
This is caused by the problematic way of GTK3 handling mouse scroll events. A workaround for this is to set [[environment variable]] {{ic|1=GDK_CORE_DEVICE_EVENTS=1}}. However, this workaround also breaks touchpad smooth scrolling and touchscreen scrolling.<br />
<br />
=== TeamViewer behaves slowly ===<br />
<br />
When using TeamViewer, it may behave slowly if you use smooth animations (such as windows minimizing). See [[#Disable compositing]] as a workaround.<br />
<br />
=== Kmail, Kontact and Wayland ===<br />
<br />
Kmail may become unresponsive, show a black messageviewer or similar, often after having been minimized and restored. A workaround may be to set [[environment variable]] {{ic|1=QT_QPA_PLATFORM="xcb;wayland"}}. See [https://bugs.kde.org/show_bug.cgi?id=397825 KDE Bug 397825].<br />
<br />
=== Unlock widgets (Plasma ≥ 5.18) ===<br />
<br />
If you previously locked your widgets, you will probably find yourself unable to unlock them again.<br />
You just have to run this command to do so:<br />
<br />
$ qdbus org.kde.plasmashell /PlasmaShell evaluateScript "lockCorona(false)"<br />
<br />
The new {{ic|Customize Layout}} does not require to lock them back up but if want to do that:<br />
<br />
$ qdbus org.kde.plasmashell /PlasmaShell evaluateScript "lockCorona(true)"<br />
<br />
=== KIO opens URLs with the wrong program ===<br />
<br />
Check file associations regarding HTML, PHP, etc... and change it to a browser. KIO's cache files are located in {{ic|$HOME/.cache/kioexec}}. See also [[xdg-utils#URL scheme handlers]].<br />
<br />
=== Custom Shortcuts tab is missing under Shortcuts in System Settings ===<br />
<br />
This is due to the {{Pkg|khotkeys}} package being missing. After installation, a restart of the System Settings application may be necessary to apply the changes.<br />
<br />
=== Lock the screen before suspending and hibernating ===<br />
<br />
In the System Settings application, KDE offers a setting to automatically lock the screen after waking up from sleep. Upon resuming, [https://www.reddit.com/r/kde/comments/obnpeb/how_to_lock_system_before_suspend/ some users] report that the screen is briefly showed before locking. To prevent this behavior and have KDE lock the screen before suspending, create a hook in {{man|1|systemd}} by creating the following file as the root user:<br />
<br />
{{hc|/usr/lib/systemd/system-sleep/lock_before_suspend.sh|2=<br />
#!/bin/bash<br />
<br />
case $1/$2 in<br />
pre/*)<br />
case $2 in<br />
suspend{{!}}hibernate)<br />
loginctl lock-session<br />
sleep 1<br />
;;<br />
esac<br />
;;<br />
esac<br />
}}<br />
<br />
The use of ''sleep'' is necessary in order for the lock-session to complete before the device is suspended. Lower value do not allow for completion. <br />
<br />
After creating the file, make it [[executable]]. <br />
<br />
Finally, make sure that the KDE setting is enabled by going to ''System Settings > Workspace Behavior > Screen Locking'' and checking the ''After waking from sleep'' checkbox.<br />
<br />
=== X11 shortcuts conflict on Wayland ===<br />
<br />
Some X11 software like {{Pkg|freerdp}} can grab keyboard input since KDE 5.27. Others like [[VMware]] cannot grab correctly. [https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml]<br />
<br />
It is inappropriate to force grab [https://gitlab.freedesktop.org/xorg/xserver/-/issues/1332 in Xserver] or in compositors. [https://gitlab.gnome.org/GNOME/mutter/-/issues/1720] You can solve it in an elegant way as follows:<br />
<br />
* Right click the window titlebar (e.g. VMware or Citrix);<br />
* ''More Actions > Configure Special Window Settings...''<br />
* Click ''Add Property...'' and select ''Ignore global shortcuts''. <br />
* Select ''force'' and ''yes''. Apply it.<br />
<br />
== See also ==<br />
<br />
* [https://www.kde.org/ KDE homepage]<br />
* [https://dot.kde.org/ KDE news]<br />
* [https://planet.kde.org/ KDE Blogs]<br />
* [https://discuss.kde.org/ KDE Forums]<br />
* [https://wiki.kde.org/ KDE Wikis]<br />
* [https://bugs.kde.org/ KDE bug tracker and reporter]<br />
* [https://blog.martin-graesslin.com/blog/kategorien/kde/ Martin Graesslin's blog]<br />
* [https://community.kde.org/Matrix KDE Matrix Rooms]</div>Iaz3https://wiki.archlinux.org/index.php?title=KDE&diff=793729KDE2023-12-01T21:27:19Z<p>Iaz3: /* Plasma cursor sometimes shown incorrectly */ Add KDE cursor fix info</p>
<hr />
<div>[[Category:KDE]]<br />
[[de:KDE]]<br />
[[es:KDE]]<br />
[[fa:KDE]]<br />
[[it:KDE]]<br />
[[ja:KDE]]<br />
[[pt:KDE]]<br />
[[ru:KDE]]<br />
[[zh-hans:KDE]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|Window manager}}<br />
{{Related|Qt}}<br />
{{Related|SDDM}}<br />
{{Related|Dolphin}}<br />
{{Related|KDE Wallet}}<br />
{{Related|KDevelop}}<br />
{{Related|Trinity}}<br />
{{Related|Uniform look for Qt and GTK applications}}<br />
{{Related|Official repositories#kde-unstable}}<br />
{{Related articles end}}<br />
<br />
KDE is a software project currently comprising a [[desktop environment]] known as Plasma, a collection of libraries and frameworks (KDE Frameworks) and several applications (KDE Applications) as well. KDE upstream has a well maintained [https://userbase.kde.org/ UserBase wiki]. Detailed information about most KDE applications can be found there.<br />
<br />
== Installation ==<br />
<br />
=== Plasma ===<br />
<br />
Before installing Plasma, make sure you have a working [[Xorg]] installation on your system.<br />
<br />
[[Install]] the {{Pkg|plasma-meta}} meta-package or the {{Grp|plasma}} group. For differences between {{Pkg|plasma-meta}} and {{Grp|plasma}} reference [[Package group]]. Alternatively, for a more minimal Plasma installation, install the {{Pkg|plasma-desktop}} package. Upstream KDE has [https://community.kde.org/Distributions/Packaging_Recommendations package and setup recommendations] to get a fully-featured Plasma session.<br />
<br />
To enable support for [[Wayland]] in Plasma, also [[install]] the {{Pkg|plasma-wayland-session}} package. If you are an [[NVIDIA]] user with the proprietary {{Pkg|nvidia}} driver, also enable the [[NVIDIA#DRM kernel mode setting|DRM kernel mode setting]]. If that does not work, too, check the instructions on the [https://community.kde.org/Plasma/Wayland/Nvidia KDE wiki].<br />
<br />
=== Plasma Mobile ===<br />
<br />
[[Install]] {{AUR|plasma-mobile}}.<br />
<br />
=== KDE applications ===<br />
<br />
To install the full set of KDE Applications, install the {{Grp|kde-applications}} group or the {{Pkg|kde-applications-meta}} meta-package. If you only want KDE applications for a certain category such as games or education, install the relevant dependency of {{Pkg|kde-applications-meta}}. Note that this will only install applications, it will not install any version of Plasma.<br />
<br />
=== Unstable releases ===<br />
<br />
See [[Official repositories#kde-unstable]] for beta releases.<br />
<br />
== Starting Plasma ==<br />
<br />
{{Note|Although it is possible to launch Plasma under [[Wayland]], there are some missing features and known problems. See [https://community.kde.org/Plasma/Wayland_Showstoppers Wayland Showstoppers] for a list of issues and the [https://phabricator.kde.org/project/board/99/ Plasma on Wayland workboard] for the current state of development. Use [[Xorg]] for the most complete and stable experience.}}<br />
<br />
Plasma can be started either using a [[display manager]], or from the console.<br />
<br />
=== Using a display manager ===<br />
<br />
{{Tip|The preferred [[display manager]] is [[SDDM]].}}<br />
<br />
* Select ''Plasma (X11)'' to launch a new session in [[Xorg]].<br />
* Select ''Plasma (Wayland)'' to launch a new session in [[Wayland]].<br />
* Select ''Plasma Mobile (Wayland)'' to launch a new Plasma Mobile session in [[Wayland]].<br />
<br />
=== From the console ===<br />
<br />
* To start Plasma with [[xinit|xinit/startx]], append {{ic|1=export DESKTOP_SESSION=plasma}} and {{ic|exec startplasma-x11}} to your {{ic|.xinitrc}} file. If you want to start Xorg at login, please see [[Start X at login]].<br />
* To start a Plasma on Wayland session from a console, run {{ic|1=startplasma-wayland}}[https://community.kde.org/KWin/Wayland#Start_a_Plasma_session_on_Wayland]. Manually starting a dbus-session through {{ic|1=dbus-run-session}} should not be needed [https://invent.kde.org/plasma/plasma-workspace/-/merge_requests/128].<br />
<br />
== Configuration ==<br />
<br />
Most settings for KDE applications are stored in {{ic|~/.config/}}. However, configuring KDE is primarily done through the '''System Settings''' application. It can be started from a terminal by executing {{ic|systemsettings}}.<br />
<br />
=== Personalization ===<br />
<br />
==== Plasma desktop ====<br />
<br />
===== Themes =====<br />
<br />
There are different types of KDE themes, varying by scope of what they modify:<br />
<br />
* [https://store.kde.org/browse?cat=121 Global themes], comprehensive packages that can include Plasma themes, application styles, colors, fonts, icons, cursors, splash screens, SDDM themes, and Konsole color schemes.<br />
* [https://store.kde.org/browse?cat=104 Plasma themes], modifying the look of Plasma panels and widgets. These often have a recommended accompanying Kvantum or Aurorae theme to complete the look.<br />
* [https://store.kde.org/browse?cat=421 Application styles], modifying the look of programs.<br />
* Application styles that use [[Uniform look for Qt and GTK applications#Theme engines|theme engines]] such as [[Uniform look for Qt and GTK applications#Kvantum|Kvantum]], [[Qt#Styles in Qt 5|QtCurve]] [https://store.kde.org/browse?cat=119], [https://github.com/DexterMagnific/QSvgStyle QSvgStyle] [https://store.kde.org/browse?cat=622], and [https://store.kde.org/p/1167275/ Aurorae].<br />
* [[#Icon themes]], providing icons for applications, files, and actions.<br />
<br />
For easy system-wide installation and updating, some themes are available in both the [https://archlinux.org/packages/?sort=&q=kde+theme&maintainer=&flagged= official repositories] and the [https://aur.archlinux.org/packages?O=0&K=kde+theme AUR].<br />
<br />
Global themes can also be installed through ''System Settings > Appearance > Global Theme > Get New Global Themes...''.<br />
<br />
====== GTK application appearance ======<br />
<br />
{{Tip|For Qt and GTK theme consistency, see [[Uniform look for Qt and GTK applications]].}}<br />
<br />
The recommended theme for a pleasant appearance in GTK applications is {{Pkg|breeze-gtk}}, a GTK theme designed to mimic the appearance of Plasma's Breeze theme.<br />
Install {{Pkg|kde-gtk-config}} (part of the {{grp|plasma}} group) and select {{ic|Breeze}} as the GTK theme in ''System Settings > Appearance > Application Style > Configure GNOME/GTK Application Style...''.<br />
<br />
{{Out of date|The Plasma GTKd background service overwrites GTK settings on Plasma startup.}}<br />
<br />
In some themes, tooltips in GTK applications have white text on white backgrounds making it difficult to read. To change the colors in GTK2 applications, find the section for tooltips in the {{ic|.gtkrc-2.0}} file and change it. For GTK3 application two files need to be changed, {{ic|gtk.css}} and {{ic|settings.ini}}.<br />
<br />
Some GTK2 programs like {{AUR|vuescan-bin}} still look hardly usable due to invisible checkboxes with the Breeze or Adwaita skin in a Plasma session. To workaround this, install and select e.g. the Numix-Frost-Light skin of the {{AUR|numix-frost-themes}} under ''System Settings > Appearance > Application Style > Configure GNOME/GTK Application Style... > GTK theme''. Numix-Frost-Light looks similar to Breeze.<br />
<br />
===== Faces =====<br />
<br />
Plasma and [[SDDM]] will both use images found at {{ic|/var/lib/AccountsService/icons/}} as users' avatars. To configure with a graphical interface, you can use ''System Settings > Users'', which may first need to be [[install]]ed (see the {{Pkg|plasma-desktop}} package). The file corresponding to your username can be removed to restore the default avatar.<br />
<br />
===== Widgets =====<br />
<br />
[https://store.kde.org/browse?cat=418 Plasmoids] are widgets for plasma desktop shell designed to enhance the functionality of desktop, they can be found on the [https://aur.archlinux.org/packages?K=plasma5-applet AUR].<br />
<br />
Plasmoid scripts can also be installed by right-clicking onto a panel or the desktop and choosing ''Add Widgets > Get New Widgets... > Download New Plasma Widgets''. This will present a front-end for https://store.kde.org/ that allows you to install, uninstall, or update third-party Plasmoid scripts with just one click.<br />
<br />
===== Sound applet in the system tray =====<br />
<br />
[[Install]] {{Pkg|plasma-pa}} or {{Pkg|kmix}} (start Kmix from the Application Launcher). {{Pkg|plasma-pa}} is now installed by default with {{Grp|plasma}}, no further configuration needed.<br />
<br />
{{Note|1=To adjust the [https://bugs.kde.org/show_bug.cgi?id=313579#c28 step size of volume increments/decrements], add e.g. {{ic|1=VolumePercentageStep=1}} in the {{ic|[Global]}} section of {{ic|~/.config/kmixrc}}.}}<br />
<br />
===== Disable panel shadow =====<br />
<br />
As the Plasma panel is on top of other windows, its shadow is drawn over them. [https://bbs.archlinux.org/viewtopic.php?pid=1228394#p1228394] To disable this behaviour without impacting other shadows, [[install]] {{Pkg|xorg-xprop}} and run:<br />
<br />
$ xprop -remove _KDE_NET_WM_SHADOW<br />
<br />
then select the panel with the plus-sized cursor. [https://forum.kde.org/viewtopic.php%3Ff=285&t=121592.html] For automation, install {{Pkg|xorg-xwininfo}} and create the following script:<br />
<br />
{{hc|/usr/local/bin/kde-no-shadow|<nowiki><br />
#!/bin/bash<br />
for WID in $(xwininfo -root -tree | sed '/"Plasma": ("plasmashell" "plasmashell")/!d; s/^ *\([^ ]*\) .*/\1/g'); do<br />
xprop -id $WID -remove _KDE_NET_WM_SHADOW<br />
done<br />
</nowiki>}}<br />
<br />
Make the script [[executable]].<br />
<br />
The script can be run on login with ''Add Script'' in ''Autostart'':<br />
<br />
$ kcmshell5 autostart<br />
<br />
===== Display scaling / High DPI displays =====<br />
<br />
See [[HiDPI#KDE Plasma]].<br />
<br />
==== Plasma Mobile ====<br />
<br />
To use Plasma Mobile on small screens, [https://invent.kde.org/plasma-mobile/plasma-phone-settings plasma-phone-settings] contains several settings which can be applied globally ({{ic|/etc/xdg}}) and/or per user {{ic|~/.config}}.<br />
<br />
===== Applications blacklist =====<br />
<br />
{{ic|/etc/xdg/applications-blacklistrc}} (or {{ic|~/.config/applications-blacklistrc}}) removes applications from the applications menu/launcher to unclutter it.<br />
<br />
===== KDE globals =====<br />
<br />
{{ic|/etc/xdg/kdeglobals}} (or {{ic|~/.config/kdeglobals}}) does the following:<br />
<br />
* Sets the webbrowser to [https://apps.kde.org/angelfish/ Angelfish].<br />
* Sets the look and feel ([https://invent.kde.org/plasma/plasma-mobile/-/tree/master/look-and-feel org.kde.plasma.phone]) such that e.g. windows are maximized and do not have a titlebar.<br />
<br />
===== Lock screen =====<br />
<br />
{{ic|/etc/xdg/kscreenlockerrc}} (or {{ic|~/.config/kscreenlockerrc}}) locks the screen immediately after login. This is useful in combination with [[SDDM#Autologin]].<br />
<br />
===== KWin =====<br />
<br />
{{ic|/etc/xdg/kwinrc}} (or {{ic|~/.config/kwinrc}}) does the following:<br />
<br />
* Disables blur to improve performance.<br />
* Enables the [https://maliit.github.io/ Maliit] virtual keyboard.<br />
<br />
==== Window decorations ====<br />
<br />
[https://store.kde.org/browse/cat/114/ Window decorations] can be found in the [https://aur.archlinux.org/packages?K=kde+window+decoration AUR].<br />
<br />
They can be changed in ''System Settings > Appearance > Window Decorations'', there you can also directly download and install more themes with one click.<br />
<br />
==== Icon themes ====<br />
<br />
Icon themes can be installed and changed on ''System Settings > Appearance > Icons''.<br />
<br />
{{Note|Although all modern Linux desktops share the same icon theme format, desktops like [[GNOME]] use fewer icons (esp. in menus and toolbars). Themes developed for such desktops usually lack icons required by Plasma and KDE applications. It is recommended to install Plasma compatible icon themes instead.}}<br />
<br />
{{Tip|Since some icon themes do not inherit from the default icon theme, some icons may be missing. <br />
To inherit from the Breeze, add {{ic|breeze}} to the {{ic|1=Inherits=}} array in {{ic|/usr/share/icon/''theme-name''/index.theme}}, for example: {{ic|1=Inherits=breeze,hicolor}}. You need to reapply this patch after every update to the icon theme, consider using [[Pacman hooks]] to automate the process.}}<br />
<br />
==== Space efficiency ====<br />
<br />
The Plasma Netbook shell has been dropped from Plasma 5, see the following [https://forum.kde.org/viewtopic.php%3Ff=289&t=126631.html#p335947 KDE forum post]. However, you can achieve something similar by editing the file {{ic|~/.config/kwinrc}} adding {{ic|1=BorderlessMaximizedWindows=true}} in the {{ic|[Windows]}} section.<br />
<br />
==== Thumbnail generation ====<br />
<br />
To allow thumbnail generation for media or document files on the desktop and in Dolphin, install {{Pkg|kdegraphics-thumbnailers}} and {{Pkg|ffmpegthumbs}}.<br />
<br />
Then enable the thumbnail categories for the desktop via ''right click'' on the ''desktop background'' > ''Configure Desktop and Wallpaper...'' > ''Icons'' > ''Configure Preview Plugins...''.<br />
<br />
In ''Dolphin'', navigate to ''Configure > Configure Dolphin... > General > Previews''.<br />
<br />
=== Night Color ===<br />
<br />
Plasma provides a [[Redshift]]-like feature (working on both [[Xorg]] and [[Wayland]]) called Night Color. It makes the colors on the screen warmer to reduce eye strain at the time of your choosing. It can be enabled in ''System Settings > Display and Monitor > Night Color''.<br />
<br />
{{Tip|To have a handy System Tray on/off button for night color you need the {{Pkg|kdeplasma-addons}} and then you can add it.}}<br />
<br />
=== Printing ===<br />
<br />
{{Tip|Use the [[CUPS]] web interface for faster configuration. Printers configured in this way can be used in KDE applications. }}<br />
<br />
You can also configure printers in ''System Settings > Printers''. To use this method, you must first install the following packages {{Pkg|print-manager}}, {{Pkg|cups}}, {{Pkg|system-config-printer}}. See [[CUPS#Configuration]].<br />
<br />
=== Samba/Windows support ===<br />
<br />
If you want to have access to Windows services, install [[Samba]] (package {{Pkg|samba}}).<br />
<br />
The Dolphin share functionality requires the package {{Pkg|kdenetwork-filesharing}} and usershares, which the stock {{ic|smb.conf}} does not have enabled. Instructions to add them are in [[Samba#Enable Usershares]], after which sharing in Dolphin should work out of the box after restarting Samba.<br />
<br />
{{Tip|Use {{ic|*}} (asterisk) for both username and password when accessing a Windows share without authentication in Dolphin's prompt.}}<br />
<br />
Unlike GTK file browsers which utilize GVfs also for the launched program, opening files from Samba shares in Dolphin via KIO makes Plasma copy the whole file to the local system first with most programs (VLC is an exception).<br />
To workaround this, you can use a GTK based file browser like {{Pkg|thunar}} with {{Pkg|gvfs}} and {{Pkg|gvfs-smb}} (and {{Pkg|gnome-keyring}} for saving login credentials) to access SMB shares in a more able way.<br />
<br />
Another possibility is to [[mount]] a Samba share via {{Pkg|cifs-utils}} to make it look to Plasma like if the SMB share was just a normal local folder and thus can be accessed normally.<br />
See [[Samba#Manual mounting]] and [[Samba#Automatic mounting]].<br />
<br />
An GUI solution is available with {{AUR|samba-mounter-git}}, which offers basically the same functionality via an easy to use option located at ''System Settings'' > ''Network Drivers''. However, it might break with new KDE Plasma versions.<br />
<br />
=== KDE Desktop activities ===<br />
<br />
[https://userbase.kde.org/Plasma#Activities KDE Desktop Activities] are special workspaces where you can select specific settings for each activity that apply only when you are using said activity.<br />
<br />
=== Power management ===<br />
<br />
[[Install]] {{Pkg|powerdevil}} for an integrated Plasma power managing service. This service offers additional power saving features, monitor brightness control (if supported) and battery reporting including peripheral devices.<br />
<br />
{{Tip|Integration with [https://pointieststick.com/2021/07/23/this-week-in-kde-power-profiles-and-a-more-polished-kickoff/ power profiles] requires the [[power-profiles-daemon]] optional dependency.<br />
}}<br />
<br />
{{Accuracy|1=Regarding the note below, it might be that the problem is the logind setting ''LidSwitchIgnoreInhibited'' which defaults to ''yes''. [https://bbs.archlinux.org/viewtopic.php?pid=1649022#p1649022]}}<br />
<br />
{{Note|Power Devil may not [[Power management#Power managers|inhibit]] all logind settings (such as the lid close action for laptops). In these cases, the logind setting itself will need to be changed - see [[Power management#Power management]].}}<br />
<br />
=== Autostart ===<br />
<br />
Plasma can autostart applications and run scripts on startup and shutdown. To autostart an application, navigate to ''System Settings > Startup and Shutdown > Autostart'' and add the program or shell script of your choice. For applications, a ''.desktop'' file will be created, for login scripts, a ''.desktop'' file launching the script will be created.<br />
<br />
{{Note|<br />
* Programs can be autostarted on login only, whilst shell scripts can also be run on shutdown or even before Plasma itself starts.<br />
* Shell scripts will only be run if they are marked [[executable]].<br />
* Shell scripts previously placed in {{ic|~/.config/autostart-scripts/}} will get [https://invent.kde.org/plasma/plasma-workspace/-/merge_requests/736 automatically migrated to .desktop files].<br />
}}<br />
<br />
* Place [[Desktop entries]] (i.e. ''.desktop'' files) in the appropriate [[XDG Autostart]] directory.<br />
* Place or symlink shell scripts in one of the following directories:<br />
** {{ic|~/.config/plasma-workspace/env/}}: for executing scripts at login before launching Plasma.<br />
** {{ic|~/.config/plasma-workspace/shutdown/}}: for executing scripts when Plasma exits.<br />
<br />
See [https://docs.kde.org/stable5/en/plasma-workspace/kcontrol/autostart/index.html official documentation].<br />
<br />
=== Phonon ===<br />
<br />
From [[Wikipedia:Phonon (software)|Wikipedia]]:<br />
<br />
:Phonon is the multimedia API provided by KDE and is the standard abstraction for handling multimedia streams within KDE software and also used by several Qt applications.<br />
<br />
:Phonon was originally created to allow KDE and Qt software to be independent of any single multimedia framework such as GStreamer or xine and to provide a stable API for a major version's lifetime.<br />
<br />
Phonon is being widely used within KDE, for both audio (e.g., the System notifications or KDE audio applications) and video (e.g., the [[Dolphin]] video thumbnails). It can use the following backends:<br />
<br />
* [[VLC]]: {{Pkg|phonon-qt5-vlc}}<br />
* [[GStreamer]]: {{Pkg|phonon-qt5-gstreamer}}, see [[GStreamer#Installation]] for additional codec support<br />
* [[mpv]]: {{AUR|phonon-qt5-mpv}}, {{AUR|phonon-qt5-mpv-git}}<br />
<br />
KDE [https://community.kde.org/Distributions/Packaging_Recommendations#Non-Plasma_packages recommends only the VLC backend]. The GStreamer backend is [https://invent.kde.org/libraries/phonon-gstreamer/-/issues/1 unmaintained] but prominent Linux distributions (Kubuntu and Fedora-KDE for example) use it as default because that allows them to easily leave out patented MPEG codecs from the default installation.<br />
<br />
{{Note|1=<br><br />
* Multiple backends can be installed at once and prioritized via the ''phononsettings'' application.<br />
* According to the [https://forum.kde.org/viewtopic.php%3Ff=250&t=126476.html#p335080 KDE forums], the VLC backend lacks support for [[wikipedia:ReplayGain|ReplayGain]].<br />
* If using the VLC backend, you may experience crashes every time Plasma wants to send you an audible warning and in quite a number of other cases as well [https://forum.kde.org/viewtopic.php%3Ff=289&t=135956.html]. A possible fix is to rebuild the VLC plugins cache:<br />
{{bc|# /usr/lib/vlc/vlc-cache-gen /usr/lib/vlc/plugins}}<br />
}}<br />
<br />
=== Backup and restore ===<br />
<br />
KDE Plasma 5 stores personalized desktop settings as configuration files in the [[XDG Base Directory#Specification|XDG_CONFIG_HOME]] folder. Use the [https://github.com/shalva97/kde-configuration-files detail of configuration files] to select and choose a [https://www.addictivetips.com/ubuntu-linux-tips/backup-kde-plasma-5-desktop-linux/ method of backup and restore].<br />
<br />
=== systemd startup ===<br />
<br />
Plasma uses a [[systemd/User|systemd user]] instance to launch and manage all the Plasma services. This is the default startup method since Plasma 5.25, but can be [https://invent.kde.org/plasma/plasma-workspace/-/wikis/Plasma-and-the-systemd-boot disabled to use boot scripts instead] with the following command (however this may stop working in a future release):<br />
<br />
$ kwriteconfig5 --file startkderc --group General --key systemdBoot false<br />
<br />
More details about the implementation can be read in [https://blog.davidedmundson.co.uk/blog/plasma-and-the-systemd-startup/ Edmundson's blog: plasma and the systemd startup].<br />
<br />
=== Spell checking ===<br />
<br />
KDE applications use {{Pkg|sonnet}} for spell checking. See its optional dependencies for the supported [[spell checker]]s.<br />
<br />
Configure it in ''System Settings > Regional Settings > Spell Check''.<br />
<br />
=== Running kwin wayland on NVIDIA ===<br />
<br />
See https://community.kde.org/Plasma/Wayland/Nvidia.<br />
<br />
== Applications ==<br />
<br />
The KDE project provides a suite of applications that integrate with the Plasma desktop. See the {{Grp|kde-applications}} group for a full listing of the available applications. Also see [[:Category:KDE]] for related KDE application pages.<br />
<br />
Aside from the programs provided in KDE Applications, there are many other applications available that can complement the Plasma desktop. Some of these are discussed below.<br />
<br />
=== System administration ===<br />
<br />
==== Terminate Xorg server through KDE System Settings ====<br />
<br />
Navigate to the submenu ''System Settings > Input Devices > Keyboard > Advanced (tab) > "Key Sequence to kill the X server"'' and ensure that the checkbox is ticked.<br />
<br />
==== KCM ====<br />
<br />
KCM stands for ''KC''onfig ''M''odule. KCMs can help you configure your system by providing interfaces in System Settings, or through the command line with ''kcmshell5''.<br />
<br />
* {{App|sddm-kcm|KDE Configuration Module for [[SDDM]].|https://invent.kde.org/plasma/sddm-kcm|{{Pkg|sddm-kcm}}}}<br />
* {{App|kde-gtk-config|GTK2 and GTK3 Configurator for KDE.|https://invent.kde.org/plasma/kde-gtk-config|{{Pkg|kde-gtk-config}}}}<br />
* {{App|System policies|Set of configuration modules which allows administrator to change [[PolicyKit]] settings.|https://invent.kde.org/system/polkit-kde-kcmodules-1|{{AUR|kcm-polkit-kde-git}}}}<br />
* {{App|wacom tablet|KDE GUI for the Wacom Linux Drivers.|https://www.linux-apps.com/p/1127862/|{{Pkg|kcm-wacomtablet}}}}<br />
* {{App|Kcmsystemd|systemd control module for KDE.|https://github.com/rthomsen/kcmsystemd|{{AUR|systemd-kcm}}}}<br />
<br />
More KCMs can be found at [https://www.linux-apps.com/find?search=kcm linux-apps.com].<br />
<br />
=== Desktop search ===<br />
<br />
KDE implements desktop search with a software called [[Baloo]], a file indexing and searching solution.<br />
<br />
=== Web browsers ===<br />
<br />
The following web browsers can integrate with Plasma:<br />
<br />
* {{App|[[Wikipedia:Konqueror|Konqueror]]|Part of the KDE project, supports two rendering engines – KHTML and the [[Chromium]]-based Qt WebEngine.|https://konqueror.org/|{{Pkg|konqueror}}}}<br />
* {{App|[[Wikipedia:Falkon|Falkon]]|A Qt web browser with Plasma integration features, previously known as Qupzilla. It uses Qt WebEngine.|https://userbase.kde.org/Falkon/|{{Pkg|falkon}}}}<br />
* {{App|[[Chromium]]|Chromium and its proprietary variant Google Chrome have limited Plasma integration. [[KDE Wallet#KDE Wallet for Chrome and Chromium|They can use KWallet]] and KDE Open/Save windows.|https://www.chromium.org/|{{Pkg|chromium}}}}<br />
* {{App|[[Firefox]]|Firefox can be configured to better integrate with Plasma. See [[Firefox#KDE integration]] for details.|https://mozilla.org/firefox|{{Pkg|firefox}}}}<br />
<br />
{{Tip|Starting from Plasma 5.13, one can integrate [[Firefox]] or [[Chrome]] with Plasma: providing media playback control from the Plasma tray, download notifications and find open tabs in KRunner. [[Install]] {{pkg|plasma-browser-integration}} and the corresponding browser add-on. Chrome/Chromium support should already be included, for Firefox add-on see [[Firefox#KDE integration]].}}<br />
<br />
=== PIM ===<br />
<br />
KDE offers its own stack for [[Wikipedia:Personal information management|personal information management]] (PIM). This includes emails, contacts, calendar, etc. To install all the PIM packages, you could use the {{Grp|kde-pim}} package group or the {{Pkg|kde-pim-meta}} meta package.<br />
<br />
==== Akonadi ====<br />
<br />
Akonadi is a system meant to act as a local cache for PIM data, regardless of its origin, which can be then used by other applications. This includes the user's emails, contacts, calendars, events, journals, alarms, notes, and so on. Akonadi does not store any data by itself: the storage format depends on the nature of the data (for example, contacts may be stored in vCard format).<br />
<br />
Install {{Pkg|akonadi}}. For additional addons, install {{Pkg|kdepim-addons}}.<br />
<br />
{{Note|<br />
* If you wish to use a database engine other than [[MariaDB]], then when installing the {{Pkg|akonadi}} package, use the following command to skip installing the {{Pkg|mariadb}} dependencies: {{bc|# pacman -S akonadi --assume-installed mariadb}} See also {{Bug|32878}}.<br />
* If Akonadi cannot find {{ic|/usr/bin/mysqld}} upon first start, it will fall back to using SQLite.<br />
}}<br />
<br />
===== MySQL =====<br />
<br />
By default Akonadi will use {{ic|/usr/bin/mysqld}} ([[MariaDB]] by default, see [[MySQL]] for alternative providers) to run a managed MySQL instance with the database stored in {{ic|~/.local/share/akonadi/db_data/}}.<br />
<br />
====== System-wide MySQL instance ======<br />
<br />
Akonadi supports using the system-wide [[MySQL]] for its database.[https://techbase.kde.org/KDE_PIM/Akonadi#Can_Akonadi_use_a_normal_MySQL_server_running_on_my_system.3F]<br />
<br />
{{Expansion|Add instructions.}}<br />
<br />
{{hc|~/.config/akonadi/akonadiserverrc|2=<br />
[%General]<br />
Driver=QMYSQL<br />
<br />
[QMYSQL]<br />
Host=<br />
Name=akonadi_''username''<br />
Options="UNIX_SOCKET=/run/mysqld/mysqld.sock"<br />
StartServer=false<br />
}}<br />
<br />
===== PostgreSQL =====<br />
<br />
Akonadi supports either using the existing system-wide [[PostgreSQL]] instance, i.e. {{ic|postgresql.service}}, or running a PostgreSQL instance with user privileges and the database in {{ic|~/.local/share/akonadi/db_data/}}.<br />
<br />
====== Per-user PostgreSQL instance ======<br />
<br />
[[Install]] {{Pkg|postgresql}} and {{Pkg|postgresql-old-upgrade}}.<br />
<br />
Edit Akonadi configuration file so that it has the following contents:<br />
<br />
{{hc|~/.config/akonadi/akonadiserverrc|2=<br />
[%General]<br />
Driver=QPSQL<br />
}}<br />
<br />
{{Note|<br />
* When Akonadi starts, it will create the {{ic|[QPSQL]}} section and set the appropriate variables in it.<br />
* The database will be stored in {{ic|~/.local/share/akonadi/db_data/}}.<br />
}}<br />
<br />
Start Akonadi with {{ic|akonadictl start}}, and check its status: {{ic|akonadictl status}}.<br />
<br />
{{Note|<br />
* Starting with {{Pkg|akonadi}} 19.08.0-1 the PostgreSQL database cluster in {{ic|~/.local/share/akonadi/db_data/}} will get automatically upgraded when a major PostgreSQL version upgrade is detected.<br />
* For previous {{Pkg|akonadi}} versions major PostgreSQL version upgrades will require a manual database upgrade. Follow the [https://userbase.kde.org/Akonadi/Postgres_update update instructions on KDE UserBase Wiki]. Make sure to adjust the paths to PostgreSQL binaries to those used by {{Pkg|postgresql}} and {{Pkg|postgresql-old-upgrade}}, see [[PostgreSQL#Upgrading PostgreSQL]].<br />
}}<br />
<br />
====== System-wide PostgreSQL instance ======<br />
<br />
This requires an already configured and running [[PostgreSQL]].<br />
<br />
Create a PostgreSQL user account for your user:<br />
<br />
[postgres]$ createuser ''username''<br />
<br />
Create a database for Akonadi:<br />
<br />
[postgres]$ createdb -O ''username'' -E UTF8 --locale=C -T template0 akonadi-''username''<br />
<br />
Configure Akonadi to use the system-wide PostgreSQL:<br />
<br />
{{hc|~/.config/akonadi/akonadiserverrc|2=<br />
[%General]<br />
Driver=QPSQL<br />
<br />
[QPSQL]<br />
Host=/run/postgresql<br />
Name=akonadi-''username''<br />
StartServer=false<br />
}}<br />
<br />
{{Note|Custom port, username and password can be specified with options {{ic|1=Port=}}, {{ic|1=User=}}, {{ic|1=Password=}} in the {{ic|[QPSQL]}} section.}}<br />
<br />
Start Akonadi with {{ic|akonadictl start}}, and check its status: {{ic|akonadictl status}}.<br />
<br />
===== SQLite =====<br />
<br />
To use [[SQLite]], edit the Akonadi configuration file to match the configuration below:<br />
<br />
{{hc|~/.config/akonadi/akonadiserverrc|2=<br />
[%General]<br />
Driver=QSQLITE<br />
}}<br />
<br />
{{Note|<br />
* When Akonadi starts, it will create the {{ic|[QSQLITE]}} section and set the appropriate variables in it.<br />
* The database will be stored as {{ic|~/.local/share/akonadi/akonadi.db}}.<br />
}}<br />
<br />
===== Disabling Akonadi =====<br />
<br />
Users who want to disable Akonadi would need to not start any KDE applications that rely on it. See this [https://userbase.kde.org/Akonadi#Disabling_the_Akonadi_subsystem section in the KDE userbase] for more information.<br />
<br />
=== KDE Connect ===<br />
<br />
[https://community.kde.org/KDEConnect KDE Connect] provides several features to connect your [[Android]] or [[iOS]] phone with your Linux desktop:<br />
<br />
* Share files and URLs to/from KDE from/to any app, without wires.<br />
* Touchpad emulation: Use your phone screen as your computer's touchpad.<br />
* Notifications sync (4.3+): Read your Android notifications from the desktop.<br />
* Shared clipboard: copy and paste between your phone and your computer.<br />
* Multimedia remote control: Use your phone as a remote for Linux media players.<br />
* WiFi connection: no usb wire or bluetooth needed.<br />
* RSA Encryption: your information is safe.<br />
<br />
You will need to install KDE Connect both on your computer and on your phone. For PC, [[install]] {{Pkg|kdeconnect}} package. For Android, install KDE Connect from [https://play.google.com/store/apps/details?id=org.kde.kdeconnect_tp Google Play] or from [https://f-droid.org/packages/org.kde.kdeconnect_tp/ F-Droid]. If you want to browse your phone's filesystem, you need to [[install]] {{Pkg|sshfs}} as well and configure filesystem exposes in your Android app. For iOS, install KDE Connect from the [https://apps.apple.com/app/kde-connect/id1580245991 App Store]. Not all features from the Android version are available on the iOS version.<br />
<br />
To use remote input functionality on a Plasma Wayland session, the {{Pkg|xdg-desktop-portal}} package is required.<br />
<br />
It is possible to use KDE Connect even if you do not use the Plasma desktop. For GNOME users, better integration can be achieved by installing {{AUR|gnome-shell-extension-gsconnect}} instead of {{Pkg|kdeconnect}}. To start the KDE Connect daemon manually, execute {{ic|/usr/lib/kdeconnectd}}.<br />
<br />
If you use a [[firewall]], you need to open UDP and TCP ports {{ic|1714}} through {{ic|1764}}.<br />
<br />
Sometimes, KDE Connect will not detect a phone. You can restart the services by running {{ic|killall kdeconnectd}} and then opening kdeconnect in system settings or running {{ic|kdeconnect-cli --refresh}} followed by {{ic|kdeconnect-cli -l}}. You can also use ''Pair new device > Add devices by IP'' on KDE Connect for Android.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Use a different window manager ===<br />
<br />
It is possible to use a window manager other than KWin with Plasma. This allows you to combine the functionality of the KDE desktop with the utility of a [[tiling window manager]], which may be more fleshed out than KWin tiling scripts.<br />
<br />
The component chooser settings in Plasma [https://github.com/KDE/plasma-desktop/commit/2f83a4434a888cd17b03af1f9925cbb054256ade no longer allows changing the window manager], but you are still able to swap KWin via other methods.<br />
<br />
{{Note|When replacing Kwin with a window manager which does not provide a Compositor (such as Openbox), any desktop compositing effects e.g. transparency will be lost. In this case, install and run a separate Composite manager to provide the effects such as [[Xcompmgr]] or [[picom]].}}<br />
<br />
==== Replacing KWin service ====<br />
<br />
Since KDE 5.25, [https://blog.davidedmundson.co.uk/blog/plasma-and-the-systemd-startup/ Plasma's systemd based startup] is enabled by default.<br />
<br />
To replace KWin in this startup, you must first [[mask]] the {{ic|plasma-kwin_x11.service}} for the current user to prevent it from starting.<br />
<br />
Then, [[create]] a new systemd [[user unit]] to start your preferred WM [https://bugs.kde.org/show_bug.cgi?id=439481#c2]:<br />
<br />
{{hc|1=~/.config/systemd/user/plasma-custom-wm.service|2=<br />
[Install]<br />
WantedBy=plasma-workspace.target<br />
<br />
[Unit]<br />
Description=Plasma Custom Window Manager<br />
Before=plasma-workspace.target<br />
<br />
[Service]<br />
ExecStart=''/path/to/other/wm''<br />
Slice=session.slice<br />
Restart=on-failure<br />
}}<br />
<br />
To use it, do (as [[user unit]]s) a [[daemon-reload]], make sure you have [[mask]]ed {{ic|plasma-kwin_x11.service}} then [[enable]] the newly created {{ic|plasma-custom-wm.service}}.<br />
<br />
{{Note|When using i3 window manager with Plasma, it may be necessary to manually set dialogs to open in floating mode in order for them to correctly appear. For more information, see [[i3#Correct handling of floating dialogs]].}}<br />
<br />
==== Using script-based boot and KDEWM ====<br />
<br />
Plasma's script-based boot is used by disabling [[#systemd startup]]. If you have done so, you can change the window manager by setting the {{ic|KDEWM}} [[environment variable]] before Plasma is invoked.<br />
<br />
===== System-wide =====<br />
<br />
{{Merge|Environment variables#Globally|This technique should be moved into a new section there (2.1.3: Using Xsession), and then this section merged with the previous one.}}<br />
<br />
If you have root access, you can also add an XSession that will be available to all users as an option on the login screen. <br />
<br />
First, create a script with execution permissions as follows:<br />
<br />
{{hc|1=/usr/local/bin/plasma-i3.sh|2=<br />
#!/bin/sh<br />
export KDEWM=/usr/bin/i3<br />
/usr/bin/startplasma-x11<br />
}}<br />
<br />
Replace {{ic|/usr/bin/i3}} to the path to your preferred WM. Ensure the path is correctly set. If KDE is unable to start the window manager, the session will fail and the user will be returned to the login screen.<br />
<br />
Then, to add an XSession, add a file in {{ic|/usr/share/xsessions}} with the following content:<br />
<br />
{{hc|1=/usr/share/xsessions/plasma-i3.desktop|2=<br />
[Desktop Entry]<br />
Type=XSession<br />
Exec=/usr/local/bin/plasma-i3.sh<br />
DesktopNames=KDE<br />
Name=Plasma (i3)<br />
Comment=KDE Plasma with i3 as the WM}}<br />
<br />
==== KDE/Openbox session ====<br />
<br />
The {{Pkg|openbox}} package provides a session for using KDE with [[Openbox]]. To make use of this session, select ''KDE/Openbox'' from the [[display manager]] menu.<br />
<br />
For those starting the session manually, add the following line to your [[xinit]] configuration:<br />
<br />
{{hc|~/.xinitrc|<br />
exec openbox-kde-session<br />
}}<br />
<br />
=== KWin tiling window scripts ===<br />
<br />
{{Style|Use [[Template:App]].}}<br />
<br />
[https://github.com/Bismuth-Forge/bismuth Bismuth], [https://github.com/zeroxoneafour/polonium Polonium] and [https://github.com/esjeon/krohnkite Kröhnkite] are Kwin extensions that tile windows automatically and lets you manage them via keyboard.<br />
<br />
[https://github.com/codeswhite/kzones KZones] is a KWin script that mimicks the behavior of the "Fancy Zones" feature of Microsoft PowerToys.<br />
<br />
=== Configuring monitor resolution / multiple monitors ===<br />
<br />
To enable display resolution management and multiple monitors in Plasma, install {{Pkg|kscreen}}. This provides additional options to ''System Settings > Display and Monitor''.<br />
<br />
=== Configuring ICC profiles ===<br />
<br />
To enable [[ICC profiles]] in Plasma, [[install]] {{Pkg|colord-kde}}. This provides additional options to ''System Settings > Color Corrections''.<br />
<br />
ICC profiles can be imported using ''Add Profile''.<br />
<br />
=== Disable opening application launcher with Super key (Windows key) ===<br />
<br />
To disable this feature you currently can run the following command:<br />
<br />
$ kwriteconfig5 --file kwinrc --group ModifierOnlyShortcuts --key Meta ""<br />
<br />
=== Disable bookmarks showing in application menu ===<br />
<br />
With the Plasma Browser integration installed, KDE will show bookmarks in the application launcher.<br />
<br />
To disable this feature, you can run the following commands:<br />
<br />
$ mkdir ~/.local/share/kservices5<br />
$ sed 's/EnabledByDefault=true$/EnabledByDefault=false/' /usr/share/kservices5/plasma-runner-bookmarks.desktop > ~/.local/share/kservices5/plasma-runner-bookmarks.desktop<br />
<br />
=== IBus Integration ===<br />
<br />
[[IBus]] is an [[Input method#Input method framework|input method framework]] and can be integrated into KDE. See [[IBus#Integration]] for details.<br />
<br />
Using [[IBus]] may be required when using KDE on [[Wayland]] to offer accented characters and dead keys support [https://bugs.kde.org/show_bug.cgi?id=411729].<br />
<br />
=== Enable hotspot in plasma-nm ===<br />
<br />
See [[NetworkManager#Sharing internet connection over Wi-Fi]].<br />
<br />
=== Restore previous saved session ===<br />
<br />
If you have ''System Settings > Startup and Shutdown > Desktop Session > When logging in: Restore previous saved session'' (default) selected, ksmserver (KDE's session manager) will automatically save/load all open applications to/from {{ic|~/.config/ksmserverrc}} on logout/login.<br />
<br />
{{Note|Currently, native Wayland windows cannot be restored. See [https://community.kde.org/Plasma/Wayland_Showstoppers Wayland Showstoppers] for the current state of development.}}<br />
<br />
=== Receive local mail in KMail ===<br />
<br />
If you have set up local mail delivery with a [[mail server]] that uses the [[Wikipedia:Maildir|Maildir]] format, you may want to receive this mail in KMail. To do so, you can re-use KMail's default receiving account "Local Folders" that stores mail in {{ic|~/.local/share/local-mail/}}.<br />
<br />
Symlink the {{ic|~/Maildir}} directory (where Maildir format mail is commonly delivered) to the Local Folders' inbox:<br />
<br />
$ ln -s .local/share/local-mail/inbox ~/Maildir<br />
<br />
Alternatively, add a new receiving account with the type ''Maildir'' and set {{ic|~/Maildir}} as its directory.<br />
<br />
=== Configure Plasma for all users ===<br />
<br />
Edit {{ic|config/main.xml}} files in the {{ic|/usr/share/plasma}}. For example, to configure the Application Launcher for all users, edit {{ic|/usr/share/plasma/plasmoids/org.kde.plasma.kickoff/contents/config/main.xml}}. To prevent the files from being overwritten with package updates, add the files to [[Pacman#Skip file from being upgraded|Pacman's NoUpgrade]]<br />
<br />
=== Disable hibernate ===<br />
<br />
{{Merge|Power management|This is not specific to KDE. Merge and then either leave this section as a stub linking to that one.}}<br />
<br />
Properly disable the hibernate feature and hide it from the menu with a Polkit policy rule.<br />
<br />
{{hc|/etc/polkit-1/rules.d/99-disable-hibernate.rules|<nowiki><br />
// Disable hibernate for all users<br />
polkit.addRule(function(action, subject) {<br />
if ((action.id == "org.freedesktop.login1.hibernate")) {<br />
return polkit.Result.NO;<br />
}<br />
});<br />
polkit.addRule(function(action, subject) {<br />
if ((action.id == "org.freedesktop.login1.hibernate-multiple-sessions")) {<br />
return polkit.Result.NO;<br />
}<br />
});<br />
</nowiki>}}<br />
<br />
Alternatively, add the following lines to a file in {{ic|/etc/systemd/sleep.conf.d/}}:<br />
<br />
{{hc|/etc/systemd/sleep.conf.d/00-disable-hibernation.conf|2=<br />
[Sleep]<br />
AllowHibernation=no<br />
AllowSuspendThenHibernate=no<br />
AllowHybridSleep=no<br />
}}<br />
<br />
=== Using window rules ===<br />
<br />
Kwin has the ability to specify rules for specific windows/applications. For example, you can force enable the window titlebar even if the application developer decided that there should not be one. You can set such rules as specific starting position, size, minimize state, keeping above/below others and so on.<br />
<br />
To create a rule you can press {{ic|Alt+F3}} when the window of interest is in focus. Then, in ''More Actions > Configure special application/window settings'', you can set the desired property. A list of created rules is available from ''System Settings > Window Management > Window Rules''.<br />
<br />
=== Virtual keyboard ===<br />
<br />
There are no virtual keyboards installed by default. Choose an appropriate one from [[List of applications/Utilities#On-screen keyboards]], for example the Maliit keyboard, and install it. Then enable it in System Settings.<br />
<br />
== Troubleshooting ==<br />
<br />
=== qt5ct and kvantum bugs after upgrade ===<br />
<br />
{{Out of date|This was added 2021-02-15 : the "latest update" is one year old, is this fixed ?}}<br />
<br />
Latest update might cause incompatible HiDPI scaling that made some interfaces becomes too big for your screen, some icons are missing or can not be displayed, and missing panels or widgets.<br />
<br />
Try to remove {{Pkg|qt5ct}} and {{Pkg|kvantum}} related package, then apply default global Plasma theme. If the problem persists, try clearing all your KDE configuration and reinstalling {{Grp|plasma}} to overwrite the configuration. Be sure to check HiDPI scaling in KDE system settings as well.<br />
<br />
=== Fonts ===<br />
<br />
==== Fonts in a Plasma session look poor ====<br />
<br />
Try installing the {{Pkg|ttf-dejavu}} and {{Pkg|ttf-liberation}} packages.<br />
<br />
After the installation, be sure to log out and back in. You should not have to modify anything in ''System Settings > Appearance > Fonts''. If you are using {{Pkg|qt5ct}}, the settings in Qt5 Configuration Tool may override the font settings in System Settings.<br />
<br />
If you have personally set up how your [[Fonts]] render, be aware that System Settings may alter their appearance. When you go ''System Settings > Appearance > Fonts'' System Settings will likely alter your font configuration file ({{ic|fonts.conf}}).<br />
<br />
There is no way to prevent this, but, if you set the values to match your {{ic|fonts.conf}} file, the expected font rendering will return (it will require you to restart your application or in a few cases restart your desktop). Note that Gnome's Font Preferences also does this.<br />
<br />
==== Fonts are huge or seem disproportional ====<br />
<br />
Try to force font DPI to {{ic|'''96'''}} in ''System Settings > Appearance > Fonts''.<br />
<br />
If that does not work, try setting the DPI directly in your Xorg configuration as documented in [[Xorg#Setting DPI manually]].<br />
<br />
=== Configuration related ===<br />
<br />
Many problems in KDE are related to its configuration.<br />
<br />
==== Plasma desktop behaves strangely ====<br />
<br />
Plasma problems are usually caused by unstable ''Plasma widgets'' (colloquially called ''plasmoids'') or ''Plasma themes''. First, find which was the last widget or theme you had installed and disable or uninstall it.<br />
<br />
So, if your desktop suddenly exhibits "locking up", this is likely caused by a faulty installed widget. If you cannot remember which widget you installed before the problem began (sometimes it can be an irregular problem), try to track it down by removing each widget until the problem ceases. Then you can uninstall the widget, and file a bug report on the [https://bugs.kde.org/ KDE bug tracker] '''only if it is an official widget'''. If it is not, it is recommended to find the entry on the [https://store.kde.org/ KDE Store] and inform the developer of that widget about the problem (detailing steps to reproduce, etc.).<br />
<br />
If you cannot find the problem, but you do not want ''all'' the settings to be lost, navigate to {{ic|~/.config/}} and run the following command:<br />
<br />
$ for j in plasma*; do mv -- "$j" "${j%}.bak"; done<br />
<br />
This command will rename '''all''' Plasma related configuration files to ''*.bak'' (e.g. {{ic|plasmarc.bak}}) of your user and when you will relogin into Plasma, you will have the default settings back. To undo that action, remove the ''.bak'' file extension. If you already have ''*.bak'' files, rename, move, or delete them first. It is highly recommended that you create regular backups anyway. See [[Synchronization and backup programs]] for a list of possible solutions.<br />
<br />
==== Clean cache to resolve upgrade problems ====<br />
<br />
The [https://bbs.archlinux.org/viewtopic.php?id=135301 problem] may be caused by old cache. Sometimes, after an upgrade, the old cache might introduce strange, hard to debug behaviour such as unkillable shells, hangs when changing various settings, Ark being unable to extract archives or Amarok not recognizing any of your music. This solution can also resolve problems with KDE and Qt applications looking bad after an update.<br />
<br />
Rebuild the cache using the following commands:<br />
<br />
$ rm ~/.config/Trolltech.conf<br />
$ kbuildsycoca5 --noincremental<br />
<br />
Optionally, empty the {{ic|~/.cache/}} folder contents, however, this will also clear the cache of other applications:<br />
<br />
$ rm -rf ~/.cache/*<br />
<br />
==== Plasma desktop does not respect locale/language settings ====<br />
<br />
Plasma desktop may use different settings than you set at KDE System Settings panel, or in {{ic|locale.conf}} (per [[Locale#Variables]]). First thing to do is log out and log in after removing {{ic|~/.config/plasma-localerc}}, if this does not fix the issue, try to edit the file manually. For example, to set {{ic|LANG}} variable to {{ic|es_ES.UTF-8}} and the {{ic|LC_MESSAGES}} variable to {{ic|en_US.UTF-8}}:<br />
<br />
{{hc|~/.config/plasma-localerc|2=<br />
[Formats]<br />
LANG=es_ES.UTF-8<br />
<br />
[Translations]<br />
LANGUAGE=en_US<br />
}}<br />
<br />
==== Cannot change theme, icons, fonts, colors in systemsettings; most icons are not displayed ====<br />
<br />
Make sure that {{ic|QT_QPA_PLATFORMTHEME}} [[environment variable]] is unset, the command {{ic|printenv QT_QPA_PLATFORMTHEME}} should show empty output. Otherwise if you had an environment set (most likely qt5ct) the variable will force qt5ct settings upon Qt applications, the command {{ic|1=export QT_QPA_PLATFORMTHEME=}} should unset the environment.<br />
<br />
An easier (and more reliable) solution can be to uninstall completely qt5ct.<br />
<br />
==== Volume control, notifications or multimedia keys do not work ====<br />
<br />
Hiding certain items in the System Tray settings (e.g. Audio Volume, Media Player or Notifications) also disables related features. Hiding the ''Audio Volume'' disables volume control keys, ''Media Player'' disables multimedia keys (rewind, stop, pause) and hiding ''Notifications'' disables showing notifications.<br />
<br />
==== Login Screen KCM does not sync cursor settings to SDDM ====<br />
<br />
The Login Screen KCM reads your cursor settings from {{ic|~/.config/kcminputrc}}, without this file no settings are synced. The easiest way to generate this file is to change your cursor theme in ''System Settings > Cursors'', then change it back to your preferred cursor theme.<br />
<br />
==== Missing panels/widgets ====<br />
<br />
A crash or hardware change can modify the screen numbers, even on a single monitor setup. The panels/widgets can be missing after such an event, this can be fixed in the {{ic|~/.config/plasma-org.kde.plasma.desktop-appletsrc}} file by changing the {{ic|lastScreen}} values.<br />
<br />
=== Graphical problems ===<br />
<br />
Make sure you have the proper driver for your GPU installed. See [[Xorg#Driver installation]] for more information. If you have an older card, it might help to [[#Disable desktop effects manually or automatically for defined applications]] or [[#Disable compositing]].<br />
<br />
==== Getting current state of KWin for support and debug purposes ====<br />
<br />
This command prints out a summary of the current state of KWin including used options, used compositing backend and relevant OpenGL driver capabilities. See more on [https://blog.martin-graesslin.com/blog/2012/03/on-getting-help-for-kwin-and-helping-kwin/ Martin's blog].<br />
<br />
$ qdbus org.kde.KWin /KWin org.kde.KWin.supportInformation<br />
<br />
==== Disable desktop effects manually or automatically for defined applications ====<br />
<br />
Plasma has desktop effects enabled by default and e.g. not every game will disable them automatically. You can disable desktop effects in ''System Settings > Workspace Behavior > Desktop Effects'' and you can toggle desktop effects with {{ic|Alt+Shift+F12}}. <br />
<br />
Additionally, you can create custom KWin rules to automatically disable/enable compositing when a certain application/window starts under ''System Settings > Window Management > Window Rules''.<br />
<br />
==== Enable transparency ====<br />
<br />
If you use a transparent background without enabling the compositor, you will get the message:<br />
<br />
This color scheme uses a transparent background which does not appear to be supported on your desktop<br />
<br />
In ''System Settings > Display and Monitor > Compositor'', check ''Compositing: Enable on startup'' and restart Plasma.<br />
<br />
==== Disable compositing ====<br />
<br />
In ''System Settings > Display and Monitor > Compositor'', uncheck ''Compositing: Enable on startup'' and restart Plasma.<br />
<br />
==== Flickering in fullscreen when compositing is enabled ====<br />
<br />
In ''System Settings > Display and Monitor > Compositor'', uncheck ''Compositing: Allow applications to block compositing''. This may harm performance.<br />
<br />
==== Plasma cursor sometimes shown incorrectly ====<br />
<br />
Create the directory {{ic|~/.icons/default}} and inside a file named {{ic|index.theme}} with the following contents:<br />
<br />
{{hc|~/.icons/default/index.theme|2=<br />
[Icon Theme]<br />
Inherits=breeze_cursors<br />
}}<br />
<br />
Execute the following command:<br />
<br />
$ ln -s /usr/share/icons/breeze_cursors/cursors ~/.icons/default/cursors<br />
<br />
On Wayland, it is neccessary for {{Pkg|xdg-desktop-portal-gtk}} to be be installed for GTK/Gnome apps to correctly apply cursor themes.<br />
<br />
===== Firefox and Thunderbird ignore cursor theme =====<br />
If you have enabled [[Firefox#Wayland]] support, Firefox and Thunderbird will refer to GSettings to determine which cursor to display.<br />
<br />
To sync KDE settings to GTK applications, install {{Pkg|kde-gtk-config}}.<br />
<br />
If you do not want to install an extra package, you can set the cursor theme manually:<br />
<br />
$ gsettings set org.gnome.desktop.interface cursor-theme ''cursor-theme-name''<br />
<br />
==== Cursor jerking/flicking when changing roles (e.g., when mousing over hyperlinks) ====<br />
<br />
Try installing the appropriate 2D acceleration driver for your system and window manager.<br />
<br />
==== Unusable screen resolution set ====<br />
<br />
Your local configuration settings for kscreen can override those set in {{ic|xorg.conf}}. Look for kscreen configuration files in {{ic|~/.local/share/kscreen/}} and check if mode is being set to a resolution that is not supported by your monitor.<br />
<br />
==== Blurry icons in system tray ====<br />
<br />
In order to add icons to tray, applications often make use of the library appindicator. If your icons are blurry, check which version of libappindicator you have installed. If you only have {{Pkg|libappindicator-gtk2}} installed, you can install {{Pkg|libappindicator-gtk3}} as an attempt to get clear icons.<br />
<br />
==== Cannot change screen resolution when running in a virtual machine ====<br />
<br />
When running Plasma in a [[VMware]], [[VirtualBox]] or [[QEMU]] virtual machine, kscreen may not allow changing the guest's screen resolution to a resolution higher than 800×600.<br />
<br />
The workaround is to set the {{ic|PreferredMode}} option in {{man|5|xorg.conf.d}}. Alternatively try using a different graphics adapter in the VM, e.g. VBoxSVGA instead of VMSVGA for VirtualBox and Virtio instead of QXL for QEMU. See [https://bugs.kde.org/show_bug.cgi?id=407058 KDE Bug 407058] for details.<br />
<br />
==== Dolphin, Kate, etc. stuck long time when opening ====<br />
<br />
Check whether your user directories ({{ic|Documents}}, {{ic|Downloads}}, etc.) are read-only.<br />
<br />
==== Spectacle screenshot uses old screen state ====<br />
<br />
In ''System Settings > Display and Monitor > Compositor'', change ''Keep window thumbnails'' from ''Only from Shown windows'' to ''Never''. If you're on Intel graphics, ensure that {{Pkg|xf86-video-intel}} is [[Intel graphics#Installation|not installed]].<br />
<br />
=== Sound problems ===<br />
<br />
{{Note|First make sure you have {{Pkg|alsa-utils}} installed.}}<br />
<br />
==== No sound after suspend ====<br />
<br />
If there is no sound after suspending and KMix does not show audio devices which should be there, restarting plasmashell and pulseaudio may help:<br />
<br />
$ killall plasmashell<br />
$ systemctl --user restart pulseaudio.service<br />
$ plasmashell<br />
<br />
Some applications may also need to be restarted in order for sound to play from them again.<br />
<br />
==== MP3 files cannot be played when using the GStreamer Phonon backend ====<br />
<br />
This can be solved by installing the GStreamer libav plugin (package {{Pkg|gst-libav}}). If you still encounter problems, you can try changing the Phonon backend used by installing another such as {{AUR|phonon-qt4-vlc}} or {{Pkg|phonon-qt5-vlc}}.<br />
<br />
Then, make sure the backend is preferred via ''System Settings > Multimedia > Audio and Video > Backend''.<br />
<br />
If the settings does not show any, try {{ic|phononsettings}} in your terminal.<br />
<br />
==== No volume control icon in tray and cannot adjust sound by function key ====<br />
<br />
Check if you have {{Pkg|plasma-pa}} installed.<br />
<br />
==== No sound after a short time ====<br />
<br />
If {{ic|journalctl -p4 -t pulseaudio}} contains entries saying {{ic|Failed to create sink input: sink is suspended}}, try commenting the following line in in {{ic|/etc/pulse/default.pa}}:<br />
<br />
#load-module module-suspend-on-idle<br />
<br />
If the issue persists, {{Pkg|plasma-meta}} or {{Grp|plasma}} may have installed {{Pkg|pulseaudio}} alongside {{Pkg|wireplumber}}. To fix the issue, replace {{Pkg|pulseaudio}} with {{Pkg|pipewire-pulse}}. If {{Pkg|pulseaudio}} is preferred, replace {{Pkg|wireplumber}} with {{Pkg|pipewire-media-session}}. See [[PipeWire#PulseAudio clients]] and [https://bbs.archlinux.org/viewtopic.php?id=276308 this forum thread] for more details.<br />
<br />
=== Power management ===<br />
<br />
==== No Suspend/Hibernate options ====<br />
<br />
If your system is able to suspend or hibernate using [[systemd]] but do not have these options shown in KDE, make sure {{Pkg|powerdevil}} is installed.<br />
<br />
==== No power profile options ====<br />
<br />
Make sure you [[install]]ed {{Pkg|powerdevil}} and {{Pkg|power-profiles-daemon}}.<br />
Run ''powerprofilesctl'' and check the driver. If it is {{ic|intel_pstate}} or {{ic|amd_pstate}}, you are done, otherwise see [[CPU frequency scaling#Scaling drivers]] for more information on enabling them.<br />
<br />
=== KMail ===<br />
<br />
==== Clean Akonadi configuration to fix KMail ====<br />
<br />
See [https://userbase.kde.org/KMail/FAQs_Hints_and_Tips#Clean_start_after_a_failed_migration] for details.<br />
<br />
If you want a backup, copy the following configuration directories:<br />
<br />
$ cp -a ~/.local/share/akonadi ~/.local/share/akonadi-old<br />
$ cp -a ~/.config/akonadi ~/.config/akonadi-old<br />
<br />
==== Empty IMAP inbox in KMail ====<br />
<br />
For some IMAP accounts KMail will show the inbox as a top-level container (so it will not be possible to read messages there) with all other folders of this account inside.[https://bugs.kde.org/show_bug.cgi?id=284172]. To solve this problem simply disable the server-side subscriptions in the KMail account settings.<br />
<br />
==== Authorization error for EWS account in KMail ====<br />
<br />
While setting up EWS account in KMail, you may keep getting errors about failed authorization even for valid and fully working credentials. This is likely caused by broken communication between [[KWallet]] and KMail. To workaround the issue set a passsword via qdbus:<br />
<br />
$ qdbus org.freedesktop.Akonadi.Resource.akonadi_ews_resource_0 /Settings org.kde.Akonadi.Ews.Wallet.setPassword "XXX"<br />
<br />
=== Aggressive QXcbConnection / kscreen.xcb.helper journal logging ===<br />
<br />
See [[Qt#Disable/Change Qt journal logging behaviour]].<br />
<br />
=== KF5/Qt 5 applications do not display icons in i3/FVWM/awesome ===<br />
<br />
See [[Qt#Configuration of Qt 5 applications under environments other than KDE Plasma]].<br />
<br />
=== Problems with saving credentials and persistently occurring KWallet dialogs ===<br />
<br />
It is not recommended to turn off the [[KWallet]] password saving system in the user settings as it is required to save encrypted credentials like WiFi passphrases for each user. Persistently occuring KWallet dialogs can be the consequence of turning it off.<br />
<br />
In case you find the dialogs to unlock the wallet annoying when applications want to access it, you can let the [[Display manager|display managers]] [[SDDM]] and [[LightDM]] unlock the wallet at login automatically, see [[KDE Wallet#Unlock KDE Wallet automatically on login]]. The first wallet needs to be generated by KWallet (and not user-generated) in order to be usable for system program credentials.<br />
<br />
In case you want the wallet credentials not to be opened in memory for every application, you can restrict applications from accessing it with {{Pkg|kwalletmanager}} in the KWallet settings.<br />
<br />
If you do not care for credential encryption at all, you can simply leave the password forms blank when KWallet asks for the password while creating a wallet. In this case, applications can access passwords without having to unlock the wallet first.<br />
<br />
=== Discover does not show any applications ===<br />
<br />
This can be solved by installing {{Pkg|packagekit-qt5}}.<br />
<br />
{{Warning|As explained in a [https://github.com/archlinux/archinstall/issues/1321#issuecomment-1151343223 GitHub comment] by a Package Maintainer, "Handling system packages via packagekit is just fundamentally incompatible with our high-maintenance rolling release distro, where any update might leave the system in an unbootable or otherwise unusable state if the user does not take care reading pacman's logs or merging pacnew files before rebooting."}}<br />
<br />
=== Discover stops showing updates from Arch repositories ===<br />
<br />
Discover sometimes will not remove its PackageKit alpm lock. To release it, remove {{ic|/var/lib/PackageKit/alpm/db.lck}}. Use "Refresh" in Discover and updates should appear (if there are any updates pending).<br />
<br />
=== High CPU usage of kscreenlocker_greet with NVIDIA drivers ===<br />
<br />
As described in [https://bugs.kde.org/show_bug.cgi?id=347772 KDE Bug 347772] NVIDIA OpenGL drivers and QML may not play well together with Qt 5. This may lead {{ic|kscreenlocker_greet}} to high CPU usage after unlocking the session. To work around this issue, set the {{ic|QSG_RENDERER_LOOP}} [[environment variable]] to {{ic|basic}}.<br />
<br />
Then kill previous instances of the greeter with {{ic|killall kscreenlocker_greet}}.<br />
<br />
=== OS error 22 when running Akonadi on ZFS ===<br />
<br />
If your home directory is on a [[ZFS]] pool, create a {{ic|~/.config/akonadi/mysql-local.conf}} file with the following contents:<br />
<br />
[mysqld]<br />
innodb_use_native_aio = 0<br />
<br />
See [[MariaDB#OS error 22 when running on ZFS]].<br />
<br />
=== Some programs are unable to scroll when their windows are inactive ===<br />
<br />
This is caused by the problematic way of GTK3 handling mouse scroll events. A workaround for this is to set [[environment variable]] {{ic|1=GDK_CORE_DEVICE_EVENTS=1}}. However, this workaround also breaks touchpad smooth scrolling and touchscreen scrolling.<br />
<br />
=== TeamViewer behaves slowly ===<br />
<br />
When using TeamViewer, it may behave slowly if you use smooth animations (such as windows minimizing). See [[#Disable compositing]] as a workaround.<br />
<br />
=== Kmail, Kontact and Wayland ===<br />
<br />
Kmail may become unresponsive, show a black messageviewer or similar, often after having been minimized and restored. A workaround may be to set [[environment variable]] {{ic|1=QT_QPA_PLATFORM="xcb;wayland"}}. See [https://bugs.kde.org/show_bug.cgi?id=397825 KDE Bug 397825].<br />
<br />
=== Unlock widgets (Plasma ≥ 5.18) ===<br />
<br />
If you previously locked your widgets, you will probably find yourself unable to unlock them again.<br />
You just have to run this command to do so:<br />
<br />
$ qdbus org.kde.plasmashell /PlasmaShell evaluateScript "lockCorona(false)"<br />
<br />
The new {{ic|Customize Layout}} does not require to lock them back up but if want to do that:<br />
<br />
$ qdbus org.kde.plasmashell /PlasmaShell evaluateScript "lockCorona(true)"<br />
<br />
=== KIO opens URLs with the wrong program ===<br />
<br />
Check file associations regarding HTML, PHP, etc... and change it to a browser. KIO's cache files are located in {{ic|$HOME/.cache/kioexec}}. See also [[xdg-utils#URL scheme handlers]].<br />
<br />
=== Custom Shortcuts tab is missing under Shortcuts in System Settings ===<br />
<br />
This is due to the {{Pkg|khotkeys}} package being missing. After installation, a restart of the System Settings application may be necessary to apply the changes.<br />
<br />
=== Lock the screen before suspending and hibernating ===<br />
<br />
In the System Settings application, KDE offers a setting to automatically lock the screen after waking up from sleep. Upon resuming, [https://www.reddit.com/r/kde/comments/obnpeb/how_to_lock_system_before_suspend/ some users] report that the screen is briefly showed before locking. To prevent this behavior and have KDE lock the screen before suspending, create a hook in {{man|1|systemd}} by creating the following file as the root user:<br />
<br />
{{hc|/usr/lib/systemd/system-sleep/lock_before_suspend.sh|2=<br />
#!/bin/bash<br />
<br />
case $1/$2 in<br />
pre/*)<br />
case $2 in<br />
suspend{{!}}hibernate)<br />
loginctl lock-session<br />
sleep 1<br />
;;<br />
esac<br />
;;<br />
esac<br />
}}<br />
<br />
The use of ''sleep'' is necessary in order for the lock-session to complete before the device is suspended. Lower value do not allow for completion. <br />
<br />
After creating the file, make it [[executable]]. <br />
<br />
Finally, make sure that the KDE setting is enabled by going to ''System Settings > Workspace Behavior > Screen Locking'' and checking the ''After waking from sleep'' checkbox.<br />
<br />
=== X11 shortcuts conflict on Wayland ===<br />
<br />
Some X11 software like {{Pkg|freerdp}} can grab keyboard input since KDE 5.27. Others like [[VMware]] cannot grab correctly. [https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml]<br />
<br />
It is inappropriate to force grab [https://gitlab.freedesktop.org/xorg/xserver/-/issues/1332 in Xserver] or in compositors. [https://gitlab.gnome.org/GNOME/mutter/-/issues/1720] You can solve it in an elegant way as follows:<br />
<br />
* Right click the window titlebar (e.g. VMware or Citrix);<br />
* ''More Actions > Configure Special Window Settings...''<br />
* Click ''Add Property...'' and select ''Ignore global shortcuts''. <br />
* Select ''force'' and ''yes''. Apply it.<br />
<br />
== See also ==<br />
<br />
* [https://www.kde.org/ KDE homepage]<br />
* [https://dot.kde.org/ KDE news]<br />
* [https://planet.kde.org/ KDE Blogs]<br />
* [https://discuss.kde.org/ KDE Forums]<br />
* [https://wiki.kde.org/ KDE Wikis]<br />
* [https://bugs.kde.org/ KDE bug tracker and reporter]<br />
* [https://blog.martin-graesslin.com/blog/kategorien/kde/ Martin Graesslin's blog]<br />
* [https://community.kde.org/Matrix KDE Matrix Rooms]</div>Iaz3https://wiki.archlinux.org/index.php?title=Cursor_themes&diff=793728Cursor themes2023-12-01T21:26:05Z<p>Iaz3: /* Desktop environments */ Add information for KDE Wayland</p>
<hr />
<div>[[Category:X server]]<br />
[[Category:Eye candy]]<br />
[[de:Mauscursor-Themes]]<br />
[[es:Cursor themes]]<br />
[[ja:カーソルテーマ]]<br />
[[pt:Cursor themes]]<br />
[[ru:Cursor themes]]<br />
[[zh-hans:Cursor themes]]<br />
The display server is accompanied by a ''cursor theme'' that helps various aspects of GUI navigation and manipulation. The display server includes a cursor theme, however, other cursor themes can be installed and selected.<br />
<br />
== Installation ==<br />
<br />
Installation can be done with a package, or downloaded and extracted to an appropriate directory.<br />
<br />
=== Packages ===<br />
<br />
Cursors themes are available in the:<br />
<br />
* [[Official repositories]] — search for packages with the prefix [https://archlinux.org/packages/?sort=&q=xcursor-&maintainer=&last_update=&flagged=&limit=50 "xcursor-"], or the suffix [https://archlinux.org/packages/?sort=&q=-cursors&maintainer=&last_update=&flagged=&limit=50 "-cursors"]. Several icon themes also include cursors.<br />
* [[AUR]] — [https://aur.archlinux.org/packages?O=0&L=0&C=17&K=cursor&SeB=nd&SB=n&SO=a&PP=50&do_Search=Go "cursor" search].<br />
<br />
=== Manually ===<br />
<br />
If a cursor theme is not available in the official repositories or the AUR, it can be added manually. A number of websites exist where cursor themes can be downloaded. Once downloaded, they need to be put in the ''icons'' directory (as cursors have the ability to be bundled with icon themes).<br />
<br />
Some websites that have cursor themes:<br />
<br />
* [https://www.gnome-look.org/browse/cat/107/ord/latest/ GNOME Look]<br />
* [https://www.deviantart.com/search?q=x11%20cursors Deviant Art]<br />
* [https://www.opendesktop.org/browse/cat/107/ Open Desktop]<br />
<br />
For ''user-specific'' installation, use the {{ic|~/.local/share/icons/}} or {{ic|~/.icons/}} directory. Extract them with this command that will work for most archives:<br />
<br />
$ tar xvf foobar-cursor-theme.tar.gz -C ~/.local/share/icons<br />
<br />
The cursor theme directory structure is {{ic|theme-name/cursors}}, for example: {{ic|~/.local/share/icons/''theme''/cursors/}}; make sure the extracted files follow this structure.<br />
<br />
{{Note|For ''system-wide'' installation the {{ic|/usr/share/icons}} directory is used. Direct extraction to this directory is usually discouraged as files here are not tracked by [[pacman]]; it is recommended to create a [[PKGBUILD|package]] for the cursor theme instead.}}<br />
<br />
Already installed cursor themes can be viewed with the command:<br />
<br />
find /usr/share/icons ~/.local/share/icons ~/.icons -type d -name "cursors"<br />
<br />
If the package includes an {{ic|index.theme}} file, check if there is an "Inherits" line inside. If yes, check whether the inherited theme also exists on the system (rename if needed).<br />
<br />
== Configuration ==<br />
<br />
There are various ways to set the cursor theme.<br />
<br />
=== XDG specification ===<br />
<br />
This method applies to both [[X11]] and [[Wayland]] cursor themes. <br />
<br />
For ''user-specific'' configuration, create or edit {{ic|~/.icons/default/index.theme}}; for ''system-wide'' configuration, one can edit {{ic|/usr/share/icons/default/index.theme}}.<br />
<br />
The {{ic|Inherits}} option in the {{ic|[icon theme]}} section must be set to the xcursor theme directory name {{ic|''cursor_theme_name''}}, for example {{ic|Breeze_Snow}}:<br />
<br />
{{hc|~/.icons/default/index.theme|2=<br />
[icon theme] <br />
Inherits=''cursor_theme_name''}}<br />
<br />
You should then edit {{ic|~/.config/gtk-3.0/settings.ini}}, replacing the {{ic|''cursor_theme_name''}} with the chosen one: <br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|2=<br />
[Settings]<br />
gtk-cursor-theme-name=''cursor_theme_name''}}<br />
<br />
Restart X for the changes to take effect.<br />
<br />
If it still does not work, try creating a symlink from {{ic|~/.icons/default/cursors}} (assuming ''user-specific'') to {{ic|.local/share/icons/''cursor_theme_name''/cursors}} and restart X again.<br />
<br />
=== LXAppearance ===<br />
<br />
[[LXDE#Cursors|LXAppearance]] sets the default cursor by creating an {{ic|~/.icons/default/index.theme}} file: if you edited that file manually, LXAppearance will overwrite it. Remember to also edit {{ic|~/.config/gtk-3.0/settings.ini}} manually as specified in [[#XDG specification]], because applications like Firefox use this setting instead.<br />
<br />
=== Desktop environments ===<br />
<br />
[[Desktop environments]] use the [https://specifications.freedesktop.org/xsettings-spec/xsettings-latest.html XSETTINGS protocol], typically implemented through a settings daemon. While this allows to change the cursor on-the-fly, the applied theme may be inconsistent across applications. See [[#XDG specification]] to change the cursor theme manually.<br />
<br />
==== GNOME ====<br />
<br />
To change the theme in [[GNOME]], use {{Pkg|gnome-tweaks}} or set the configuration directly with:<br />
<br />
$ gsettings set org.gnome.desktop.interface cursor-theme ''cursor_theme_name''<br />
<br />
Change the cursor size with (depending on the theme, sizes are 24, 32, 48, 64):<br />
<br />
$ gsettings set org.gnome.desktop.interface cursor-size ''cursor_theme_size''<br />
<br />
{{Note|By default, on Wayland, Gnome applications should be unable to display your cursor themes located in {{ic|~/.local/share/icons}}. As a workaround, you can [[#Environment variable|add that path to XCURSOR_PATH]].}}<br />
<br />
==== KDE (Wayland) ====<br />
<br />
{{Pkg|xdg-desktop-portal-gtk}} must be installed for GTK/Gnome apps to correctly apply cursor themeing on Wayland.<br />
<br />
==== MATE ====<br />
<br />
In MATE one can use mate-control-center or gsettings. To change the theme:<br />
<br />
gsettings set org.mate.peripherals-mouse cursor-theme ''cursor_theme_name''<br />
<br />
To change the size:<br />
<br />
gsettings set org.mate.peripherals-mouse ''theme-size''<br />
<br />
==== XFCE ====<br />
<br />
To change the xcursor theme, use:<br />
<br />
xfconf-query --channel xsettings --property /Gtk/CursorThemeName --set ''cursor_theme_name''<br />
<br />
To change the size:<br />
<br />
xfconf-query --channel xsettings --property /Gtk/CursorThemeSize --set ''cursor_theme_size''<br />
<br />
=== X resources ===<br />
<br />
To locally name a cursor theme, add to the {{ic|~/.Xresources}} file:<br />
<br />
Xcursor.theme: cursor-theme<br />
<br />
To have the cursor theme properly loaded, it will need to be done so by the window manager; if it does not, it can be forced to load prior the window manager by putting the following command in {{ic|~/.xinitrc}} or [[.xprofile]] (depending on ones personal setup):<br />
<br />
$ xrdb ~/.Xresources<br />
<br />
Optionally, add this line to {{ic|~/.Xresources}} if your cursor theme supports multiple sizes:<br />
<br />
Xcursor.size: 16<br />
<br />
{{Tip|32, 48 or 64 may also be good size.}}<br />
<br />
If in doubt over supported cursor sizes, start X without this setting and let it choose the cursor size automatically. (Refer to your window manager documentation for details.)<br />
<br />
=== Environment variable ===<br />
<br />
You can use an [[environment variable]] to set a theme for a single application to try it out temporarily, for example:<br />
<br />
$ XCURSOR_THEME=SomeThemeName xclock<br />
<br />
XCURSOR_SIZE is optional if your cursor theme supports multiple sizes.<br />
<br />
If cursor themes are installed in {{ic|~/.local/share/icons}}, in order to avoid possible issues, add that path to XCURSOR_PATH. For example:<br />
<br />
{{hc|~/.bash_profile|2=<br />
export XCURSOR_PATH=${XCURSOR_PATH}:~/.local/share/icons}}<br />
<br />
=== Display managers ===<br />
<br />
Cursor theme can usually be set within a display manager, but keep in mind the cursor theme may not carry over to the user session.<br />
<br />
==== GDM ====<br />
<br />
See [[GDM#Changing the cursor theme]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Create links to missing cursors ===<br />
<br />
Applications may keep using the default cursors when a theme lacks some cursors. This can be corrected by adding links to the missing cursors. For example:<br />
<br />
$ cd ~/.icons/''theme''/cursors/<br />
$ ln -s right_ptr arrow<br />
$ ln -s cross crosshair<br />
$ ln -s right_ptr draft_large<br />
$ ln -s right_ptr draft_small<br />
$ ln -s cross plus<br />
$ ln -s left_ptr top_left_arrow<br />
$ ln -s cross tcross<br />
$ ln -s hand hand1<br />
$ ln -s hand hand2<br />
$ ln -s left_side left_tee<br />
$ ln -s left_ptr ul_angle<br />
$ ln -s left_ptr ur_angle<br />
$ ln -s left_ptr_watch 08e8e1c95fe2fc01f976f1e063a24ccd<br />
<br />
If the above does not solve the problem, look in {{ic|/usr/share/icons/whiteglass/cursors}} for additional cursors your theme may be missing, and create links for these as well.<br />
<br />
{{Tip|You can also remove unwanted cursors. To for example remove the "watch" cursor:<br />
<br />
$ cd ~/.icons/''theme''/cursors/<br />
$ rm watch left_ptr_watch<br />
$ ln -s left_ptr watch<br />
$ ln -s left_ptr left_ptr_watch<br />
}}<br />
<br />
=== Supplying missing cursors ===<br />
<br />
Some programs set their own custom cursors {{ic|~/.Xresources}} which you may want to override. A common example of this is rdesktop, which connects to a Microsoft Windows computer and uses the cursors obtained from the remote machine, which can often be difficult to see due to protocol limitations yielding poor conversion quality.<br />
<br />
This can be resolved by replacing these cursors with ones from the same (or another) cursor theme. In order to do this, the '''hash''' of the image must be obtained. This is done by setting the {{ic|XCURSOR_DISCOVER}} environment variable prior to launching the application that sets these cursors:<br />
<br />
$ XCURSOR_DISCOVER=1 rdesktop ...<br />
<br />
The first time (and only the first time) the cursor is set, some details will be displayed, like this:<br />
<br />
Cursor image name: 24020000002800000528000084810000<br />
...<br />
Cursor image name: 7bf1cc07d310bf080118007e08fc30ff<br />
...<br />
Cursor hash 24020000002800000528000084810000 returns 0x0<br />
<br />
When Xcursor looks for missing cursors, the search path includes {{ic|~/.icons/default/cursors}} so this is where an image can be placed for Xcursor to find. First, create this directory if it does not already exist:<br />
<br />
$ mkdir -p ~/.icons/default/cursors<br />
<br />
Then link the hash to the target image. Here we are using the {{ic|left_ptr}} image from the {{ic|Vanilla-DMZ}} cursor theme:<br />
<br />
$ ln -s /usr/share/icons/Vanilla-DMZ/cursors/left_ptr ~/.icons/default/cursors/24020000002800000528000084810000<br />
<br />
The change will be visible as soon as the application is restarted. No special method of launching the application is required.<br />
<br />
=== Change X shaped default cursor ===<br />
<br />
The default X shaped Xcursor appears in window managers that do not set the default cursor to left_ptr or in window managers using XCB (like [[awesome]]) instead of Xlib.<br />
<br />
To fix this, simply add the following to your {{ic|~/.xinitrc}}, xsession or window managers startup configuration if possible (for example bspwm's bspwmrc). <br />
$ xsetroot -cursor_name left_ptr<br />
<br />
The list of cursor styles is in [https://tronche.com/gui/x/xlib/appendix/b/ appendix B] of the X protocol.<br />
<br />
=== .Xdefaults ===<br />
<br />
If you have conflicting cursors then it might be because a different cursor has been set in the {{ic|~/.Xdefaults}} file.<br />
<br />
=== Cursor size does not change on startup ===<br />
<br />
If you are trying to change cursor size via {{ic|~/.Xresources}} in your {{ic|~/.xinitrc}} and it does not work, make sure that xrandr runs before loading {{ic|~/.Xresources}}.<br />
<br />
Make sure your {{ic|~/.xinitrc}} looks similar to the following<br />
<br />
{{hc|~/.xinitrc|2=<br />
xrandr<br />
...<br />
xrdb -merge ~/.Xresources<br />
exec ''wm''}}<br />
<br />
=== Cursor size or theme does not change on Plasma (Wayland) ===<br />
<br />
When changing the cursor size or theme when using [[Plasma]] under [[Wayland]], make sure to restart the session after applying the changes [https://community.kde.org/Plasma/Wayland_Showstoppers#KWin.2Fcompositing.2Fwindow_management] [https://bugs.kde.org/show_bug.cgi?id=420859].<br />
<br />
This is a bug. See a workaround at [[KDE#Plasma cursor sometimes shown incorrectly]].<br />
<br />
== See also ==<br />
<br />
* {{man|3|Xcursor}} — For more information about cursors in X (supported directories, formats, compatibility, etc.).<br />
* For the creation of cursor files, see [[Xcursorgen]]</div>Iaz3https://wiki.archlinux.org/index.php?title=ZFS&diff=792525ZFS2023-11-14T23:04:48Z<p>Iaz3: /* I/O Scheduler */ add info on the ZFS I/O scheduler recommendation</p>
<hr />
<div>[[Category:File systems]]<br />
[[Category:Oracle]]<br />
[[ja:ZFS]]<br />
[[pt:ZFS]]<br />
[[zh-hans:ZFS]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related|ZFS/Virtual disks}}<br />
{{Related|Installing Arch Linux on ZFS}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:ZFS|ZFS]] is an advanced filesystem created by [[Wikipedia:Sun Microsystems|Sun Microsystems]] (now owned by Oracle) and released for OpenSolaris in November 2005.<br />
<br />
Features of ZFS include: pooled storage (integrated volume management – zpool), [[Wikipedia:Copy-on-write|Copy-on-write]], [[Wikipedia:Snapshot (computer storage)|snapshots]], data integrity verification and automatic repair (scrubbing), [[Wikipedia:RAID-Z|RAID-Z]], a maximum [[Wikipedia:Exabyte|16 exabyte]] file size, and a maximum 256 quadrillion [[Wikipedia:Zettabyte|zettabyte]] storage with no limit on number of filesystems (datasets) or files[https://docs.oracle.com/cd/E19253-01/819-5461/zfsover-2/index.html]. ZFS is licensed under the [[Wikipedia:CDDL|Common Development and Distribution License]] (CDDL).<br />
<br />
Described as [https://web.archive.org/web/20060428092023/http://www.sun.com/2004-0914/feature/ "The last word in filesystems"], ZFS is stable, fast, secure, and future-proof. Being licensed under the CDDL, and thus incompatible with GPL, it is not possible for ZFS to be distributed along with the Linux Kernel. This requirement, however, does not prevent a native Linux kernel module from being developed and distributed by a third party, as is the case with [https://openzfs.org OpenZFS], previously named [https://zfsonlinux.org/ ZFS on Linux] (ZOL).<br />
<br />
ZOL is a project funded by the [https://www.llnl.gov/ Lawrence Livermore National Laboratory] to develop a native Linux kernel module for its massive storage requirements and super computers.<br />
<br />
{{Note|<br />
Due to potential legal incompatibilities between CDDL license of ZFS code and GPL of the Linux kernel ([https://sfconservancy.org/blog/2016/feb/25/zfs-and-linux/ ],[[wikipedia:Common_Development_and_Distribution_License#GPL_compatibility|CDDL-GPL]],[[wikipedia:ZFS#Linux|ZFS in Linux]]) - ZFS development is not supported by the kernel.<br />
<br />
As a result:<br />
<br />
* ZFSonLinux project must keep up with Linux kernel versions. After making stable ZFSonLinux release - Arch ZFS maintainers release them.<br />
* This situation sometimes locks down the normal rolling update process by unsatisfied dependencies because the new kernel version, proposed by update, is unsupported by ZFSonLinux.<br />
}}<br />
<br />
== Installation ==<br />
<br />
=== General ===<br />
<br />
{{Warning|Unless you use the [[dkms]] versions of these packages, the ZFS and SPL kernel modules are tied to a specific kernel version. It would not be possible to apply any kernel updates until updated packages are uploaded to AUR or the [[Unofficial user repositories#archzfs|archzfs]] repository.}}<br />
<br />
{{Tip| You can [[downgrade]] your linux version to the one from [[Unofficial user repositories#archzfs|archzfs]] repo if your current kernel is newer.}}<br />
<br />
Install from the [[Unofficial user repositories#archzfs|archzfs]] repository or alternatively the [[Arch User Repository]]:<br />
<br />
* {{AUR|zfs-linux}} for [https://zfsonlinux.org/ stable] releases.<br />
* {{AUR|zfs-linux-git}} for [https://github.com/openzfs/zfs development] releases (with support of newer kernel versions).<br />
* {{AUR|zfs-linux-lts}} for stable releases for LTS kernels.<br />
* {{AUR|zfs-linux-lts-git}} for development releases for LTS kernels.<br />
* {{AUR|zfs-linux-hardened}} for stable releases for hardened kernels.<br />
* {{AUR|zfs-linux-hardened-git}} for development releases for hardened kernels.<br />
* {{AUR|zfs-linux-zen}} for stable releases for zen kernels.<br />
* {{AUR|zfs-linux-zen-git}} for development releases for zen kernels.<br />
* {{AUR|zfs-dkms}} for versions with dynamic kernel module support.<br />
* {{AUR|zfs-dkms-git}} for development releases for versions with dynamic kernel module support.<br />
<br />
These packages have a dependency on the {{ic|zfs-utils}} package.<br />
<br />
Test the installation by issuing {{ic|zpool status}} on the command line. If an "insmod" error is produced, try {{ic|depmod -a}}.<br />
<br />
=== Root on ZFS ===<br />
<br />
See [[Install Arch Linux on ZFS#Installation]].<br />
<br />
=== DKMS ===<br />
<br />
Users can make use of [[DKMS]] to rebuild the ZFS modules automatically with every kernel upgrade. <br />
<br />
{{Note|When installing {{Pkg|dkms}}, read [[Dynamic Kernel Module Support#Installation]]}}<br />
<br />
Install {{AUR|zfs-dkms}} or {{AUR|zfs-dkms-git}}.<br />
<br />
{{Tip|Add an {{ic|IgnorePkg}} entry to [[pacman.conf]] to prevent these packages from upgrading when doing a regular update.}}<br />
<br />
== Experimenting with ZFS ==<br />
<br />
Users wishing to experiment with ZFS on ''virtual block devices'' (known in ZFS terms as VDEVs) which can be simple files like {{ic|~/zfs0.img}} {{ic|~/zfs1.img}} {{ic|~/zfs2.img}} etc. with no possibility of real data loss are encouraged to see the [[Experimenting with ZFS]] article. Common tasks like building a RAIDZ array, purposefully corrupting data and recovering it, snapshotting datasets, etc. are covered.<br />
<br />
== Configuration ==<br />
<br />
ZFS is considered a "zero administration" filesystem by its creators; therefore, configuring ZFS is very straight forward. Configuration is done primarily with two commands: {{ic|zfs}} and {{ic|zpool}}.<br />
<br />
=== Automatic Start ===<br />
<br />
For ZFS to live by its "zero administration" namesake, {{Ic|zfs-import-cache.service}} must be enabled to import the pools and {{Ic|zfs-mount.service}} must be enabled to mount the filesystems available in the pools. A benefit to this is that it is not necessary to mount ZFS filesystems in {{ic|/etc/fstab}}. {{Ic|zfs-import-cache.service}} imports the zfs pools reading the file {{ic|/etc/zfs/zpool.cache}}.<br />
<br />
For each [[#Importing a pool created by id|imported pool]] you want automatically imported by {{Ic|zfs-import-cache.service}} execute:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache <pool><br />
<br />
{{Note|Beginning with [https://github.com/openzfs/zfs/releases/tag/zfs-0.6.5.8 OpenZFS version 0.6.5.8] the ZFS service unit files have been changed so that you need to explicitly enable any ZFS services you want to run. See [https://github.com/archzfs/archzfs/issues/72 ArchZFS issue 72] for more information.}}<br />
<br />
[[Enable]] the relevant service ({{ic|zfs-import-cache.service}}) and targets ({{ic|zfs.target}} and {{ic|zfs-import.target}}) so the pools are automatically imported at boot time:<br />
<br />
To mount the ZFS filesystems, you have 2 choices:<br />
* Enable the [[#Using zfs-mount.service|zfs-mount.service]]<br />
* Using [[#Using zfs-mount-generator|zfs-mount-generator]]<br />
<br />
==== Using zfs-mount.service ====<br />
<br />
In order to mount ZFS filesystems automatically on boot you need to [[enable]] {{ic|zfs-mount.service}} and {{ic|zfs.target}}.<br />
<br />
{{Note|1=<nowiki/><br />
* This does not work with separated {{ic|/var}} dataset because it does not get mounted early enough. Instead you should use [[#Using zfs-mount-generator|zfs-mount-generator]] option. See [https://github.com/openzfs/zfs/issues/3768 OpenZFS issue #3768] for more information.<br />
* It appears that the ZFS module is loaded too late for using this method, see [https://bbs.archlinux.org/viewtopic.php?id=274044 BBS#274044] and [[Talk:ZFS#zfs hook in mkinitcpio.conf]]. The workaround is to use the {{ic|ZFS}} [[mkinitcpio]] hook.<br />
}}<br />
<br />
==== Using zfs-mount-generator ====<br />
<br />
You can also use the zfs-mount-generator to create systemd mount units for your ZFS filesystems at boot. systemd will automatically mount the filesystems based on the mount units without having to use the {{Ic|zfs-mount.service}}. To do that, you need to:<br />
<br />
# Create the {{Ic|/etc/zfs/zfs-list.cache}} directory.<br />
# Enable the ZFS Event Daemon(ZED) script (called a ZEDLET) required to create a list of mountable ZFS filesystems. (This link is created automatically if you are using OpenZFS >= 2.0.0.) {{bc|# ln -s /usr/lib/zfs/zed.d/history_event-zfs-list-cacher.sh /etc/zfs/zed.d}}<br />
# [[Enable]] {{ic|zfs.target}} and [[enable/start]] the ZFS Event Daemon ({{ic|zfs-zed.service}}). This service is responsible for running the script in the previous step. <br />
# You need to create an empty file named after your pool in {{Ic|/etc/zfs/zfs-list.cache}}. The ZEDLET will only update the list of filesystems if the file for the pool already exists. {{bc|# touch /etc/zfs/zfs-list.cache/<pool-name>}}<br />
# Check the contents of {{Ic|/etc/zfs/zfs-list.cache/<pool-name>}}. If it is empty, make sure that the {{Ic|zfs-zed.service}} is running and just change the canmount property of any of your ZFS filesystem by running: {{bc|1=zfs set canmount=off zroot/fs1}} This change causes ZFS to raise an event which is captured by ZED, which in turn runs the ZEDLET to update the file in {{Ic|/etc/zfs/zfs-list.cache}}. If the file in {{Ic|/etc/zfs/zfs-list.cache}} is updated, you can set the {{Ic|canmount}} property of the filesystem back by running: {{bc|1=zfs set canmount=on zroot/fs1}}<br />
You need to add a file in {{Ic|/etc/zfs/zfs-list.cache}} for each ZFS pool in your system. Make sure the pools are imported by enabling {{Ic|zfs-import-cache.service}} and {{Ic|zfs-import.target}} as [[#Automatic Start|explained above]].<br />
<br />
== Storage pools ==<br />
<br />
It is not necessary to partition the drives before creating the ZFS filesystem. It is recommended to point ZFS at an entire disk (ie. {{ic|/dev/sdx}} rather than {{ic|/dev/sdx1}}), which will [https://www.reddit.com/r/zfs/comments/667na0/zfs_on_raw_or_gpt/dgh0l9t/ automatically create a GPT (GUID Partition Table)] and add an 8 MB reserved partition at the end of the disk for legacy bootloaders. However, you can specify a partition or a file within an existing filesystem, if you wish to create multiple volumes with different redundancy properties.<br />
<br />
{{Note|If some or all device have been used in a software RAID set it is paramount to [[mdadm#Prepare the devices|erase any old RAID configuration information]].}}<br />
<br />
{{Warning|For [[Advanced Format]] Disks with 4KB sector size, an ashift of 12 is recommended for best performance. Advanced Format disks emulate a sector size of 512 bytes for compatibility with legacy systems, this causes ZFS to sometimes use an ashift option number that is not ideal. Once the pool has been created, the only way to change the ashift option is to recreate the pool. Using an ashift of 12 would also decrease available capacity. See the OpenZFS FAQ: [https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html#performance-considerations Performance Considerations], [https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html#advanced-format-disks Advanced Format Disks], and [https://web.archive.org/web/20170913063528/https://wiki.illumos.org/display/illumos/ZFS+and+Advanced+Format+disks ZFS and Advanced Format disks].}}<br />
<br />
=== Identify disks ===<br />
<br />
OpenZFS recommends using device IDs when creating ZFS storage pools of less than 10 devices[https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html#selecting-dev-names-when-creating-a-pool-linux]. Use [[Persistent block device naming#by-id and by-path]] to identify the list of drives to be used for ZFS pool. <br />
<br />
The disk IDs should look similar to the following:<br />
<br />
{{hc|$ ls -lh /dev/disk/by-id/|<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JKRR -> ../../sdc<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JTM1 -> ../../sde<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KBP8 -> ../../sdd<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KDGY -> ../../sdb}}<br />
<br />
{{Warning|If you create zpools using device names (e.g. {{ic|/dev/sda}},{{ic|/dev/sdb}},...) ZFS might not be able to detect zpools intermittently on boot.}}<br />
<br />
==== Using GPT labels ====<br />
<br />
{{Style|Missing references to [[Persistent block device naming]], it is useless to explain the differences (or even what they are) here.}}<br />
<br />
Disk labels and UUID can also be used for ZFS mounts by using [[GUID Partition Table|GPT]] partitions. ZFS drives have labels but Linux is unable to read them at boot. Unlike [[Master Boot Record|MBR]] partitions, GPT partitions directly support both UUID and labels independent of the format inside the partition. Partitioning rather than using the whole disk for ZFS offers two additional advantages. The OS does not generate bogus partition numbers from whatever unpredictable data ZFS has written to the partition sector, and if desired, you can easily over provision SSD drives, and slightly over provision spindle drives to ensure that different models with slightly different sector counts can zpool replace into your mirrors. This is a lot of organization and control over ZFS using readily available tools and techniques at almost zero cost.<br />
<br />
Use [[GUID Partition Table|gdisk]] to partition the all or part of the drive as a single partition. gdisk does not automatically name partitions so if partition labels are desired use gdisk command "c" to label the partitions. Some reasons you might prefer labels over UUID are: labels are easy to control, labels can be titled to make the purpose of each disk in your arrangement readily apparent, and labels are shorter and easier to type. These are all advantages when the server is down and the heat is on. GPT partition labels have plenty of space and can store most international characters [[wikipedia:GUID_Partition_Table#Partition_entries]] allowing large data pools to be labeled in an organized fashion.<br />
<br />
Drives partitioned with GPT have labels and UUID that look like this. <br />
<br />
{{hc|$ ls -l /dev/disk/by-partlabel|<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 zfsdata1 -> ../../sdd1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 zfsdata2 -> ../../sdc1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:59 zfsl2arc -> ../../sda1}}<br />
<br />
{{hc|$ ls -l /dev/disk/by-partuuid|<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 148c462c-7819-431a-9aba-5bf42bb5a34e -> ../../sdd1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:59 4f95da30-b2fb-412b-9090-fc349993df56 -> ../../sda1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 e5ccef58-5adf-4094-81a7-3bac846a885f -> ../../sdc1<br />
}}<br />
<br />
{{Tip|To minimize typing and copy/paste errors, set a local variable with the target PARTUUID: {{ic|<nowiki>$ UUID=$(lsblk --noheadings --output PARTUUID /dev/sd</nowiki>''XY''<nowiki>)</nowiki>}} }}<br />
<br />
=== Creating ZFS pools ===<br />
<br />
To create a ZFS pool:<br />
<br />
# zpool create -f -m <mount> <pool> [raidz(2|3)|mirror] <ids><br />
<br />
{{Tip|One may want to read [[#Advanced Format disks]] first as it may be recommend to set {{ic|ashift}} on pool creation.}}<br />
<br />
* '''create''': subcommand to create the pool.<br />
<br />
* '''-f''': Force creating the pool. This is to overcome the "EFI label error". See [[#Does not contain an EFI label]].<br />
* '''-m''': The mount point of the pool. If this is not specified, then the pool will be mounted to {{ic|/<pool>}}.<br />
* '''pool''': This is the name of the pool.<br />
* '''raidz(2|3)|mirror''': This is the type of virtual device that will be created from the list of devices. Raidz is a single disk of parity (similar to raid5), raidz2 for 2 disks of parity (similar to raid6) and raidz3 for 3 disks of parity. Also available is '''mirror''', which is similar to raid1 or raid10, but is not constrained to just 2 device. If not specified, each device will be added as a vdev which is similar to raid0. After creation, a device can be added to each single drive vdev to turn it into a mirror, which can be useful for migrating data.<br />
* '''ids''': The [[Persistent block device naming#by-id and by-path|ID's]] of the drives or partitions that to include into the pool.<br />
<br />
Create pool with single raidz vdev:<br />
<br />
# zpool create -f -m /mnt/data bigdata \<br />
raidz \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
Create pool with two mirror vdevs:<br />
<br />
# zpool create -f -m /mnt/data bigdata \<br />
mirror \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
mirror \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
==== Advanced Format disks ====<br />
<br />
At pool creation, '''ashift=12''' should always be used, except with SSDs that have 8k sectors where '''ashift=13''' is correct. A vdev of 512 byte disks using 4k sectors will not experience performance issues, but a 4k disk using 512 byte sectors will. Since '''ashift''' cannot be changed after pool creation, even a pool with only 512 byte disks should use 4k because those disks may need to be replaced with 4k disks or the pool may be expanded by adding a vdev composed of 4k disks. Because correct detection of 4k disks is not reliable, {{ic|<nowiki>-o ashift=12</nowiki>}} should always be specified during pool creation. See the [https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html#advanced-format-disks OpenZFS FAQ] for more details.<br />
<br />
{{Tip|Use {{man|8|blockdev}} (part of {{Pkg|util-linux}}) to print the sector size reported by the device's ioctls: {{ic|blockdev --getpbsz /dev/sd''XY''}} as the root user.}}<br />
<br />
Create pool with ashift=12 and single raidz vdev:<br />
<br />
# zpool create -f -o ashift=12 -m /mnt/data bigdata \<br />
raidz \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
==== GRUB-compatible pool creation ====<br />
<br />
By default, ''zpool create'' enables all features on a pool. If {{ic|/boot}} resides on ZFS when using [[GRUB]] you must only enable features supported by GRUB otherwise GRUB will not be able to read the pool. ZFS includes compatibility files (see {{ic|/usr/share/zfs/compatibility.d}}) to assist in creating pools at specific feature sets, of which grub2 is an option.<br />
<br />
You can create a pool with only the compatible features enabled:<br />
<br />
# zpool create -o compatibility=grub2 $POOL_NAME $VDEVS<br />
<br />
=== Verifying pool status ===<br />
<br />
If the command is successful, there will be no output. Using the [[mount]] command will show that the pool is mounted. Using {{ic|zpool status}} will show that the pool has been created:<br />
<br />
{{hc|# zpool status -v|<br />
pool: bigdata<br />
state: ONLINE<br />
scan: none requested<br />
config:<br />
<br />
NAME STATE READ WRITE CKSUM<br />
bigdata ONLINE 0 0 0<br />
-0 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KDGY-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JKRR-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KBP8-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JTM1-part1 ONLINE 0 0 0<br />
<br />
errors: No known data errors<br />
}}<br />
<br />
At this point it would be good to reboot the machine to ensure that the ZFS pool is mounted at boot. It is best to deal with all errors before transferring data.<br />
<br />
=== Importing a pool created by id ===<br />
<br />
Eventually a pool may fail to auto mount and you need to import to bring your pool back. Take care to avoid the most obvious solution.<br />
<br />
{{Warning|Do not run {{ic|zpool import ''pool''}}! This will import your pools using {{ic|/dev/sd?}} which will lead to problems the next time you rearrange your drives. This may be as simple as rebooting with a USB drive left in the machine.}}<br />
<br />
Adapt one of the following commands to import your pool so that pool imports retain the persistence they were created with:<br />
<br />
# zpool import -d /dev/disk/by-id bigdata<br />
# zpool import -d /dev/disk/by-partlabel bigdata<br />
# zpool import -d /dev/disk/by-partuuid bigdata<br />
<br />
{{Note|Use the {{ic|-l}} flag when importing a pool that contains [[#Native encryption|encrypted datasets keys]], e.g.:<br />
# zpool import -l -d /dev/disk/by-id bigdata<br />
}}<br />
<br />
Finally check the state of the pool:<br />
<br />
# zpool status -v bigdata<br />
<br />
=== Destroy a storage pool ===<br />
<br />
ZFS makes it easy to destroy a mounted storage pool, removing all metadata about the ZFS device.<br />
<br />
{{Warning|This command destroys '''any data''' containing in the pool and/or dataset.}}<br />
<br />
To destroy the pool:<br />
# zpool destroy <pool><br />
<br />
To destroy a dataset:<br />
# zfs destroy <pool>/<dataset><br />
<br />
And now when checking the status:<br />
<br />
{{hc|# zpool status|<br />
no pools available<br />
}}<br />
<br />
=== Exporting a storage pool ===<br />
<br />
If a storage pool is to be used on another system, it will first need to be exported. It is also necessary to export a pool if it has been imported from the archiso as the hostid is different in the archiso as it is in the booted system. The zpool command will refuse to import any storage pools that have not been exported. It is possible to force the import with the {{ic|-f}} argument, but this is considered bad form.<br />
<br />
Any attempts made to import an un-exported storage pool will result in an error stating the storage pool is in use by another system. This error can be produced at boot time abruptly abandoning the system in the busybox console and requiring an archiso to do an emergency repair by either exporting the pool, or adding the {{ic|1=zfs_force=1}} to the kernel boot parameters (which is not ideal). See [[#On boot the zfs pool does not mount stating: "pool may be in use from other system"]].<br />
<br />
To export a pool:<br />
<br />
# zpool export <pool><br />
<br />
=== Extending an existing zpool ===<br />
<br />
A device (a partition or a disk) can be added to an existing zpool:<br />
<br />
# zpool add <pool> <device-id><br />
<br />
To import a pool which consists of multiple devices:<br />
<br />
# zpool import -d <device-id-1> -d <device-id-2> <pool><br />
<br />
or simply:<br />
<br />
# zpool import -d /dev/disk-by-id/ <pool><br />
<br />
=== Attaching a device to (create) a mirror ===<br />
<br />
A device (a partition or a disk) can be attached aside an existing device to be its mirror (similar to RAID 1):<br />
<br />
# zpool attach <pool> <device-id|mirror> <new-device-id><br />
<br />
You can attach the new device to an already existing mirror vdev (e.g. to upgrade from a 2-device to a 3-device mirror) or [https://askubuntu.com/a/1303462 attach it to single device to create a new mirror vdev].<br />
<br />
=== Renaming a zpool ===<br />
<br />
Renaming a zpool that is already created is accomplished in 2 steps:<br />
<br />
# zpool export oldname<br />
# zpool import oldname newname<br />
<br />
=== Setting a different mount point ===<br />
<br />
The mount point for a given zpool can be moved at will with one command:<br />
# zfs set mountpoint=/foo/bar poolname<br />
<br />
=== Upgrade zpools ===<br />
<br />
When using a newer {{ic|zfs}} module, zpools may display an upgrade indication:<br />
<br />
{{hc|$ zpool status -v|2=<br />
pool: bigdata<br />
state: ONLINE<br />
status: Some supported features are not enabled on the pool. The pool can still be used, but some features are unavailable.<br />
action: Enable all features using 'zpool upgrade'. Once this is done, the pool may no longer be accessible by software that does not support the features. See zpool-features(5) for details.<br />
}}<br />
<br />
{{Note|<br />
* Lower version {{ic|zfs}} modules will not be able to import a zpool of a higher version.<br />
* When dealing with important data, one may want to create a [[backup]] prior running a {{ic|zpool upgrade}}.<br />
}}<br />
<br />
To upgrade the version of zpool ''bigdata'':<br />
<br />
# zpool upgrade bigdata<br />
<br />
To upgrade the version of all zpools:<br />
<br />
# zpool upgrade -a<br />
<br />
== Creating datasets ==<br />
<br />
Users can optionally create a dataset under the zpool as opposed to manually creating directories under the zpool. Datasets allow for an increased level of control (quotas for example) in addition to snapshots. To be able to create and mount a dataset, a directory of the same name must not pre-exist in the zpool. To create a dataset, use:<br />
<br />
# zfs create <nameofzpool>/<nameofdataset><br />
<br />
It is then possible to apply ZFS specific attributes to the dataset. For example, one could assign a quota limit to a specific directory within a dataset:<br />
<br />
# zfs set quota=20G <nameofzpool>/<nameofdataset>/<directory><br />
<br />
To see all the commands available in ZFS, see {{man|8|zfs|url=}} or {{man|8|zpool|url=}}.<br />
<br />
=== Native encryption ===<br />
<br />
ZFS offers the following supported encryption options: {{ic|aes-128-ccm}}, {{ic|aes-192-ccm}}, {{ic|aes-256-ccm}}, {{ic|aes-128-gcm}}, {{ic|aes-192-gcm}} and {{ic|aes-256-gcm}}. When encryption is set to {{ic|on}}, {{ic|aes-256-gcm}} will be used. See [https://openzfs.github.io/openzfs-docs/man/8/zfs-change-key.8.html#Encryption zfs-change-key(8)] for a description of the native encryption, including limitations.<br />
<br />
The following keyformats are supported: {{ic|passphrase}}, {{ic|raw}}, {{ic|hex}}.<br />
<br />
One can also specify/increase the default iterations of PBKDF2 when using {{ic|passphrase}} with {{ic|-o pbkdf2iters <n>}}, although it may increase the decryption time.<br />
<br />
{{Tip|<br />
* To import a pool with keys, one needs to specify the {{ic|-l}} flag, without this flag encrypted datasets will be left unavailable until the keys are loaded. See [[#Importing a pool created by id]].<br />
* Native ZFS encryption has been made available in the stable 0.8.0 release or newer. Previously it was only available in development versions provided by packages like {{AUR|zfs-linux-git}}, {{AUR|zfs-dkms-git}} or other development builds. Users who were only using the development versions for the native encryption, may now switch to the stable releases if they wish.<br />
* The default encryption suite was changed from {{ic|aes-256-ccm}} to {{ic|aes-256-gcm}} in the 0.8.4 release.<br />
}}<br />
<br />
To create a dataset including native encryption with a passphrase, use:<br />
<br />
# zfs create -o encryption=on -o keyformat=passphrase <nameofzpool>/<nameofdataset><br />
<br />
To use a key instead of using a passphrase:<br />
<br />
# dd if=/dev/random of=/path/to/key bs=1 count=32<br />
# zfs create -o encryption=on -o keyformat=raw -o keylocation=file:///path/to/key <nameofzpool>/<nameofdataset><br />
<br />
The easy way to make a key in human-readable form ({{ic|keyformat{{=}}hex}}):<br />
<br />
# od -Anone -x -N 32 -w64 /dev/random | tr -d [:blank:] > /path/to/hex.key<br />
<br />
To verify the key location:<br />
<br />
# zfs get keylocation <nameofzpool>/<nameofdataset><br />
<br />
To change the key location:<br />
<br />
# zfs set keylocation=file:///path/to/key <nameofzpool>/<nameofdataset><br />
<br />
You can also manually load the keys by using one of the following commands:<br />
<br />
# zfs load-key <nameofzpool>/<nameofdataset> # load key for a specific dataset<br />
# zfs load-key -a # load all keys<br />
# zfs load-key -r zpool/dataset # load all keys in a dataset<br />
<br />
To mount the created encrypted dataset:<br />
<br />
# zfs mount <nameofzpool>/<nameofdataset><br />
<br />
==== Unlock/Mount at boot time: systemd ====<br />
<br />
It is possible to automatically unlock a pool dataset on boot time by using a [[systemd]] unit. For example create the following service to unlock any specific dataset: <br />
<br />
{{hc|1=/etc/systemd/system/zfs-load-key@.service|2=<nowiki>[Unit]<br />
Description=Load %I encryption keys<br />
Before=systemd-user-sessions.service zfs-mount.service<br />
After=zfs-import.target<br />
Requires=zfs-import.target<br />
DefaultDependencies=no<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/bash -c 'until (systemd-ask-password "Encrypted ZFS password for %I" --no-tty | zfs load-key %I); do echo "Try again!"; done'<br />
<br />
[Install]<br />
WantedBy=zfs-mount.service<br />
</nowiki>}}<br />
<br />
[[Enable/start]] the service for each encrypted dataset, (e.g. {{ic|zfs-load-key@pool0-dataset0.service}}). Note the use of {{ic|-}}, which is an escaped {{ic|/}} in systemd unit definitions. See {{ic|systemd-escape(1)}} for more info.<br />
{{Note|The {{ic|1=Before=systemd-user-sessions.service}} ensures that systemd-ask-password is invoked before the local IO devices are handed over to the [[desktop environment]].}}<br />
<br />
An alternative is to load all possible keys:<br />
<br />
{{hc|/etc/systemd/system/zfs-load-key.service|2=<br />
[Unit]<br />
Description=Load encryption keys<br />
DefaultDependencies=no<br />
After=zfs-import.target<br />
Before=zfs-mount.service<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/zfs load-key -a<br />
StandardInput=tty-force<br />
<br />
[Install]<br />
WantedBy=zfs-mount.service<br />
}}<br />
<br />
[[Enable/start]] {{ic|zfs-load-key.service}}.<br />
<br />
==== Unlock at login time: PAM ====<br />
<br />
If you are not encrypting the root volume, but only the home volume or a user-specific volume, another idea is to [https://blog.trifork.com/2020/05/22/linux-homedir-encryption/ wait until login to decrypt it]. The advantages of this method are that the system boots uninterrupted, and that when the user logs in, the same password can be used both to authenticate and to decrypt the home volume, so that the password is only entered once.<br />
<br />
First set the mountpoint to legacy to avoid having it mounted by {{ic|zfs mount -a}}:<br />
{{bc|1=zfs set mountpoint=legacy zroot/data/home}}<br />
Ensure that it is in /etc/fstab so that {{ic|mount /home}} will work:<br />
{{hc|/etc/fstab|zroot/data/home /home zfs rw,xattr,posixacl,noauto 0 0}}<br />
<br />
On a single-user system, with only one {{ic|/home}} volume having the same encryption password as the user's password, it can be decrypted at login as follows: first create {{ic|/usr/local/bin/mount-zfs-homedir}}<br />
<br />
{{hc|/usr/local/bin/mount-zfs-homedir|2=<br />
#!/bin/bash<br />
<br />
# simplified from https://talldanestale.dk/2020/04/06/zfs-and-homedir-encryption/<br />
<br />
set -eu<br />
<br />
# Password is given to us via stdin, save it in a variable for later<br />
PASS=$(cat -)<br />
<br />
VOLNAME="zroot/data/home"<br />
<br />
# Unlock and mount the volume<br />
zfs load-key "$VOLNAME" <<< "$PASS" {{!}}{{!}} continue<br />
zfs mount "$VOLNAME" {{!}}{{!}} true # ignore errors<br />
}}<br />
<br />
do not forget {{ic|chmod a+x /usr/local/bin/mount-zfs-homedir}}; then get PAM to run it by adding the following line to /etc/pam.d/system-auth:<br />
<br />
{{hc|/etc/pam.d/system-auth|auth optional pam_exec.so expose_authtok /usr/local/bin/mount-zfs-homedir<br />
}}<br />
<br />
Now it will transparently decrypt and mount the /home volume when you log in anywhere: on the console, via ssh, etc. A caveat is that since your {{ic|~/.ssh}} directory is not mounted, if you log in via ssh, you must use the default password authentication the first time rather than relying on {{ic|~/.ssh/authorized_keys}}.<br />
<br />
If you want to have separate volumes for each user, each encrypted with the user's password, try the [https://blog.trifork.com/2020/05/22/linux-homedir-encryption/ linked method].<br />
<br />
=== Swap volume ===<br />
<br />
{{Warning|<br />
* On systems with extremely high memory pressure, using a zvol for swap can result in lockup, regardless of how much swap is still available. This issue is currently being investigated in [https://github.com/openzfs/zfs/issues/7734 OpenZFS issue #7734]<br />
* Swap on zvol does not support resume from hibernation, attempt to resume will result in pool corruption. Possible workaround: https://github.com/openzfs/zfs/issues/260#issuecomment-758782144<br />
}}<br />
<br />
ZFS does not allow to use swapfiles, but users can use a ZFS volume (ZVOL) as swap. It is important to set the ZVOL block size to match the system page size, which can be obtained by the {{ic|getconf PAGESIZE}} command (default on x86_64 is 4KiB). Another option useful for keeping the system running well in low-memory situations is not caching the ZVOL data.<br />
<br />
Create a 8 GiB zfs volume:<br />
<br />
# zfs create -V 8G -b $(getconf PAGESIZE) -o compression=zle \<br />
-o logbias=throughput -o sync=always\<br />
-o primarycache=metadata -o secondarycache=none \<br />
-o com.sun:auto-snapshot=false <pool>/swap<br />
<br />
Prepare it as swap partition:<br />
<br />
# mkswap -f /dev/zvol/<pool>/swap<br />
# swapon /dev/zvol/<pool>/swap<br />
<br />
To make it permanent, edit {{ic|/etc/fstab}}. ZVOLs support discard, which can potentially help ZFS's block allocator and reduce fragmentation for all other datasets when/if swap is not full.<br />
<br />
Add a line to {{ic|/etc/fstab}}:<br />
<br />
/dev/zvol/<pool>/swap none swap discard 0 0<br />
<br />
=== Access Control Lists ===<br />
<br />
To use [[ACL]] on a dataset:<br />
<br />
# zfs set acltype=posixacl <nameofzpool>/<nameofdataset><br />
# zfs set xattr=sa <nameofzpool>/<nameofdataset><br />
<br />
Setting {{ic|xattr}} is recommended for performance reasons [https://github.com/openzfs/zfs/issues/170#issuecomment-27348094].<br />
<br />
It may be preferable to enable ACL on the zpool as datasets will inherit the ACL parameters. Setting {{ic|1=aclinherit=passthrough}} may be wanted as the default mode is {{ic|restricted}} [https://docs.oracle.com/cd/E19120-01/open.solaris/817-2271/gbaaz/index.html]; however, it is worth noting that {{ic|aclinherit}} does not affect POSIX ACLs [https://askubuntu.com/questions/342553/activate-acl-for-zfs-pool-ubuntu-13-04#comment1220577_392008]:<br />
<br />
# zfs set aclinherit=passthrough <nameofzpool><br />
# zfs set acltype=posixacl <nameofzpool><br />
# zfs set xattr=sa <nameofzpool><br />
<br />
=== Databases ===<br />
<br />
ZFS, unlike most other file systems, has a variable record size, or what is commonly referred to as a block size. By default, the recordsize on ZFS is 128KiB, which means it will dynamically allocate blocks of any size from 512B to 128KiB depending on the size of file being written. This can often help fragmentation and file access, at the cost that ZFS would have to allocate new 128KiB blocks each time only a few bytes are written to.<br />
<br />
{{Accuracy|At least MariaDB uses a default of 16Kib pages! Check your specific DBMS before setting this value.}}<br />
<br />
Most RDBMSes work in 8KiB-sized blocks by default. Although the block size is tunable for [[MySQL|MySQL/MariaDB]], [[PostgreSQL]], and Oracle database, all three of them use an 8KiB block size ''by default''. For both performance concerns and keeping snapshot differences to a minimum (for backup purposes, this is helpful), it is usually desirable to tune ZFS instead to accommodate the databases, using a command such as:<br />
<br />
# zfs set recordsize=8K <pool>/postgres<br />
<br />
These RDBMSes also tend to implement their own caching algorithm, often similar to ZFS's own ARC. In the interest of saving memory, it is best to simply disable ZFS's caching of the database's file data and let the database do its own job:<br />
<br />
{{Note|[[#L2ARC|L2ARC]] requires {{ic|primarycache}} to function, because it is fed with data evicted from {{ic|primarycache}}. If you intend to use the L2ARC, do not set the option below, otherwise no actual data will be cached on L2ARC.}}<br />
<br />
# zfs set primarycache=metadata <pool>/postgres<br />
<br />
ZFS uses the [[#ZIL|ZIL]] for crash recovery, but databases are often syncing their data files to the file system on their own transaction commits anyway. The end result of this is that ZFS will be committing data '''twice''' to the data disks, and it can severely impact performance. You can tell ZFS to prefer to not use the ZIL, and in which case, data is only committed to the file system once. However, doing so on non-solid state storage (e.g. HDDs) can result in decreased read performance due to fragmentation ([https://openzfs.org/wiki/ZFS_on_high_latency_devices OpenZFS Wiki]) -- with mechanical hard drives, please consider using a dedicated SSD as [[#ZIL|ZIL]] rather than setting the option below. In addition, setting this for non-database file systems, or for pools with configured log devices, can also ''negatively'' impact the performance, so beware:<br />
<br />
# zfs set logbias=throughput <pool>/postgres<br />
<br />
These can also be done at file system creation time, for example:<br />
<br />
# zfs create -o recordsize=8K \<br />
-o primarycache=metadata \<br />
-o mountpoint=/var/lib/postgres \<br />
-o logbias=throughput \<br />
<pool>/postgres<br />
<br />
Please note: these kinds of tuning parameters are ideal for specialized applications like RDBMSes. You can easily ''hurt'' ZFS's performance by setting these on a general-purpose file system such as your /home directory.<br />
<br />
=== /tmp ===<br />
<br />
If you would like to use ZFS to store your /tmp directory, which may be useful for storing arbitrarily-large sets of files or simply keeping your RAM free of idle data, you can generally improve performance of certain applications writing to /tmp by disabling file system sync. This causes ZFS to ignore an application's sync requests (eg, with {{ic|fsync}} or {{ic|O_SYNC}}) and return immediately. While this has severe application-side data consistency consequences (never disable sync for a database!), files in /tmp are less likely to be important and affected. Please note this does ''not'' affect the integrity of ZFS itself, only the possibility that data an application expects on-disk may not have actually been written out following a crash.<br />
<br />
# zfs set sync=disabled <pool>/tmp<br />
<br />
Additionally, for security purposes, you may want to disable '''setuid''' and '''devices''' on the /tmp file system, which prevents some kinds of privilege-escalation attacks or the use of device nodes:<br />
<br />
# zfs set setuid=off <pool>/tmp<br />
# zfs set devices=off <pool>/tmp<br />
<br />
Combining all of these for a create command would be as follows:<br />
<br />
# zfs create -o setuid=off -o devices=off -o sync=disabled -o mountpoint=/tmp <pool>/tmp<br />
<br />
Please note, also, that if you want /tmp on ZFS, you will need to [[mask]] (disable) [[systemd]]'s automatic tmpfs-backed /tmp ({{ic|tmp.mount}}, else ZFS will be unable to mount your dataset at boot-time or import-time.<br />
<br />
=== Transmitting snapshots with ZFS Send and ZFS Recv ===<br />
<br />
It is possible to pipe ZFS snapshots to an arbitrary target by pairing {{ic|zfs send}} and {{ic|zfs recv}}. This is done through standard output, which allows the data to be sent to any file, device, across the network, or manipulated mid-stream by incorporating additional programs in the pipe. <br />
<br />
Below are examples of common scenarios:<br />
<br />
==== Basic ZFS Send ====<br />
<br />
First, let's create a snapshot of some ZFS filesystem:<br />
# zfs snapshot zpool0/archive/books@snap<br />
<br />
Now let's send the snapshot to a new location on a different zpool <br />
# zfs send -v zpool0/archive/books@snap | zfs recv zpool4/library<br />
<br />
The contents of {{ic|zpool0/archive/books@snap}} are now live at {{ic|zpool4/library}}<br />
<br />
{{Tip| See [https://openzfs.github.io/openzfs-docs/man/8/zfs-send.8.html man zfs-send] and [https://openzfs.github.io/openzfs-docs/man/8/zfs-recv.8.html man zfs-recv] for details on flags.}}<br />
<br />
===== To and from files =====<br />
<br />
First, let's create a snapshot of some ZFS filesystem:<br />
<br />
# zfs snapshot zpool0/archive/books@snap<br />
<br />
Write the snapshot to a gzip file:<br />
<br />
# zfs send zpool0/archive/books@snap > /tmp/mybooks.gz<br />
<br />
{{Warning| Make sure to run {{ic|zfs send}} with {{ic|-w}} flag if you wish to preserve encryption during the send.}}<br />
<br />
Now restore the snapshot from the file:<br />
<br />
# gzcat /tmp/mybooks.gz | zfs recv -F zpool0/archive/books<br />
<br />
==== Send over ssh ====<br />
<br />
First, let's create a snapshot of some ZFS filesystem:<br />
<br />
# zfs snapshot zpool1/filestore@snap<br />
<br />
Next we pipe our "send" traffic over an ssh session running "recv":<br />
<br />
# zfs send -v zpool1/filestore@snap | ssh $HOST zfs recv coldstore/backups<br />
<br />
The {{ic|-v}} flag prints information about the datastream being generated. If you are using a passphrase or passkey, you will be prompted to enter it.<br />
<br />
==== Incremental Backups ====<br />
<br />
You may wish update a previously sent ZFS filesystem without retransmitting all of the data over again. <br />
Alternatively, it may be necessary to keep a filesystem online during a lengthy transfer and it is now time to send writes that were made since the initial snapshot.<br />
<br />
First, let's create a snapshot of some ZFS filesystem:<br />
<br />
# zfs snapshot zpool1/filestore@initial<br />
<br />
Next we pipe our "send" traffic over an ssh session running "recv":<br />
<br />
# zfs send -v -R zpool1/filestore@initial | ssh $HOST zfs recv coldstore/backups<br />
<br />
Once changes are written, make another snapshot:<br />
<br />
# zfs snapshot zpool1/filestore@snap2<br />
<br />
The following will send the differences that exist locally between zpool1/filestore@initial and zpool1/filestore@snap2 and create an additional snapshot for the remote filesystem coldstore/backups:<br />
<br />
# zfs send -v -i -R zpool1/filestore@initial | ssh $HOST zfs recv coldstore/backups<br />
<br />
Now both zpool1/filestore and coldstore/backups have the @initial and @snap2 snapshots.<br />
<br />
On the remote host, you may now promote the latest snapshot to become the active filesystem:<br />
# rollback coldstore/backups@snap2<br />
<br />
== Tuning ==<br />
<br />
=== General ===<br />
<br />
ZFS pools and datasets can be further adjusted using parameters.<br />
<br />
{{Note|All settable properties, with the exception of quotas and reservations, inherit their value from the parent dataset.}}<br />
<br />
To retrieve the current pool parameter status:<br />
<br />
# zfs get all <pool><br />
<br />
To retrieve the current dataset parameter status:<br />
<br />
# zfs get all <pool>/<dataset><br />
<br />
To disable access time (atime), which is enabled by default:<br />
<br />
# zfs set atime=off <pool><br />
<br />
To disable access time (atime) on a particular dataset:<br />
<br />
# zfs set atime=off <pool>/<dataset><br />
<br />
An alternative to turning off atime completely, {{ic|relatime}} is available. This brings the default ext4/XFS atime semantics to ZFS, where access time is only updated if the modified time or changed time changes, or if the existing access time has not been updated within the past 24 hours. It is a compromise between {{ic|1=atime=off}} and {{ic|1=atime=on}}. This property ''only'' takes effect if {{ic|atime}} is {{ic|on}}:<br />
<br />
# zfs set atime=on <pool><br />
# zfs set relatime=on <pool><br />
<br />
Compression is just that, transparent compression of data. ZFS supports a few different algorithms, presently lz4 is the default, ''gzip'' is also available for seldom-written yet highly-compressible data; consult the [https://openzfs.github.io/openzfs-docs/Performance%20and%20Tuning/Workload%20Tuning.html OpenZFS Wiki] for more details.<br />
<br />
To enable compression:<br />
<br />
# zfs set compression=on <pool><br />
<br />
To reset a property of a pool and/or dataset to its default state, use {{ic|zfs inherit}}:<br />
<br />
# zfs inherit -rS atime <pool><br />
# zfs inherit -rS atime <pool>/<dataset><br />
<br />
{{Warning|Using the {{ic|-r}} flag will recursively reset all datasets of the zpool.}}<br />
<br />
=== Scrubbing ===<br />
<br />
Whenever data is read and ZFS encounters an error, it is silently repaired when possible, rewritten back to disk and logged so you can obtain an overview of errors on your pools. There is no fsck or equivalent tool for ZFS. Instead, ZFS supports a feature known as scrubbing. This traverses through all the data in a pool and verifies that all blocks can be read.<br />
<br />
To scrub a pool:<br />
<br />
# zpool scrub <pool><br />
<br />
To cancel a running scrub:<br />
<br />
# zpool scrub -s <pool><br />
<br />
==== How often should I do this? ====<br />
<br />
From the Oracle blog post [https://blogs.oracle.com/wonders-of-zfs-storage/disk-scrub-why-and-when-v2 Disk Scrub - Why and When?]:<br />
<br />
:This question is challenging for Support to answer, because as always the true answer is "It Depends". So before I offer a general guideline, here are a few tips to help you create an answer more tailored to your use pattern.<br />
<br />
:* What is the expiration of your oldest backup? You should probably scrub your data at least as often as your oldest tapes expire so that you have a known-good restore point.<br />
:* How often are you experiencing disk failures? While the recruitment of a hot-spare disk invokes a "resilver" -- a targeted scrub of just the VDEV which lost a disk -- you should probably scrub at least as often as you experience disk failures on average in your specific environment.<br />
:* How often is the oldest piece of data on your disk read? You should scrub occasionally to prevent very old, very stale data from experiencing bit-rot and dying without you knowing it.<br />
<br />
:If any of your answers to the above are "I do not know", the general guideline is: you should probably be scrubbing your zpool at least once per month. It is a schedule that works well for most use cases, provides enough time for scrubs to complete before starting up again on all but the busiest & most heavily-loaded systems, and even on very large zpools (192+ disks) should complete fairly often between disk failures.<br />
<br />
In the [https://pthree.org/2012/12/11/zfs-administration-part-vi-scrub-and-resilver/ ZFS Administration Guide] by Aaron Toponce, he advises to scrub consumer disks once a week.<br />
<br />
==== Start with a service or timer ====<br />
<br />
{{Note|Starting with OpenZFS 2.1.3 weekly and monthly [[systemd]] timers/services are included. To use these [[enable]]/[[start]] {{ic|zfs-scrub-weekly@''pool-to-scrub''.timer}} or {{ic|zfs-scrub-monthly@''pool-to-scrub''.timer}} for the desired pool.}}<br />
<br />
Using a [[systemd]] timer/service it is possible to automatically scrub pools.<br />
<br />
To perform scrubbing monthly on a particular pool:<br />
<br />
{{hc|/etc/systemd/system/zfs-scrub@.timer|2=<br />
[Unit]<br />
Description=Monthly zpool scrub on %i<br />
<br />
[Timer]<br />
OnCalendar=monthly<br />
AccuracySec=1h<br />
Persistent=true<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/zfs-scrub@.service|2=<br />
[Unit]<br />
Description=zpool scrub on %i<br />
<br />
[Service]<br />
Nice=19<br />
IOSchedulingClass=idle<br />
KillSignal=SIGINT<br />
ExecStart=/usr/bin/zpool scrub %i<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
[[Enable]]/[[start]] {{ic|zfs-scrub@''pool-to-scrub''.timer}} unit for monthly scrubbing the specified zpool.<br />
<br />
=== Enabling TRIM ===<br />
<br />
To quickly query your vdevs [[TRIM]] support, you can include trimming information in {{Ic|zpool status}} with {{Ic|-t}}. <br />
<br />
{{hc|$ zpool status -t tank|2=<br />
pool: tank<br />
state: ONLINE<br />
scan: none requested<br />
config:<br />
<br />
NAME STATE READ WRITE CKSUM<br />
tank ONLINE 0 0 0<br />
ata-ST31000524AS_5RP4SSNR-part1 ONLINE 0 0 0 (trim unsupported)<br />
ata-CT480BX500SSD1_2134A59B933D-part1 ONLINE 0 0 0 (untrimmed)<br />
<br />
errors: No known data errors<br />
}}<br />
<br />
ZFS is capable of trimming supported vdevs either on-demand or periodically via the {{Ic|autotrim}} property.<br />
<br />
Manually performing a TRIM operation on a zpool:<br />
<br />
# zpool trim <zpool><br />
<br />
Enabling periodic trimming on all supported vdevs in a pool:<br />
<br />
# zpool set autotrim=on <zpool><br />
<br />
{{Note|Because of how the automatic TRIM and a full {{Ic|zpool trim}} differ in their operation, [https://github.com/openzfs/zfs/commit/1b939560be5c51deecf875af9dada9d094633bf7 it can make sense to run a manual trim occasionally.] }}<br />
<br />
To perform a full {{Ic|zpool trim}} monthly on a particular pool using a [[systemd]] timer/service:<br />
<br />
{{hc|/etc/systemd/system/zfs-trim@.timer|2=<br />
[Unit]<br />
Description=Monthly zpool trim on %i<br />
<br />
[Timer]<br />
OnCalendar=monthly<br />
AccuracySec=1h<br />
Persistent=true<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/zfs-trim@.service|2=<br />
[Unit]<br />
Description=zpool trim on %i<br />
Documentation=man:zpool-trim(8)<br />
Requires=zfs.target<br />
After=zfs.target<br />
ConditionACPower=true<br />
ConditionPathIsDirectory=/sys/module/zfs<br />
<br />
[Service]<br />
Nice=19<br />
IOSchedulingClass=idle<br />
KillSignal=SIGINT<br />
ExecStart=/bin/sh -c '\<br />
if /usr/bin/zpool status %i {{!}} grep "trimming"; then\<br />
exec /usr/bin/zpool wait -t trim %i;\<br />
else exec /usr/bin/zpool trim -w %i; fi'<br />
ExecStop=-/bin/sh -c '/usr/bin/zpool trim -s %i 2>/dev/null {{!}}{{!}} true'<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
[[Enable]]/[[start]] {{ic|zfs-trim@''pool-to-trim''.timer}} unit for monthly trimming of the specified zpool.<br />
<br />
=== SSD Caching ===<br />
<br />
If your pool has no configured log devices, ZFS reserves space on the pool's data disks for its intent log (the ZIL, also called SLOG). If your data disks are slow (e.g. HDD) it is highly recommended to configure the ZIL on solid state drives for better write performance and also to consider a layer 2 adaptive replacement cache (L2ARC). The process to add them is very similar to adding a new VDEV.<br />
<br />
All of the below references to device-id are the IDs from {{ic|/dev/disk/by-id/*}}.<br />
<br />
==== ZIL ====<br />
<br />
To add a mirrored ZIL:<br />
<br />
# zpool add <pool> log mirror <device-id-1> <device-id-2><br />
<br />
Or to add a single device ZIL (unsafe):<br />
<br />
# zpool add <pool> log <device-id><br />
<br />
Because the ZIL device stores data that has not been written to the pool, it is important to use devices that can finish writes when power is lost. It is also important to use redundancy, since a device failure can cause data loss. In addition, the ZIL is only used for sync writes, so may not provide any performance improvement when your data drives are as fast as your ZIL drive(s).<br />
<br />
==== L2ARC ====<br />
To add L2ARC:<br />
# zpool add <pool> cache <device-id><br />
L2ARC is only a read cache, so redundancy is unnecessary. Since [https://github.com/openzfs/zfs/releases/tag/zfs-2.0.0 ZFS version 2.0.0], L2ARC is persisted across reboots.[https://github.com/openzfs/zfs/pull/9582]<br />
<br />
L2ARC is generally only useful in workloads where the amount of hot data is '''bigger''' than system memory, but small enough to fit into L2ARC. The L2ARC is indexed by the ARC in system memory, consuming 70 bytes per record (default 128KiB). Thus, the equation for RAM usage is:<br />
(L2ARC size) / (recordsize) * 70 bytes<br />
Because of this, L2ARC can, in certain workloads, harm performance as it takes memory away from ARC.<br />
<br />
=== ZVOLs ===<br />
<br />
ZFS volumes (ZVOLs) can suffer from the same block size-related issues as RDBMSes, but it is worth noting that the default recordsize for ZVOLs is 8 KiB already. If possible, it is best to align any partitions contained in a ZVOL to your recordsize (current versions of fdisk and gdisk by default automatically align at 1MiB segments, which works), and file system block sizes to the same size. Other than this, you might tweak the '''recordsize''' to accommodate the data inside the ZVOL as necessary (though 8 KiB tends to be a good value for most file systems, even when using 4 KiB blocks on that level).<br />
<br />
==== RAIDZ and Advanced Format physical disks ====<br />
<br />
Each block of a ZVOL gets its own parity disks, and if you have physical media with logical block sizes of 4096B, 8192B, or so on, the parity needs to be stored in whole physical blocks, and this can drastically increase the space requirements of a ZVOL, requiring 2× or more physical storage capacity than the ZVOL's logical capacity. Setting the '''recordsize''' to 16k or 32k can help reduce this footprint drastically.<br />
<br />
See [https://github.com/openzfs/zfs/issues/1807 OpenZFS issue #1807] for details.<br />
<br />
=== I/O Scheduler ===<br />
<br />
While ZFS is expected to work well with modern schedulers including, {{ic|mq-deadline}}, and {{ic|none}}, experimenting with [[Improving performance#Changing I/O scheduler|manually setting]] the I/O scheduler on ZFS disks may yield performance gains. The ZFS recomendation is "[...] users leave the default scheduler [https://github.com/openzfs/zfs/issues/9778#issuecomment-569347505 “unless you’re encountering a specific problem, or have clearly measured a performance improvement for your workload”]"[https://openzfs.github.io/openzfs-docs/Performance%20and%20Tuning/Module%20Parameters.html#zfs-vdev-scheduler]<br />
<br />
== Troubleshooting ==<br />
<br />
=== Creating a zpool fails ===<br />
<br />
If the following error occurs then it can be fixed.<br />
<br />
# the kernel failed to rescan the partition table: 16<br />
# cannot label 'sdc': try using parted(8) and then provide a specific slice: -1<br />
<br />
One reason this can occur is because ZFS expects pool creation to take less than 1 second[https://github.com/openzfs/zfs/issues/2582][https://github.com/openzfs/zfs/issues/1646]. This is a reasonable assumption under ordinary conditions, but in many situations it may take longer. Each drive will need to be cleared again before another attempt can be made.<br />
<br />
# parted /dev/sda rm 1<br />
# parted /dev/sda rm 1<br />
# dd if=/dev/zero of=/dev/sdb bs=512 count=1<br />
# zpool labelclear /dev/sda<br />
<br />
A brute force creation can be attempted over and over again, and with some luck the ZPool creation will take less than 1 second.<br />
One cause for creation slowdown can be slow burst read writes on a drive. By reading from the disk in parallell to ZPool creation, it may be possible to increase burst speeds.<br />
<br />
# dd if=/dev/sda of=/dev/null<br />
<br />
This can be done with multiple drives by saving the above command for each drive to a file on separate lines and running <br />
<br />
# cat $FILE | parallel<br />
<br />
Then run ZPool creation at the same time.<br />
<br />
=== ZFS is using too much RAM ===<br />
<br />
By default, ZFS caches file operations ([[wikipedia:Adaptive replacement cache|ARC]]) using up to two-thirds of available system memory on the host. To adjust the ARC size, add the following to the [[Kernel parameters]] list:<br />
<br />
zfs.zfs_arc_max=536870912 # (for 512MiB)<br />
<br />
In case that the default value of {{ic|zfs_arc_min}} (1/32 of system memory) is higher than the specified {{ic|zfs_arc_max}} it is needed to add also the following to the [[Kernel parameters]] list:<br />
<br />
zfs.zfs_arc_min=268435456 # (for 256MiB, needs to be lower than zfs.zfs_arc_max)<br />
<br />
For a more detailed description, as well as other configuration options, see [[Gentoo:ZFS#ARC]].<br />
<br />
=== Does not contain an EFI label ===<br />
<br />
The following error will occur when attempting to create a zfs filesystem,<br />
<br />
/dev/disk/by-id/<id> does not contain an EFI label but it may contain partition<br />
<br />
The way to overcome this is to use {{ic|-f}} with the zfs create command.<br />
<br />
=== No hostid found ===<br />
<br />
An error that occurs at boot with the following lines appearing before initscript output:<br />
<br />
ZFS: No hostid found on kernel command line or /etc/hostid.<br />
<br />
This warning occurs because the ZFS module does not have access to the spl hosted. There are two solutions, for this. Either place the spl hostid in the [[kernel parameters]] in the boot loader. For example, adding {{ic|1=spl.spl_hostid=0x00bab10c}}.<br />
<br />
The other solution is to make sure that there is a hostid in {{ic|/etc/hostid}}, and then [[regenerate the initramfs]] image. Which will copy the hostid into the initramfs image.<br />
<br />
=== Pool cannot be found while booting from SAS/SCSI devices ===<br />
<br />
In case you are booting a SAS/SCSI based, you might occassionally get boot problems where the pool you are trying to boot from cannot be found. A likely reason for this is that your devices are initialized too late into the process. That means that zfs cannot find any devices at the time when it tries to assemble your pool.<br />
<br />
In this case you should force the scsi driver to wait for devices to come online before continuing. You can do this by putting this into {{ic|/etc/modprobe.d/zfs.conf}}:<br />
<br />
{{hc|1=/etc/modprobe.d/zfs.conf|2=<br />
options scsi_mod scan=sync<br />
}}<br />
<br />
Afterwards, [[regenerate the initramfs]].<br />
<br />
This works because the zfs hook will copy the file at {{ic|/etc/modprobe.d/zfs.conf}} into the initcpio which will then be used at build time.<br />
<br />
=== On boot the zfs pool does not mount stating: "pool may be in use from other system" ===<br />
<br />
==== Unexported pool ====<br />
<br />
If the new installation does not boot because the zpool cannot be imported, chroot into the installation and properly export the zpool. See [[#Emergency chroot repair with archzfs]].<br />
<br />
Once inside the chroot environment, load the ZFS module and force import the zpool,<br />
<br />
# zpool import -a -f<br />
<br />
now export the pool:<br />
<br />
# zpool export <pool><br />
<br />
To see the available pools, use,<br />
<br />
# zpool status<br />
<br />
It is necessary to export a pool because of the way ZFS uses the hostid to track the system the zpool was created on. The hostid is generated partly based on the network setup. During the installation in the archiso the network configuration could be different generating a different hostid than the one contained in the new installation. Once the zfs filesystem is exported and then re-imported in the new installation, the hostid is reset. See [https://web.archive.org/web/20151101094022/http://osdir.com/ml/zfs-discuss/2011-06/msg00227.html Re: Howto zpool import/export automatically? - msg#00227].<br />
<br />
If ZFS complains about "pool may be in use" after every reboot, properly export pool as described above, and then [[regenerate the initramfs]] in normally booted system.<br />
<br />
==== Incorrect hostid ====<br />
<br />
Double check that the pool is properly exported. Exporting the zpool clears the hostid marking the ownership. So during the first boot the zpool should mount correctly. If it does not there is some other problem.<br />
<br />
Reboot again, if the zfs pool refuses to mount it means the hostid is not yet correctly set in the early boot phase and it confuses zfs. Manually tell zfs the correct number, once the hostid is coherent across the reboots the zpool will mount correctly.<br />
<br />
Boot using zfs_force and write down the hostid. This one is just an example.<br />
<br />
{{hc|$ hostid|<br />
0a0af0f8<br />
}}<br />
<br />
This number have to be added to the [[kernel parameters]] as {{ic|1=spl.spl_hostid=0x0a0af0f8}}. Another solution is writing the hostid inside the initram image, see the [[Install Arch Linux on ZFS#Configure systemd ZFS mounts|installation guide]] explanation about this.<br />
<br />
Users can always ignore the check adding {{ic|1=zfs_force=1}} in the [[kernel parameters]], but it is not advisable as a permanent solution.<br />
<br />
=== Devices have different sector alignment ===<br />
<br />
Once a drive has become faulted it should be replaced A.S.A.P. with an identical drive.<br />
<br />
# zpool replace bigdata ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-1CH166_W1F478BD -f<br />
<br />
but in this instance, the following error is produced:<br />
<br />
cannot replace ata-ST3000DM001-9YN166_S1F0KDGY with ata-ST3000DM001-1CH166_W1F478BD: devices have different sector alignment<br />
<br />
ZFS uses the ashift option to adjust for physical block size. When replacing the faulted disk, ZFS is attempting to use {{ic|<nowiki>ashift=12</nowiki>}}, but the faulted disk is using a different ashift (probably {{ic|<nowiki>ashift=9</nowiki>}}) and this causes the resulting error. <br />
<br />
For Advanced Format Disks with 4KB blocksize, an ashift of 12 is recommended for best performance. See [https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html#performance-considerations OpenZFS FAQ: Performance Considerations] and [https://web.archive.org/web/20170913063528/https://wiki.illumos.org/display/illumos/ZFS+and+Advanced+Format+disks ZFS and Advanced Format disks].<br />
<br />
Use zdb to find the ashift of the zpool: {{ic|zdb | grep ashift}}, then use the {{ic|-o}} argument to set the ashift of the replacement drive:<br />
<br />
# zpool replace bigdata ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-1CH166_W1F478BD -o ashift=9 -f<br />
<br />
Check the zpool status for confirmation:<br />
<br />
{{hc|# zpool status -v|<br />
pool: bigdata<br />
state: DEGRADED<br />
status: One or more devices is currently being resilvered. The pool will<br />
continue to function, possibly in a degraded state.<br />
action: Wait for the resilver to complete.<br />
scan: resilver in progress since Mon Jun 16 11:16:28 2014<br />
10.3G scanned out of 5.90T at 81.7M/s, 20h59m to go<br />
2.57G resilvered, 0.17% done<br />
config:<br />
<br />
NAME STATE READ WRITE CKSUM<br />
bigdata DEGRADED 0 0 0<br />
raidz1-0 DEGRADED 0 0 0<br />
replacing-0 OFFLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KDGY OFFLINE 0 0 0<br />
ata-ST3000DM001-1CH166_W1F478BD ONLINE 0 0 0 (resilvering)<br />
ata-ST3000DM001-9YN166_S1F0JKRR ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KBP8 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JTM1 ONLINE 0 0 0<br />
<br />
errors: No known data errors<br />
}}<br />
<br />
=== Pool resilvering stuck/restarting/slow? ===<br />
<br />
According to the ZFSonLinux github it is a known issue since 2012 with ZFS-ZED which causes the resilvering process to constantly restart, sometimes get stuck and be generally slow for some hardware. The simplest mitigation is to stop zfs-zed.service until the resilver completes.<br />
<br />
=== Fix slow boot caused by failed import of unavailable pools in the initramfs zpool.cache ===<br />
<br />
Your boot time can be significantly impacted if you update your intitramfs (eg when doing a kernel update) when you have additional but non-permanently attached pools imported because these pools will get added to your initramfs zpool.cache and ZFS will attempt to import these extra pools on every boot, regardless of whether you have exported it and removed it from your regular zpool.cache.<br />
<br />
If you notice ZFS trying to import unavailable pools at boot, first run:<br />
<br />
$ zdb -C<br />
<br />
To check your zpool.cache for pools you do not want imported at boot. If this command is showing (a) additional, currently unavailable pool(s), run:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache zroot<br />
<br />
To clear the zpool.cache of any pools other than the pool named zroot. Sometimes there is no need to refresh your zpool.cache, but instead all you need to do is [[regenerate the initramfs]].<br />
<br />
=== ZFS Command History ===<br />
<br />
ZFS logs changes to a pool's structure natively as a log of executed commands in a ring buffer (which cannot be turned off).<br />
The log may be helpful when restoring a degraded or failed pool.<br />
<br />
{{hc|# zpool history zpool|<nowiki><br />
History for 'zpool':<br />
2023-02-19.16:28:44 zpool create zpool raidz1 /scratch/disk_1.img /scratch/disk_2.img /scratch/disk_3.img<br />
2023-02-19.16:31:29 zfs set compression=lz4 zpool<br />
2023-02-19.16:41:45 zpool scrub zpool<br />
2023-02-19.17:00:57 zpool replace zpool /scratch/disk_1.img /scratch/bigger_disk_1.img<br />
2023-02-19.17:01:34 zpool scrub zpool<br />
2023-02-19.17:01:42 zpool replace zpool /scratch/disk_2.img /scratch/bigger_disk_2.img<br />
2023-02-19.17:01:46 zpool replace zpool /scratch/disk_3.img /scratch/bigger_disk_3.img<br />
</nowiki>}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Create an Archiso image with ZFS support ===<br />
<br />
Follow the [[Archiso]] steps for creating a fully functional Arch Linux live CD/DVD/USB image. To include ZFS support in the image, you can either build your choice of PKGBUILDs from the AUR or include prebuilt packages from one of the [[unofficial user repositories]].<br />
<br />
==== Using self-built ZFS packages from the AUR ====<br />
<br />
Build the ZFS packages you want by following the [[Arch User Repository#Build the package|normal procedures]]. If you are unsure, {{aur|zfs-dkms}} and {{aur|zfs-utils}} are likely to be compatible with the widest range of other modifications to the Archiso image you may wish to perform. Proceed to set up [[Pacman/Tips and tricks#Custom local repository|a custom local repository]]. [[Archiso#Custom local repository|Include the resulting repository]] in the Pacman configuration of your new profile.<br />
<br />
Include the built packages in the list of packages to be installed. The example below presumes you want to include only the {{aur|zfs-dkms}} and {{aur|zfs-utils}} packages.<br />
<br />
{{hc|packages.x86_64|<br />
...<br />
zfs-dkms<br />
zfs-utils<br />
}}<br />
<br />
If you include any [[DKMS]] packages, make sure you also include headers for any kernels you are including in the ISO ({{pkg|linux-headers}} for the default kernel).<br />
<br />
==== Using the archzfs unofficial user repository ====<br />
<br />
Add the [[Unofficial user repositories#archzfs|archzfs]] unofficial user repository to {{ic|pacman.conf}} in your new Archiso profile.<br />
<br />
Add the {{ic|archzfs-linux}} group to the list of packages to be installed (the {{ic|archzfs}} repository provides packages for the x86_64 architecture only).<br />
<br />
{{hc|packages.x86_64|<br />
...<br />
archzfs-linux<br />
}}<br />
<br />
{{Note|If you later have problems running modprobe zfs, you should include the linux-headers in the packages.x86_64. }}<br />
<br />
==== Finishing up ====<br />
<br />
Regardless of where you source your ZFS packages from, you should finish by [[Archiso#Build the ISO|building the ISO]].<br />
<br />
=== Automatic snapshots ===<br />
<br />
==== zrepl ====<br />
<br />
The {{AUR|zrepl}} package provides a ZFS automatic replication service, which could also be used as a snapshotting service much like [[snapper]].<br />
<br />
For details on how to configure the zrepl daemon, see the zrepl [https://zrepl.github.io/ documentation]. The configuration file should be located at {{ic|/etc/zrepl/zrepl.yml}}. Then, run {{ic|zrepl configcheck}} to make sure that the syntax of the config file is correct. Finally, enable {{ic|zrepl.service}}.<br />
<br />
==== sanoid ====<br />
<br />
{{AUR|sanoid}} is a policy-driven tool for taking snapshots. Sanoid also includes {{ic|syncoid}}, which is for replicating snapshots. It comes with systemd services and a timer.<br />
<br />
Sanoid only prunes snapshots on the local system. To prune snapshots on the remote system, run sanoid there as well with prune options. Either use the {{ic|--prune-snapshots}} command line option or use the {{ic|--cron}} command line option together with the {{ic|1=autoprune = yes}} and {{ic|1=autosnap = no}} configuration options.<br />
<br />
==== ZFS Automatic Snapshot Service for Linux ====<br />
<br />
{{Note| {{AUR|zfs-auto-snapshot-git}} has not seen any updates since 2019, and the functionality is extremely limited. You are advised to switch to a newer tool like {{AUR|zrepl}}. }}<br />
<br />
The {{AUR|zfs-auto-snapshot-git}} package provides a shell script to automate the management of snapshots, with each named by date and label (hourly, daily, etc), giving quick and convenient snapshotting of all ZFS datasets. The package also installs cron tasks for quarter-hourly, hourly, daily, weekly, and monthly snapshots. Optionally adjust the {{ic|--keep parameter}} from the defaults depending on how far back the snapshots are to go (the monthly script by default keeps data for up to a year).<br />
<br />
To prevent a dataset from being snapshotted at all, set {{ic|1=com.sun:auto-snapshot=false}} on it. Likewise, set more fine-grained control as well by label, if, for example, no monthlies are to be kept on a snapshot, for example, set {{ic|1=com.sun:auto-snapshot:monthly=false}}.<br />
<br />
{{Note|zfs-auto-snapshot-git will not create snapshots during [[#Scrubbing|scrubbing]]. It is possible to override this by [[Systemd#Editing provided units|editing provided systemd unit]] and removing {{ic|--skip-scrub}} from {{ic|ExecStart}} line. Consequences not known, someone please edit.}}<br />
<br />
Once the package has been installed, [[systemd/Timers|enable and start the selected timers]] ({{ic|<nowiki>zfs-auto-snapshot-{frequent,daily,weekly,monthly}.timer</nowiki>}}).<br />
<br />
=== Creating a share ===<br />
<br />
ZFS has support for creating shares by [[NFS]] or [[SMB]].<br />
<br />
==== NFS ====<br />
<br />
Make sure [[NFS]] has been installed/configured, note there is no need to edit the {{ic|/etc/exports}} file. For sharing over NFS the services {{ic|nfs-server.service}} and {{ic|zfs-share.service}} should be [[start|started]].<br />
<br />
To make a pool available on the network:<br />
<br />
# zfs set sharenfs=on ''nameofzpool''<br />
<br />
To make a dataset available on the network:<br />
<br />
# zfs set sharenfs=on ''nameofzpool''/''nameofdataset''<br />
<br />
To enable read/write access for a specific ip-range(s):<br />
<br />
# zfs set sharenfs="rw=@192.168.1.100/24,rw=@10.0.0.0/24" ''nameofzpool''/''nameofdataset''<br />
<br />
To check if the dataset is exported successfully:<br />
<br />
{{hc|# showmount -e `hostname`|<br />
Export list for hostname:<br />
/path/of/dataset 192.168.1.100/24<br />
}}<br />
<br />
To view the current loaded exports state in more detail, use:<br />
<br />
{{hc|# exportfs -v|2=<br />
''/path/of/dataset''<br />
192.168.1.100/24(sync,wdelay,hide,no_subtree_check,mountpoint,sec=sys,rw,secure,no_root_squash,no_all_squash)<br />
}}<br />
<br />
To view the current NFS share list by ZFS:<br />
<br />
# zfs get sharenfs<br />
<br />
==== SMB ====<br />
<br />
When sharing through SMB, using {{ic|usershares}} in {{ic|/etc/samba/smb.conf}} will allow ZFS to setup and create the shares. See [[Samba#Enable Usershares]] for details.<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
usershare path = /var/lib/samba/usershares<br />
usershare max shares = 100<br />
usershare allow guests = yes<br />
usershare owner only = no<br />
}}<br />
<br />
Create and set permissions on the user directory as root<br />
<br />
# mkdir /var/lib/samba/usershares<br />
# chmod +t /var/lib/samba/usershares<br />
<br />
To make a pool available on the network:<br />
<br />
# zfs set sharesmb=on ''nameofzpool''<br />
<br />
To make a dataset available on the network:<br />
<br />
# zfs set sharesmb=on ''nameofzpool''/''nameofdataset''<br />
<br />
To check if the dataset is exported successfully:<br />
<br />
{{hc|# smbclient -L localhost -U%|<br />
Sharename Type Comment<br />
--------- ---- -------<br />
IPC$ IPC IPC Service (SMB Server Name)<br />
''nameofzpool''_''nameofdataset'' Disk Comment: path/of/dataset<br />
SMB1 disabled -- no workgroup available<br />
}}<br />
<br />
To view the current SMB share list by ZFS:<br />
<br />
# zfs get sharesmb<br />
<br />
=== Encryption in ZFS using dm-crypt ===<br />
<br />
Before [https://github.com/openzfs/zfs/releases/tag/zfs-0.8.0 OpenZFS version 0.8.0], ZFS did not support encryption directly (See [[#Native encryption]]). Instead, zpools can be created on [[dm-crypt]] block devices. Since the zpool is created on the plain-text abstraction, it is possible to have the data encrypted while having all the advantages of ZFS like deduplication, compression, and data robustness. Furthermore, utilizing dm-crypt will encrypt the zpools metadata, which the native encryption can inherently not provide.[https://openzfs.github.io/openzfs-docs/man/8/zfs-change-key.8.html#Encryption]<br />
<br />
dm-crypt, possibly via LUKS, creates devices in {{ic|/dev/mapper}} and their name is fixed. So you just need to change {{ic|zpool create}} commands to point to that names. The idea is configuring the system to create the {{ic|/dev/mapper}} block devices and import the zpools from there. Since zpools can be created in multiple devices (raid, mirroring, striping, ...), it is important all the devices are encrypted otherwise the protection might be partially lost.<br />
<br />
For example, an encrypted zpool can be created using plain dm-crypt (without LUKS) with:<br />
<br />
# cryptsetup --hash=sha512 --cipher=twofish-xts-plain64 --offset=0 \<br />
--key-file=/dev/sdZ --key-size=512 open --type=plain /dev/sdX enc<br />
# zpool create zroot /dev/mapper/enc<br />
<br />
In the case of a root filesystem pool, the {{ic|mkinitcpio.conf}} HOOKS line will enable the keyboard for the password, create the devices, and load the pools. It will contain something like:<br />
<br />
HOOKS="... keyboard encrypt zfs ..."<br />
<br />
Since the {{ic|/dev/mapper/enc}} name is fixed no import errors will occur.<br />
<br />
Creating encrypted zpools works fine. But if you need encrypted directories, for example to protect your users' homes, ZFS loses some functionality.<br />
<br />
ZFS will see the encrypted data, not the plain-text abstraction, so compression and deduplication will not work. The reason is that encrypted data has always high entropy making compression ineffective and even from the same input you get different output (thanks to salting) making deduplication impossible. To reduce the unnecessary overhead it is possible to create a sub-filesystem for each encrypted directory and use [[eCryptfs]] on it.<br />
<br />
For example to have an encrypted home: (the two passwords, encryption and login, must be the same)<br />
<br />
# zfs create -o compression=off -o dedup=off -o mountpoint=/home/<username> <zpool>/<username><br />
# useradd -m <username><br />
# passwd <username><br />
# ecryptfs-migrate-home -u <username><br />
<log in user and complete the procedure with ecryptfs-unwrap-passphrase><br />
<br />
=== Emergency chroot repair with archzfs ===<br />
<br />
To get into the ZFS filesystem from live system for maintenance, there are two options:<br />
<br />
# Build custom archiso with ZFS as described in [[#Create an Archiso image with ZFS support]].<br />
# Boot the latest official archiso and bring up the network. Then enable [[Unofficial user repositories#archzfs|archzfs]] repository inside the live system as usual, sync the pacman package database and install the ''archzfs-archiso-linux'' package.<br />
<br />
To start the recovery, load the ZFS kernel modules:<br />
<br />
# modprobe zfs<br />
<br />
Import the pool:<br />
<br />
# zpool import -a -R /mnt<br />
<br />
Mount the boot partition and EFI system partition (if any):<br />
<br />
# mount /dev/sda2 /mnt/boot<br />
# mount /dev/sda1 /mnt/efi<br />
<br />
Chroot into the ZFS filesystem:<br />
<br />
# arch-chroot /mnt /bin/bash<br />
<br />
Check the kernel version:<br />
<br />
# pacman -Qi linux<br />
# uname -r<br />
<br />
uname will show the kernel version of the archiso. If they are different, run depmod (in the chroot) with the correct kernel version of the chroot installation:<br />
<br />
# depmod -a 3.6.9-1-ARCH (version gathered from pacman -Qi linux but using the matching kernel modules directory name under the chroot's /lib/modules)<br />
<br />
This will load the correct kernel modules for the kernel version installed in the chroot installation.<br />
<br />
[[Regenerate the initramfs]]. There should be no errors.<br />
<br />
=== Bind mount ===<br />
<br />
Here a bind mount from /mnt/zfspool to /srv/nfs4/music is created. The configuration ensures that the zfs pool is ready before the bind mount is created.<br />
<br />
==== fstab ====<br />
<br />
See {{man|5|systemd.mount}} for more information on how systemd converts fstab into mount unit files with {{man|8|systemd-fstab-generator}}.<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
/mnt/zfspool /srv/nfs4/music none bind,defaults,nofail,x-systemd.requires=zfs-mount.service 0 0<br />
</nowiki>}}<br />
<br />
=== Monitoring / Mailing on Events ===<br />
<br />
See [https://ramsdenj.com/2016/08/29/arch-linux-on-zfs-part-3-followup.html ZED: The ZFS Event Daemon] for more information.<br />
<br />
An email forwarder, such as [[S-nail]], is required to accomplish this. Test it to be sure it is working correctly.<br />
<br />
Uncomment the following in the configuration file:<br />
<br />
{{hc|/etc/zfs/zed.d/zed.rc|<nowiki><br />
ZED_EMAIL_ADDR="root"<br />
ZED_EMAIL_PROG="mailx"<br />
ZED_NOTIFY_VERBOSE=0<br />
ZED_EMAIL_OPTS="-s '@SUBJECT@' @ADDRESS@"<br />
</nowiki>}}<br />
<br />
Update 'root' in {{ic|1=ZED_EMAIL_ADDR="root"}} to the email address you want to receive notifications at.<br />
<br />
If you are keeping your mailrc in your home directory, you can tell mail to get it from there by setting {{ic|MAILRC}}:<br />
<br />
{{hc|/etc/zfs/zed.d/zed.rc|2=<br />
export MAILRC=/home/<user>/.mailrc<br />
}}<br />
<br />
This works because ZED sources this file, so {{ic|mailx}} sees this environment variable.<br />
<br />
If you want to receive an email no matter the state of your pool, you will want to set {{ic|1=ZED_NOTIFY_VERBOSE=1}}. You will need to do this temporary to test.<br />
<br />
[[Start]] and [[enable]] {{ic|zfs-zed.service}}.<br />
<br />
With {{ic|1=ZED_NOTIFY_VERBOSE=1}}, you can test by running a scrub as root: {{ic|1=zpool scrub <pool-name>}}.<br />
<br />
=== Wrap shell commands in pre & post snapshots ===<br />
<br />
Since it is so cheap to make a snapshot, we can use this as a measure of security for sensitive commands such as system and package upgrades. If we make a snapshot before, and one after, we can later diff these snapshots to find out what changed on the filesystem after the command executed. Furthermore we can also rollback in case the outcome was not desired.<br />
<br />
==== znp ====<br />
<br />
E.g.:<br />
<br />
# zfs snapshot -r zroot@pre<br />
# pacman -Syu<br />
# zfs snapshot -r zroot@post<br />
# zfs diff zroot@pre zroot@post <br />
# zfs rollback zroot@pre<br />
<br />
A utility that automates the creation of pre and post snapshots around a shell command is [https://gist.github.com/erikw/eeec35be33e847c211acd886ffb145d5 znp].<br />
<br />
E.g.:<br />
<br />
# znp pacman -Syu<br />
# znp find / -name "something*" -delete<br />
<br />
and you would get snapshots created before and after the supplied command, and also output of the commands logged to file for future reference so we know what command created the diff seen in a pair of pre/post snapshots.<br />
<br />
=== Remote unlocking of ZFS encrypted root ===<br />
<br />
As of [https://github.com/archzfs/archzfs/pull/261 PR #261], {{ic|archzfs}} supports SSH unlocking of natively-encrypted ZFS datasets. This section describes how to use this feature, and is largely based on [[dm-crypt/Specialties#Busybox based initramfs (built with mkinitcpio)]].<br />
<br />
# Install {{Pkg|mkinitcpio-netconf}} to provide hooks for setting up early user space networking.<br />
# Choose an SSH server to use in early user space. The options are {{Pkg|mkinitcpio-tinyssh}} or {{Pkg|mkinitcpio-dropbear}}, and are mutually exclusive.<br />
## If using {{Pkg|mkinitcpio-tinyssh}}, it is also recommended to install {{Pkg|tinyssh}} or {{AUR|tinyssh-convert-git}}. This tool converts an existing OpenSSH hostkey to the TinySSH key format, preserving the key fingerprint and avoiding connection warnings. The TinySSH and Dropbear mkinitcpio install scripts will automatically convert existing hostkeys when generating a new initcpio image.<br />
# Decide whether to use an existing OpenSSH key or generate a new one (recommended) for the host that will be connecting to and unlocking the encrypted ZFS machine. Copy the public key into {{ic|/etc/tinyssh/root_key}} or {{ic|/etc/dropbear/root_key}}. When generating the initcpio image, this file will be added to {{ic|authorized_keys}} for the root user and is only valid in the initrd environment.<br />
# Add the {{ic|1=ip=}} [[kernel parameter]] to your boot loader configuration. The {{ic|ip}} string is [https://docs.kernel.org/admin-guide/nfs/nfsroot.html highly configurable]. A simple DHCP example is shown below.{{bc|1=ip=:::::eth0:dhcp}}<br />
# Edit {{ic|/etc/mkinitcpio.conf}} to include the {{ic|netconf}}, {{ic|dropbear}} or {{ic|tinyssh}}, and {{ic|zfsencryptssh}} hooks before the {{ic|zfs}} hook:{{bc|1=HOOKS=(... netconf <tinyssh>{{!}}<dropbear> zfsencryptssh zfs ...)}}<br />
# [[Regenerate the initramfs]].<br />
# Reboot and try it out!<br />
<br />
==== Changing the SSH server port ====<br />
<br />
By default, {{Pkg|mkinitcpio-tinyssh}} and {{Pkg|mkinitcpio-dropbear}} listen on port {{ic|22}}. You may wish to change this.<br />
<br />
For '''TinySSH''', copy {{ic|/usr/lib/initcpio/hooks/tinyssh}} to {{ic|/etc/initcpio/hooks/tinyssh}}, and find/modify the following line in the {{ic|run_hook()}} function:<br />
<br />
{{hc|/etc/initcpio/hooks/tinyssh|<br />
/usr/bin/tcpserver -HRDl0 0.0.0.0 <new_port> /usr/sbin/tinysshd -v /etc/tinyssh/sshkeydir &<br />
}}<br />
<br />
For '''Dropbear''', copy {{ic|/usr/lib/initcpio/hooks/dropbear}} to {{ic|/etc/initcpio/hooks/dropbear}}, and find/modify the following line in the {{ic|run_hook()}} function:<br />
<br />
{{hc|/etc/initcpio/hooks/tinyssh|<br />
/usr/sbin/dropbear -E -s -j -k -p <new_port><br />
}}<br />
<br />
[[Regenerate the initramfs]].<br />
<br />
==== Unlocking from a Windows machine using PuTTY/Plink ====<br />
<br />
First, we need to use {{ic|puttygen.exe}} to import and convert the OpenSSH key generated earlier into PuTTY's ''.ppk'' private key format. Let us call it {{ic|zfs_unlock.ppk}} for this example.<br />
<br />
The mkinitcpio-netconf process above does not setup a shell (nor do we need need one). However, because there is no shell, PuTTY will immediately close after a successful connection. This can be disabled in the PuTTY SSH configuration (''Connection > SSH > [X] Do not start a shell or command at all''), but it still does not allow us to see stdout or enter the encryption passphrase. Instead, we use {{ic|plink.exe}} with the following parameters:<br />
<br />
plink.exe -ssh -l root -i c:\path\to\zfs_unlock.ppk <hostname><br />
<br />
The plink command can be put into a batch script for ease of use.<br />
<br />
== See also ==<br />
<br />
* [https://pthree.org/2012/12/04/zfs-administration-part-i-vdevs/ Aaron Toponce's 17-part blog on ZFS]<br />
* [https://zfsonlinux.org/ ZFS on Linux]<br />
* [https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html OpenZFS FAQ]<br />
* [https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/zfs.html FreeBSD Handbook - The Z File System]<br />
* [https://docs.oracle.com/cd/E19253-01/819-5461/index.html Oracle Solaris ZFS Administration Guide]<br />
* [https://web.archive.org/web/20161028084224/http://www.solarisinternals.com/wiki/index.php/ZFS_Best_Practices_Guide ZFS Best Practices Guide]<br />
* [https://docs.oracle.com/cd/E23823_01/html/819-5461/gavwg.html ZFS Troubleshooting Guide]<br />
* [https://web.archive.org/web/20171213164254/http://royal.pingdom.com/2013/06/04/zfs-backup/ How Pingdom uses ZFS to back up 5TB of MySQL data every day]<br />
* [https://www.linuxquestions.org/questions/linux-from-scratch-13/%5Bhow-to%5D-add-zfs-to-the-linux-kernel-4175514510/ Tutorial on adding the modules to a custom kernel]<br />
* [https://github.com/danboid/creating-ZFS-disks-under-Linux How to create cross platform ZFS disks under Linux]<br />
* [https://blog.heckel.xyz/2017/01/08/zfs-encryption-openzfs-zfs-on-linux/ How-To: Using ZFS Encryption at Rest in OpenZFS (ZFS on Linux, ZFS on FreeBSD, …)]<br />
* [https://archzfs.leibelt.de/ Archzfs iso download page: Frequently updated and downloadable archzfs linux iso with full OpenZFS support since 2016]</div>Iaz3https://wiki.archlinux.org/index.php?title=Zram&diff=780912Zram2023-06-12T15:08:22Z<p>Iaz3: /* Using zram-generator */ Reboot-less zram swap activation</p>
<hr />
<div>{{Lowercase title}}<br />
[[ja:zram]]<br />
[[ru:Zram]]<br />
[[zh-hans:Zram]]<br />
[[Category:Kernel]]<br />
{{Related articles start}}<br />
{{Related|Swap}}<br />
{{Related|zswap}}<br />
{{Related articles end}}<br />
<br />
[https://docs.kernel.org/admin-guide/blockdev/zram.html zram], formerly called compcache, is a Linux kernel module for creating a compressed block device in RAM, i.e. a RAM disk with on-the-fly disk compression. The block device created with zram can then be used for swap or as a general-purpose RAM disk. The two most common uses for zram are for the storage of temporary files ({{ic|/tmp}}) and as a swap device. Initially, zram had only the former function, hence the original name "compcache" ("compressed cache").<br />
<br />
== Usage as swap ==<br />
<br />
Initially the created zram block device does not reserve or use any RAM. Only as files need or want to be swapped out, they will be compressed and moved into the zram block device. The zram block device will then dynamically grow or shrink as required. <br />
<br />
Example (System has 32 GiB RAM, zram is configured with 16 GiB RAM, we assume a 1:4 compression ratio):<br />
<br />
* Worst case (RAM and zram completely "filled"): 16 GiB RAM + 64 GiB zram<br />
* Normal usage without swapping: 32 GiB RAM + 0 GiB zram<br />
* Normal usage with light swapping: 30 GiB RAM + 8 GiB zram<br />
* Without any zram configuration: 32 GiB RAM<br />
<br />
Therefore, zram always offers the advantage of being able to store more content in RAM. <br />
<br />
{{Note|<br />
* Make sure to first [[Zswap#Toggling zswap|disable zswap]] which is enabled by default to avoid zswap acting as a swap cache in front of zram. Having both enabled also results in incorrect {{man|8|zramctl}} statistics as zram remains mostly unused; this is because zswap intercepts and compresses memory pages being swapped out before they can reach zram.<br />
* Hibernating to swap on zram is not supported, even when zram is configured with a backing device on permanent storage. ''logind'' will protect against trying to hibernate to a swap space on zram.<br />
}}<br />
<br />
=== Manually ===<br />
<br />
To set up one zstd compressed zram device with 32GiB capacity and a higher-than-normal priority (only for the current session):<br />
<br />
# modprobe zram<br />
# zramctl /dev/zram0 --algorithm zstd --size 32G<br />
# mkswap -U clear /dev/zram0<br />
# swapon --priority 100 /dev/zram0<br />
<br />
To disable it again, either reboot or run:<br />
<br />
# swapoff /dev/zram0<br />
# modprobe -r zram<br />
<br />
A detailed explanation of all steps, options and potential problems is provided in the [https://docs.kernel.org/admin-guide/blockdev/zram.html official documentation of the zram module].<br />
<br />
For a permanent solution, use a method from one of the following sections.<br />
<br />
=== Using a udev rule ===<br />
<br />
The example below describes how to set up swap on zram automatically at boot with a single udev rule. No extra package should be needed to make this work.<br />
<br />
Explicitly [[load the module at boot]]:<br />
<br />
{{hc|/etc/modules-load.d/zram.conf|<br />
zram<br />
}}<br />
<br />
Create the following [[udev rule]] adjusting the {{ic|disksize}} attribute as necessary: <br />
<br />
{{hc|/etc/udev/rules.d/99-zram.rules|2=<br />
ACTION=="add", KERNEL=="zram0", ATTR{comp_algorithm}="zstd", ATTR{disksize}="4G", RUN="/usr/bin/mkswap -U clear /dev/%k", TAG+="systemd"<br />
}}<br />
<br />
Add {{ic|/dev/zram}} to your [[fstab]] with a higher than default priority:<br />
<br />
{{hc|/etc/fstab|2=<br />
/dev/zram0 none swap defaults,pri=100 0 0<br />
}}<br />
<br />
=== Using zram-generator ===<br />
<br />
[https://github.com/systemd/zram-generator/blob/main/README.md zram-generator] provides a {{ic|systemd-zram-setup@.service}} unit to automatically initialize zram devices without users needing to [[enable/start]] the template or its instances. See {{man|8|zram-generator}} and {{man|5|zram-generator.conf}}.<br />
<br />
For example, to create a zram swap device using {{ic|zstd}} and half of the entire available ram, [[install]] {{Pkg|zram-generator}}, then create {{ic|/etc/systemd/zram-generator.conf}} with the following:<br />
<br />
{{hc|/etc/systemd/zram-generator.conf|2=<br />
[zram0]<br />
zram-size = ram / 2<br />
compression-algorithm = zstd<br />
swap-priority = 100<br />
fs-type = swap<br />
}}<br />
<br />
Run [[daemon-reload]], then [[start]] your configured {{ic|systemd-zram-setup@zram''N''.service}} instance(s).<br />
<br />
You can [[Swap#Swap space|check the swap status]] of your configured {{ic|/dev/zram''N''}} devices by reading the [[unit status]] of your {{ic|systemd-zram-setup@zram''N''.service}} instance(s), or by using {{man|8|zramctl}}.<br />
<br />
=== Using zramswap ===<br />
<br />
{{AUR|zramswap}} provides an automated script for setting up a swap with a higher priority and a default size of 20% of the RAM size of your system. To do this automatically on every boot, [[enable]] {{ic|zramswap.service}}.<br />
<br />
=== Using zramd ===<br />
<br />
{{AUR|zramd}} allows to setup zram automatically using zstd compression by default, its configuration can be changed at {{ic|/etc/default/zramd}}. It can be started at boot by enabling the {{ic|zramd.service}} unit.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Multiple zram devices ===<br />
<br />
By default, loading the {{ic|zram}} module creates a single {{ic|/dev/zram0}} device.<br />
<br />
If you need more than one {{ic|/dev/zram}} device, specify the amount using the {{ic|num_devices}} [[kernel module parameter]] or [https://docs.kernel.org/admin-guide/blockdev/zram.html#add-remove-zram-devices add them as needed afterwards].<br />
<br />
=== Optimizing swap on zram ===<br />
<br />
{{Expansion|Advises the user to set "random" options without explanation.}}<br />
<br />
Since zram behaves differently than disk swap, we can configure the systems swap to take full potential of the zram advantages:<br />
<br />
{{hc|/etc/sysctl.d/99-vm-zram-parameters.conf|2=<br />
vm.swappiness = 180<br />
vm.watermark_boost_factor=0<br />
vm.watermark_scale_factor = 125<br />
vm.page-cluster=0<br />
}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:zram]]<br />
* https://github.com/pop-os/default-settings/pull/163<br />
* https://www.reddit.com/r/pop_os/comments/znh9n6/help_test_a_zram_optimization_for_pop_os/</div>Iaz3https://wiki.archlinux.org/index.php?title=GPGPU&diff=775844GPGPU2023-04-20T13:43:01Z<p>Iaz3: /* ROCm */ Mention miopen-hip</p>
<hr />
<div>[[Category:Development]]<br />
[[Category:Graphics]]<br />
[[ja:GPGPU]]<br />
[[ru:GPGPU]]<br />
{{Related articles start}}<br />
{{Related|Nvidia}}<br />
{{Related|Hardware video acceleration}}<br />
{{Related articles end}}<br />
<br />
GPGPU stands for [[Wikipedia:GPGPU|General-purpose computing on graphics processing units]].<br />
<br />
== OpenCL ==<br />
<br />
[[Wikipedia:OpenCL|OpenCL]] (Open Computing Language) is an open, royalty-free parallel programming specification developed by the Khronos Group, a non-profit consortium.<br />
<br />
The OpenCL specification describes a programming language, a general environment that is required to be present, and a C API to enable programmers to call into this environment.<br />
<br />
{{Tip|The {{pkg|clinfo}} utility can be used to list OpenCL platforms, devices present and ICD loader properties.}}<br />
<br />
=== Runtime ===<br />
<br />
To '''execute''' programs that use OpenCL, a compatible hardware runtime needs to be installed.<br />
<br />
==== AMD/ATI ====<br />
<br />
* {{Pkg|opencl-mesa}}: OpenCL support with clover and rusticl for mesa drivers<br />
* {{Pkg|rocm-opencl-runtime}}: Part of AMD's ROCm GPU compute stack, officially supporting GFX8 and later cards (Fiji, Polaris, Vega), with unofficial and partial support for Navi10 based cards. To support cards older than Vega, you need to set the runtime variable {{ic|1=ROC_ENABLE_PRE_VEGA=1}}. This is similar, but not quite equivalent to [https://amdgpu-install.readthedocs.io/en/latest/install-script.html#specifying-an-opencl-implementation specifying] {{ic|1=opencl=rocr}} in ubuntu's amdgpu-install, because this package's rocm version differs from ubuntu's installer version.<br />
* {{AUR|opencl-legacy-amdgpu-pro}}: Legacy Orca OpenCL repackaged from AMD's ubuntu releases. Equivalent to [https://amdgpu-install.readthedocs.io/en/latest/install-script.html#specifying-an-opencl-implementation specifying] {{ic|1=opencl=legacy}} in ubuntu's amdgpu-install.<br />
* {{AUR|opencl-amd}}, {{AUR|opencl-amd-dev}}: ROCr and Orca OpenCL repackaged from AMD's ubuntu releases. Equivalent to [https://amdgpu-install.readthedocs.io/en/latest/install-script.html#specifying-an-opencl-implementation specifying] {{ic|1=opencl=rocr,legacy}} in ubuntu's amdgpu-install.<br />
* {{AUR|amdapp-sdk}}: AMD CPU runtime<br />
<br />
==== NVIDIA ====<br />
<br />
* {{Pkg|opencl-nvidia}}: official [[NVIDIA]] runtime<br />
<br />
==== Intel ====<br />
<br />
* {{pkg|intel-compute-runtime}}: a.k.a. the Neo OpenCL runtime, the open-source implementation for Intel HD Graphics GPU on Gen8 (Broadwell) and beyond.<br />
* {{Pkg|opencl-mesa}}: OpenCL support with clover and rusticl for mesa drivers<br />
* {{AUR|beignet}}: the open-source implementation for Intel HD Graphics GPU on Gen7 (Ivy Bridge) and beyond, deprecated by Intel in favour of NEO OpenCL driver, remains recommended solution for legacy hardware platforms (e.g. Ivy Bridge, Haswell).<br />
* {{AUR|intel-opencl}}: the proprietary implementation for Intel HD Graphics GPU on Gen7 (Ivy Bridge) and beyond, deprecated by Intel in favour of NEO OpenCL driver, remains recommended solution for legacy hardware platforms (e.g. Ivy Bridge, Haswell).<br />
* {{AUR|intel-opencl-runtime}}: the implementation for Intel Core and Xeon processors. It also supports non-Intel CPUs.<br />
<br />
==== Others ====<br />
<br />
* {{Pkg|pocl}}: LLVM-based OpenCL implementation (hardware independent)<br />
<br />
There is compiler and translator enable OpenCL applications to be run over a Vulkan run-time.<br />
<br />
* {{AUR|clspv-git}}: Clspv is a prototype compiler for a subset of OpenCL C to Vulkan compute shaders.<br />
* [https://github.com/kpet/clvk clvk]: clvk is a prototype implementation of OpenCL 3.0 on top of Vulkan using clspv as the compiler.<br />
* {{AUR|xrt-bin}}: Xilinx Run Time for FPGA [https://github.com/Xilinx/XRT xrt]<br />
*[https://github.com/intel/fpga-runtime-for-opencl fpga-runtime-for-opencl]:FPGA Runtime<br />
<br />
=== 32-bit runtime ===<br />
<br />
To '''execute''' 32-bit programs that use OpenCL, a compatible hardware 32-bit runtime needs to be installed.<br />
<br />
{{Tip|The {{pkg|clinfo}} utility can only be used to list 64-bit OpenCL platforms, devices present and ICD loader properties.<br />
for 32-bit you need to compile clinfo for 32-bit or use the 32-bit [https://www.archlinux32.org/packages/i686/community/clinfo/ clinfo] from the archlinux32 project.}}<br />
<br />
==== AMD/ATI ====<br />
<br />
{{Note|Rusticl is not included in {{pkg|lib32-opencl-mesa}}. The package only provides the Clover implementation}} <br />
* {{Pkg|lib32-opencl-mesa}}: OpenCL support for AMD/ATI Radeon mesa drivers (32-bit)<br />
<br />
==== NVIDIA ====<br />
<br />
* {{Pkg|lib32-opencl-nvidia}}: OpenCL implemention for NVIDIA (32-bit)<br />
<br />
=== ICD loader (libOpenCL.so) ===<br />
<br />
The OpenCL ICD loader is supposed to be a platform-agnostic library that provides the means to load device-specific drivers through the OpenCL API.<br />
Most OpenCL vendors provide their own implementation of an OpenCL ICD loader, and these should all work with the other vendors' OpenCL implementations.<br />
Unfortunately, most vendors do not provide completely up-to-date ICD loaders, and therefore Arch Linux has decided to provide this library from a separate project ({{Pkg|ocl-icd}}) which currently provides a functioning implementation of the current OpenCL API.<br />
<br />
The other ICD loader libraries are installed as part of each vendor's SDK. If you want to ensure the ICD loader from the {{Pkg|ocl-icd}} package is used, you can create a file in {{ic|/etc/ld.so.conf.d}} which adds {{ic|/usr/lib}} to the dynamic program loader's search directories:<br />
<br />
{{hc|/etc/ld.so.conf.d/00-usrlib.conf|<br />
/usr/lib<br />
}}<br />
<br />
This is necessary because all the SDKs add their runtime's lib directories to the search path through {{ic|ld.so.conf.d}} files.<br />
<br />
The available packages containing various OpenCL ICDs are:<br />
<br />
* {{Pkg|ocl-icd}}: recommended, most up-to-date<br />
* {{AUR|intel-opencl}} by Intel. Provides OpenCL 2.0, deprecated in favour of {{pkg|intel-compute-runtime}}.<br />
<br />
{{Note|ICD Loader's vendor is mentioned only to identify each loader, it is otherwise completely irrelevant. ICD loaders are vendor-agnostic and may be used interchangeably (as long as they are implemented correctly).}}<br />
<br />
=== Development ===<br />
<br />
For OpenCL '''development''', the bare minimum additional packages required, are:<br />
<br />
* {{Pkg|ocl-icd}}: OpenCL ICD loader implementation, up to date with the latest OpenCL specification.<br />
* {{Pkg|opencl-headers}}: OpenCL C/C++ API headers.<br />
<br />
The vendors' SDKs provide a multitude of tools and support libraries:<br />
<br />
* {{AUR|intel-opencl-sdk}}: [https://software.intel.com/en-us/articles/opencl-sdk/ Intel OpenCL SDK] (old version, new OpenCL SDKs are included in the INDE and Intel Media Server Studio)<br />
* {{AUR|amdapp-sdk}}: This package is installed as {{ic|/opt/AMDAPP}} and apart from SDK files it also contains a number of code samples ({{ic|/opt/AMDAPP/SDK/samples/}}). It also provides the {{ic|clinfo}} utility which lists OpenCL platforms and devices present in the system and displays detailed information about them. As the SDK itself contains a CPU OpenCL driver, no extra driver is needed to execute OpenCL on CPU devices (regardless of its vendor).<br />
* {{Pkg|cuda}}: Nvidia's GPU SDK which includes support for OpenCL 1.1.<br />
<br />
=== Implementations ===<br />
<br />
To see which OpenCL implementations are currently active on your system, use the following command:<br />
<br />
$ ls /etc/OpenCL/vendors<br />
<br />
To find out all possible (known) properties of the OpenCL platform and devices available on the system, [[install]] {{pkg|clinfo}}.<br />
<br />
==== Rusticl ====<br />
<br />
{{Note|Currently only Intel GPUs are supported through the {{ic|iris}} driver. Support for AMD GPUs through {{ic|radeonsi}} should come soon, and for other GPUs and drivers at a later date.}}<br />
<br />
[https://docs.mesa3d.org/rusticl.html Rusticl] is a new OpenCL implementation written in Rust provided by {{pkg|opencl-mesa}}. It can be enabled by using the [[environment variable]] {{ic|RUSTICL_ENABLE{{=}}''driver''}}, where {{ic|''driver''}} is a Gallium driver, such as {{ic|radeonsi}} or {{ic|iris}}.<br />
<br />
Optionally, if OpenCL applications still do not detect Rusticl, use the following environment variable:<br />
<br />
OCL_ICD_VENDORS=/etc/OpenCL/vendors/rusticl.icd<br />
<br />
==== Language bindings ====<br />
<br />
* '''JavaScript/HTML5''': [https://www.khronos.org/webcl/ WebCL]<br />
* [[Python]]: {{pkg|python-pyopencl}}<br />
* [[D]]: [https://github.com/Trass3r/cl4d cl4d] or [https://github.com/libmir/dcompute DCompute]<br />
* [[Java]]: [https://git.qoto.org/aparapi/aparapi Aparapi] or [https://jogamp.org/jocl/www/ JOCL] (a part of [https://jogamp.org/ JogAmp])<br />
* [[Mono|Mono/.NET]]: [https://sourceforge.net/projects/opentk/ Open Toolkit]<br />
* [[Go]]: [https://github.com/samuel/go-opencl OpenCL bindings for Go]<br />
* '''Racket''': Racket has a native interface [http://planet.racket-lang.org/display.ss?owner=jaymccarthy&package=opencl.plt on PLaneT] that can be installed via raco.<br />
* [[Rust]]: [https://github.com/cogciprocate/ocl ocl]<br />
* [[Julia]]: [https://github.com/JuliaGPU/OpenCL.jl OpenCL.jl]<br />
<br />
== SYCL ==<br />
<br />
[[Wikipedia:SYCL|SYCL]] is another open and royalty-free standard by the Khronos Group that defines a single-source heterogeneous programming model for C++ on top of OpenCL 1.2.<br />
<br />
SYCL consists of a runtime part and a C++ device compiler. The device compiler may target any number and kind of accelerators. The runtime is required to fall back to a pure CPU code path in case no OpenCL implementation can be found.<br />
<br />
=== Implementations ===<br />
<br />
* {{AUR|computecpp}} Codeplay's proprietary implementation of SYCL 1.2.1. Can target SPIR, SPIR-V and experimentally PTX (NVIDIA) as device targets.<br />
* {{AUR|trisycl-git}}: Open source implementation mainly driven by Xilinx. <br />
* {{AUR|hipsycl-cuda-git}} and {{AUR|hipsycl-rocm-git}}: Free implementation built over AMD's HIP instead of OpenCL. Is able to run on AMD and NVIDIA GPUs.<br />
<br />
=== Checking for SPIR support ===<br />
<br />
Most SYCL implementations are able to compile the accelerator code to [[Wikipedia:Standard Portable Intermediate Representation|SPIR]] or [[Wikipedia:Standard Portable Intermediate Representation|SPIR-V]]. Both are intermediate languages designed by Khronos that can be consumed by an OpenCL driver. To check whether SPIR or SPIR-V are supported {{pkg|clinfo}} can be used:<br />
<br />
{{hc|head=$ clinfo {{!}} grep -i spir|output=<br />
Platform Extensions cl_khr_icd cl_khr_global_int32_base_atomics cl_khr_global_int32_extended_atomics cl_khr_local_int32_base_atomics cl_khr_local_int32_extended_atomics cl_khr_byte_addressable_store cl_khr_depth_images cl_khr_3d_image_writes cl_intel_exec_by_local_thread cl_khr_spir cl_khr_fp64 cl_khr_image2d_from_buffer cl_intel_vec_len_hint <br />
IL version SPIR-V_1.0<br />
SPIR versions 1.2<br />
}}<br />
<br />
ComputeCpp additionally ships with a tool that summarizes the relevant system information:<br />
<br />
{{hc|$ computecpp_info|<br />
Device 0:<br />
<br />
Device is supported : UNTESTED - Untested OS<br />
CL_DEVICE_NAME : Intel(R) Core(TM) i7-4770K CPU @ 3.50GHz<br />
CL_DEVICE_VENDOR : Intel(R) Corporation<br />
CL_DRIVER_VERSION : 18.1.0.0920<br />
CL_DEVICE_TYPE : CL_DEVICE_TYPE_CPU <br />
<br />
}}<br />
<br />
{{Out of date|Is the driver for AMD {{AUR|opencl-legacy-amdgpu-pro}} or {{AUR|opencl-amd}}?}}<br />
<br />
Drivers known to at least partially support SPIR or SPIR-V include {{pkg|intel-compute-runtime}}, {{AUR|intel-opencl-runtime}}, {{Pkg|pocl}} and {{AUR|amdgpu-pro-opencl}}{{Broken package link|package not found}}.<br />
<br />
=== Development ===<br />
<br />
SYCL requires a working C++11 environment to be set up. There are a few open source libraries available:<br />
<br />
* [https://github.com/codeplaysoftware/computecpp-sdk/ ComputeCpp SDK]: Collection of code examples, {{Pkg|cmake}} integration for ComputeCpp<br />
* [https://github.com/codeplaysoftware/SYCL-DNN SYCL-DNN]: Neural network performance primitives<br />
* [https://github.com/codeplaysoftware/SYCL-BLAS SYCL-BLAS]: Linear algebra performance primitives<br />
* [https://github.com/codeplaysoftware/visioncpp VisionCpp]: Computer Vision library<br />
* [https://github.com/KhronosGroup/SyclParallelSTL SYCL Parallel STL]: GPU implementation of the C++17 parallel algorithms<br />
<br />
== CUDA ==<br />
<br />
[[Wikipedia:CUDA|CUDA]] (Compute Unified Device Architecture) is [[NVIDIA]]'s proprietary, closed-source parallel computing architecture and framework. It requires an NVIDIA GPU, and consists of several components:<br />
<br />
* Required:<br />
** Proprietary NVIDIA kernel module<br />
** CUDA "driver" and "runtime" libraries<br />
* Optional:<br />
** Additional libraries: CUBLAS, CUFFT, CUSPARSE, etc.<br />
** CUDA toolkit, including the {{ic|nvcc}} compiler<br />
** CUDA SDK, which contains many code samples and examples of CUDA and OpenCL programs<br />
<br />
The kernel module and CUDA "driver" library are shipped in {{Pkg|nvidia}} and {{Pkg|opencl-nvidia}}. The "runtime" library and the rest of the CUDA toolkit are available in {{Pkg|cuda}}. {{ic|cuda-gdb}} needs {{aur|ncurses5-compat-libs}} to be installed, see {{Bug|46598}}.<br />
<br />
=== Development ===<br />
<br />
The {{Pkg|cuda}} package installs all components in the directory {{ic|/opt/cuda}}. For compiling CUDA code, add {{ic|/opt/cuda/include}} to your include path in the compiler instructions. For example, this can be accomplished by adding {{ic|-I/opt/cuda/include}} to the compiler flags/options. To use {{ic|nvcc}}, a {{ic|gcc}} wrapper provided by NVIDIA, add {{ic|/opt/cuda/bin}} to your path.<br />
<br />
To find whether the installation was successful and whether CUDA is up and running, you can compile the [https://github.com/nvidia/cuda-samples CUDA samples]. One way to check the installation is to run the {{ic|deviceQuery}} sample.<br />
<br />
=== Language bindings ===<br />
<br />
* '''Fortran''': [https://www.pgroup.com/resources/cudafortran.htm PGI CUDA Fortran Compiler]<br />
* [[Haskell]]: The [https://hackage.haskell.org/package/accelerate accelerate package] lists available CUDA backends <br />
* [[Java]]: [http://www.jcuda.org/jcuda/JCuda.html JCuda]<br />
* [[Mathematica]]: [https://reference.wolfram.com/mathematica/CUDALink/tutorial/Overview.html CUDAlink]<br />
* [[Mono|Mono/.NET]]: [https://github.com/rapiddev/CUDAfy.NET CUDAfy.NET], [https://github.com/kunzmi/managedCuda managedCuda]<br />
* [[Perl]]: [https://metacpan.org/pod/KappaCUDA KappaCUDA], [https://github.com/run4flat/perl-CUDA-Minimal CUDA-Minimal]<br />
* [[Python]]: {{pkg|python-pycuda}}<br />
* [[Ruby]]: [https://github.com/SciRuby/rbcuda rbcuda]<br />
* [[Rust]]: [https://github.com/rust-cuda/cuda-sys cuda-sys] (bindings) or [https://github.com/bheisler/rustacuda RustaCUDA] (high-level wrapper)<br />
<br />
== ROCm ==<br />
<br />
[https://rocm-documentation.readthedocs.io/en/latest/index.html ROCm] (Radeon Open Compute) is AMD's open-source parallel computing architecture and framework. Although it requires an AMD GPU some ROCm tools are hardware agnostic. See the [https://github.com/rocm-arch/rocm-arch ROCm for Arch Linux repository] for more information.<br />
<br />
* {{Pkg|rocm-hip-sdk}}: Develop applications using HIP and libraries for AMD platforms.<br />
* {{Pkg|rocm-opencl-sdk}}: Develop OpenCL-based applications for AMD platforms.<br />
<br />
=== HIP ===<br />
<br />
The [https://rocmdocs.amd.com/en/latest/Programming_Guides/HIP_API_Guide.html Heterogeneous Interface for Portability (HIP)] is AMD's dedicated GPU programming environment for designing high performance kernels on GPU hardware. HIP is a C++ runtime API and programming language that allows developers to create portable applications on different platforms.<br />
<br />
* {{Pkg|rocm-hip-runtime}}: The base runtime, packages to run HIP applications on the AMD platform.<br />
* {{Pkg|hip-runtime-amd}}: The Heterogeneous Interface for AMDGPUs in ROCm. Supports GPUs from the polaris architecture (RX 500 series) till AMD's latest RDNA 2 architecture (RX 6000 series)<br />
* {{Pkg|miopen-hip}}: [https://github.com/ROCmSoftwarePlatform/MIOpen/blob/develop/doc/src/cache.md#installing-pre-compiled-kernels Pre-compiled GPU kernels] to improve startup latency<br />
* {{AUR|hip-runtime-nvidia}}: The Heterogeneous Interface for NVIDIA GPUs in ROCm.<br />
<br />
{{Tip|More information about using HIP with [[Blender]] is available there.}}<br />
<br />
=== OpenMP ===<br />
<br />
The {{AUR|openmp-extras}} package provides [https://github.com/ROCm-Developer-Tools/aomp AOMP] - an open source Clang/LLVM based compiler with added support for the OpenMP API on AMD GPUs.<br />
<br />
=== OpenCL ===<br />
<br />
The {{Pkg|rocm-opencl-runtime}} package is the part of the ROCm framework providing an OpenCL runtime.<br />
<br />
==== OpenCL image support ====<br />
<br />
The latest ROCm versions now includes OpenCL Image Support used by GPGPU accelerated software such as Darktable. ROCm with the [[AMDGPU]] open source graphics driver are all that is required. AMDGPU PRO is not required.<br />
<br />
{{hc|head=$ /opt/rocm/bin/clinfo {{!}} grep -i "image support"|output=<br />
Image support Yes<br />
}}<br />
<br />
== List of GPGPU accelerated software ==<br />
<br />
{{Expansion|More application may support GPGPU.}}<br />
<br />
* [[Bitcoin]]<br />
* [[Blender]] – CUDA support for Nvidia GPUs and HIP support for AMD GPUs. More information [https://docs.blender.org/manual/en/latest/render/cycles/gpu_rendering.html here].<br />
* [[BOINC]]<br />
* [[FFmpeg]] – more information [https://trac.ffmpeg.org/wiki/HWAccelIntro#OpenCL here].<br />
* [[Folding@home]]<br />
* [[GIMP]] – experimental – more information [http://www.h-online.com/open/news/item/GIMP-2-8-RC-1-arrives-with-GPU-acceleration-1518417.html here].<br />
* [[HandBrake]]<br />
* [[Hashcat]]<br />
* [[LibreOffice]] Calc – more information [https://help.libreoffice.org/Calc/OpenCL_Options here].<br />
* [[Mpv]] - See [[Mpv#Hardware video acceleration]].<br />
* {{Pkg|clinfo}} – Find all possible (known) properties of the OpenCL platform and devices available on the system.<br />
* {{AUR|cuda_memtest}} – a GPU memtest. Despite its name, is supports both CUDA and OpenCL.<br />
* {{Pkg|darktable}} – OpenCL feature requires at least 1 GB RAM on GPU and ''Image support'' (check output of clinfo command).<br />
* [[DaVinci Resolve]] - a non-linear video editor. Can use both OpenCL and CUDA.<br />
* {{Pkg|imagemagick}}<br />
* {{AUR|lc0}} - Used for searching the neural network (supports tensorflow, OpenCL, CUDA, and openblas)<br />
* {{Pkg|opencv}}<br />
* {{AUR|pyrit}}<br />
* {{Pkg|python-pytorch-cuda}} - PyTorch with CUDA backend<br />
* {{Pkg|tensorflow-cuda}} - Port of TensorFlow to CUDA<br />
* {{AUR|tensorflow-computecpp}} - Port of TensorFlow to SYCL<br />
* {{Pkg|xmrig}} - High Perf CryptoNote CPU and GPU (OpenCL, CUDA) miner<br />
<br />
== See also ==<br />
<br />
* [https://www.khronos.org/opencl/ OpenCL official homepage]<br />
* [https://www.khronos.org/sycl/ SYCL official homepage]<br />
* [https://www.khronos.org/spir/ SPIR official homepage]<br />
* [https://developer.nvidia.com/cuda-toolkit CUDA Toolkit homepage]<br />
* [https://software.intel.com/en-us/intel-opencl Intel SDK for OpenCL Applications homepage]<br />
* [https://developer.codeplay.com/home/ ComputeCpp official homepage]<br />
* [https://gitlab.com/illwieckz/i-love-compute List of OpenCL frameworks applicable for different GPUs]</div>Iaz3https://wiki.archlinux.org/index.php?title=DSDT&diff=774299DSDT2023-03-31T19:24:06Z<p>Iaz3: /* Recompiling it yourself */ link fix link to ACPI specs</p>
<hr />
<div>[[Category:Boot process]]<br />
[[Category:Kernel]]<br />
[[Category:Power management]]<br />
[[ja:DSDT]]<br />
[[zh-hans:DSDT]]<br />
{{Related articles start}}<br />
{{Related|ACPI modules}}<br />
{{Related|acpid}}<br />
{{Related articles end}}<br />
DSDT (Differentiated System Description Table) is a part of the [[Wikipedia:Advanced Configuration and Power Interface|ACPI]] specification. It supplies information about supported power events in a given system. ACPI tables are provided in firmware from the manufacturer. A common Linux problem is missing ACPI functionality, such as: fans not running, screens not turning off when the lid is closed, etc. This can stem from DSDTs made with Windows specifically in mind, which can be patched after installation. The goal of this article is to analyze and rebuild a faulty DSDT, so that the kernel can override the default one.<br />
<br />
Basically a DSDT table is the code run on ACPI (Power Management) events.<br />
<br />
{{Note|The goal of the [https://01.org/linux-acpi Linux ACPI]{{Dead link|2022|09|17|status=403}} project is that Linux should work on unmodified firmware. If you still find this type of workaround necessary on modern kernels then you should consider [[Reporting bug guidelines|submitting a bug report]]. }}<br />
<br />
== Before you start... ==<br />
<br />
It is possible that the hardware manufacturer has released an updated firmware which fixes ACPI related problems. Installing an updated firmware is often preferred over this method because it would avoid duplication of effort.<br />
<br />
This process does tamper with some fairly fundamental code on your installation. You will want to be absolutely sure of the changes you make. You might also wish to [[Disk cloning|clone your disk]] beforehand.<br />
<br />
Even before attempting to fix your DSDT yourself, you can attempt a couple of different shortcuts:<br />
<br />
=== Tell the kernel to report a version of Windows ===<br />
<br />
Use the variable {{ic|acpi_os_name}} as a [[kernel parameter]]. For example:<br />
<br />
acpi_os_name="Microsoft Windows NT"<br />
<br />
Or<br />
<br />
acpi_osi="!Windows2012"<br />
<br />
other strings to test:<br />
* "Microsoft Windows XP"<br />
* "Microsoft Windows 2000"<br />
* "Microsoft Windows 2000.1"<br />
* "Microsoft Windows ME: Millennium Edition"<br />
* "Windows 2001"<br />
* "Windows 2006"<br />
* "Windows 2009"<br />
* "Windows 2012"<br />
* when all that fails, you can even try "Linux"<br />
<br />
Out of curiousity, you can follow the steps below to extract your DSDT and search the ''.dsl'' file. Just grep for "Windows" and see what pops up.<br />
<br />
=== Find a fixed DSDT ===<br />
<br />
A DSDT file is originally written in ACPI Source language (an ''.asl''/''.dsl'' file). Using a compiler this can produce an 'ACPI Machine Language' file (''.aml'') or a hex table (''.hex''). To incorporate the file in your Arch install, you will need to get hold of a compiled ''.aml'' file — whether this means compiling it yourself or trusting some stranger on the Internet is at your discretion. If you do download a file from the world wide web, it will most likely be a compressed ''.asl'' file. So you will need to unzip it and compile it. The upside to this is that you will not have to research specific code fixes yourself.<br />
<br />
Arch users with the same laptop as you are: a minority of a minority of a minority. Try browsing other distributions/Linux forums for talk about the same model. It is likely they have the same problems and either because there is a lot of them, or because they are tech savvy — someone there has produced a working DSDT and may even provide a precompiled version (again, use at your own risk).<br />
Search engines are your best tools. Try keeping it short: 'model name' + 'dsdt' will probably produce results.<br />
<br />
== Recompiling it yourself ==<br />
<br />
Your best resources in this endeavor are going to be [https://uefi.org/acpi/specs ACPI Spec homepage], and [https://01.org/linux-acpi Linux ACPI Project]{{Dead link|2022|09|17|status=403}} which supercedes the activity that occurred at ''acpi.sourceforge.net''.<br />
In a nutshell, you can use Intel's ASL compiler to turn your systems DSDT table into source code, locate/fix the errors, and recompile.<br />
<br />
You will need to install {{Pkg|acpica}} to modify code.<br />
<br />
'''What compiled the original code?'''<br />
Check if your system's DSDT was compiled using Intel or Microsoft compiler:<br />
{{hc|# dmesg {{!}} grep DSDT|<br />
ACPI: DSDT 00000000bf7e5000 0A35F (v02 Intel CALPELLA 06040000 INTL 20060912)<br />
ACPI: EC: Look up EC in DSDT<br />
}}<br />
In case Microsoft's compiler had been used, abbreviation INTL would instead be MSFT.<br />
In the example, there were 5 errors on decompiling/recompiling the DSDT. Two of them were easy to fix after a bit of googling and delving into the ACPI specification. Three of them were due to different versions of compiler used and are, as later discovered, handled by the ACPICA at boot-time. The ACPICA component of the kernel can handle most of the trivial errors you get while compiling the DSDT. So do not fret yourself over compile errors if your system is ''working the way it should''.<br />
<br />
Extract the binary ACPI tables:<br />
<br />
{{bc|# cat /sys/firmware/acpi/tables/DSDT > dsdt.dat}}<br />
<br />
Disassemble the ACPI tables to a ''.dsl'' file:<br />
<br />
{{bc|$ iasl -d dsdt.dat}}<br />
<br />
Attempt to create a hex AML table (in C) from the ''.dsl'' file:<br />
<br />
{{bc|$ iasl -tc dsdt.dsl}}<br />
<br />
Examine any errors outputted from creating the hex AML table and fix them. For example:<br />
<br />
{{bc|<br />
dsdt.dsl 6727: Name (_PLD, Buffer (0x10) <br />
Error 4105 - Invalid object type for reserved name ^ (found BUFFER, requires Package)<br />
}}<br />
<br />
Amend the file at line 6727 where the error occurred:<br />
<br />
{{bc|<br />
(_PLD, '''Package(1) {'''Buffer (0x10)<br />
{<br />
...<br />
}'''}''')<br />
}}<br />
<br />
Increase the OEM version. Otherwise, the kernel will not apply the modified ACPI table. For example, before increasing the OEM version:<br />
<br />
{{bc|DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)}}<br />
<br />
After increasing the OEM version:<br />
<br />
{{bc|DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x0000000'''1''')}}<br />
<br />
Create the hex AML table again after fixing all errors and increasing the OEM version:<br />
<br />
{{bc|$ iasl -tc dsdt.dsl}}<br />
<br />
You might want to try the option {{ic|-ic}} for C include file to insert into kernel source. If no errors and no warnings are raised, you should be good to go.<br />
<br />
== Using modified code ==<br />
<br />
{{Warning|After each BIOS update you will need to fix DSDT again and repeat these steps!}}<br />
<br />
There are at least two ways to use a custom DSDT:<br />
* creating a CPIO archive that is loaded by the boot loader<br />
* compiling it into the kernel<br />
<br />
=== Using a CPIO archive ===<br />
<br />
This method has the advantage that you do not need to recompile your kernel, and updating the kernel will not make it necessary to repeat these steps.<br />
<br />
This method requires the {{ic|1=ACPI_TABLE_UPGRADE=y}} kernel configuration to be enabled (true for the {{pkg|linux}} package). See [https://docs.kernel.org/admin-guide/acpi/initrd_table_override.html] for details.<br />
<br />
First, create the following folder structure: <br />
$ mkdir -p kernel/firmware/acpi<br />
Copy the fixed ACPI tables into the just created {{ic|kernel/firmware/acpi}} folder, for example:<br />
$ cp dsdt.aml ssdt1.aml kernel/firmware/acpi<br />
Within the same folder where the newly created {{ic|kernel/}} folder resides, run:<br />
$ find kernel | cpio -H newc --create > acpi_override<br />
This creates the CPIO archive containing the fixed ACPI tables. Copy the archive to the {{ic|boot}} directory.<br />
# cp acpi_override /boot<br />
Lastly, configure the [[boot loader]] to load your CPIO archive. For example, using [[Systemd-boot]], {{ic|/boot/loader/entries/arch.conf}} might look like this:<br />
title Arch Linux<br />
linux /vmlinuz-linux<br />
initrd /acpi_override<br />
initrd /initramfs-linux.img<br />
options root=PARTUUID=ec9d5998-a9db-4bd8-8ea0-35a45df04701 resume=PARTUUID=58d0aa86-d39b-4fe1-81cf-45e7add275a0 ...<br />
Now all that is left to do is to reboot and to [[#Verify successful override|verify the result.]]<br />
<br />
=== Compiling into the kernel ===<br />
<br />
You will want to be familiar with [[Kernels|compiling your own kernel]]. The most straightforward way is with the "traditional" approach.<br />
After compiling DSDT, iasl produce two files: {{ic|dsdt.hex}} and {{ic|dsdt.aml}}.<br />
<br />
'''Using {{ic|menuconfig}}:'''<br />
* Disable "Select only drivers that do not need compile-time external firmware". Located in "Device Drivers -> Generic Driver Options".<br />
* Enable "Include Custom DSDT" and specify the absolute path of your fixed DSDT file ({{ic|dsdt.hex}}, not {{ic|dsdt.aml}}). Located in "Power management and ACPI options -> ACPI (Advanced Configuration and Power Interface) Support".<br />
<br />
== Verify successful override ==<br />
<br />
Look for messages that confirm the override, for example:<br />
<br />
{{hc|# dmesg {{!}} grep ACPI|<br />
[ 0.000000] ACPI: Override [DSDT- A M I], this is unsafe: tainting kernel<br />
[ 0.000000] ACPI: DSDT 00000000be9b1190 Logical table override, new table: ffffffff81865af0<br />
[ 0.000000] ACPI: DSDT ffffffff81865af0 0BBA3 (v02 ALASKA A M I 000000F3 INTL 20130517)<br />
}}<br />
<br />
== See also ==<br />
<br />
* [https://docs.kernel.org/admin-guide/acpi/initrd_table_override.html Upgrading ACPI tables via initrd]<br />
* [https://docs.microsoft.com/en-us/windows-hardware/drivers/acpi/winacpi-osi How to Identify the Windows Version in ACPI by Using _OSI]</div>Iaz3https://wiki.archlinux.org/index.php?title=Network_configuration/Wireless&diff=773477Network configuration/Wireless2023-03-22T14:20:36Z<p>Iaz3: /* Respecting the regulatory domain */ More accurate and useful. Previously there was no mention that `iw` was temporary and the only way to know was to infer it from the throwaway line about `/etc/conf.d/wireless-regdom` being permanent.</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[de:(W)LAN und Arch Linux]]<br />
[[fa:تنظیمات شبکه ی بی سیم]]<br />
[[ja:ワイヤレス設定]]<br />
[[pt:Network configuration (Português)/Wireless]]<br />
[[ru:Network configuration (Русский)/Wireless]]<br />
[[zh-hans:网络配置/无线网络配置]]<br />
{{Related articles start}}<br />
{{Related|Software access point}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related|Wireless bonding}}<br />
{{Related|Network Debugging}}<br />
{{Related|Bluetooth}}<br />
{{Related articles end}}<br />
<br />
The main article on network configuration is [[Network configuration]].<br />
<br />
Configuring wireless is a two-part process; the first part is to identify and ensure the correct driver for your wireless device is installed (they are available on the installation media, but often have to be installed explicitly), and to configure the interface. The second is choosing a method of managing wireless connections. This article covers both parts, and provides additional links to wireless management tools.<br />
<br />
The [[#iw]] section describes how to manually manage your wireless network interface / your wireless LANs using {{Pkg|iw}}. The [[Network configuration#Network managers]] section describes several programs that can be used to automatically manage your wireless interface, some of which include a GUI and all of which include support for network profiles (useful when frequently switching wireless networks, like with laptops).<br />
<br />
== Device driver ==<br />
<br />
The default Arch Linux kernel is ''modular'', meaning many of the drivers for machine hardware reside on the hard drive and are available as [[Kernel modules|modules]]. At boot, [[udev]] takes an inventory of your hardware and loads appropriate modules (drivers) for your corresponding hardware, which will in turn allow creation of a network ''interface''.<br />
<br />
Some wireless chipsets also require firmware, in addition to a corresponding driver. Many firmware images are provided by the {{Pkg|linux-firmware}} package; however, proprietary firmware images are not included and have to be installed separately. This is described in [[#Installing driver/firmware]].<br />
<br />
{{Note|If the proper module is not loaded by udev on boot, simply [[Kernel modules#Manual module handling|load it manually]]. If udev loads more than one driver for a device, the resulting conflict may prevent successful configuration. Make sure to [[blacklist]] the unwanted module.}}<br />
<br />
=== Check the driver status ===<br />
<br />
To check if the driver for your card has been loaded, check the output of the {{ic|lspci -k}} or {{ic|lsusb -v}} command, depending on if the card is connected by PCI(e) or USB. You should see that some kernel driver is in use, for example:<br />
<br />
{{hc|$ lspci -k|<br />
06:00.0 Network controller: Intel Corporation WiFi Link 5100<br />
Subsystem: Intel Corporation WiFi Link 5100 AGN<br />
Kernel driver in use: iwlwifi<br />
Kernel modules: iwlwifi<br />
}}<br />
<br />
{{Note|If the card is a USB device, running {{ic|dmesg {{!}} grep usbcore}} as root should give something like {{ic|usbcore: registered new interface driver rtl8187}} as output.}}<br />
<br />
Also check the output of the {{ic|ip link}} command to see if a wireless interface was created; usually the naming of the wireless [[network interfaces]] starts with the letter "w", e.g. {{ic|wlan0}} or {{ic|wlp2s0}}. Then bring the interface up with:<br />
<br />
# ip link set ''interface'' up<br />
<br />
For example, assuming the interface is {{ic|wlan0}}, this is {{ic|ip link set wlan0 up}}.<br />
<br />
{{Note|<br />
* If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that the device is not hard-blocked or soft-blocked. See [[#Rfkill caveat]] for details.<br />
* If you get the error message {{ic|SIOCSIFFLAGS: No such file or directory}}, it most certainly means that your wireless chipset requires a firmware to function.<br />
}}<br />
<br />
Check kernel messages for firmware being loaded:<br />
<br />
{{hc|# dmesg {{!}} grep firmware|<br />
[ 7.148259] iwlwifi 0000:02:00.0: loaded firmware version 39.30.4.1 build 35138 op_mode iwldvm<br />
}}<br />
<br />
If there is no relevant output, check the messages for the full output for the module you identified earlier ({{ic|iwlwifi}} in this example) to identify the relevant message or further issues:<br />
<br />
{{hc|# dmesg {{!}} grep iwlwifi|2=<br />
[ 12.342694] iwlwifi 0000:02:00.0: irq 44 for MSI/MSI-X<br />
[ 12.353466] iwlwifi 0000:02:00.0: loaded firmware version 39.31.5.1 build 35138 op_mode iwldvm<br />
[ 12.430317] iwlwifi 0000:02:00.0: CONFIG_IWLWIFI_DEBUG disabled<br />
...<br />
[ 12.430341] iwlwifi 0000:02:00.0: Detected Intel(R) Corporation WiFi Link 5100 AGN, REV=0x6B<br />
}}<br />
<br />
If the kernel module is successfully loaded and the interface is up, you can skip the next section.<br />
<br />
=== Installing driver/firmware ===<br />
<br />
Check the following lists to discover if your card is supported:<br />
<br />
* See the table of [https://wireless.wiki.kernel.org/en/users/drivers existing Linux wireless drivers] and follow to the specific driver's page, which contains a list of supported devices. There is also a [https://wikidevi.com/wiki/List_of_Wi-Fi_Device_IDs_in_Linux List of Wi-Fi Device IDs in Linux]{{Dead link|2022|11|11}}.<br />
* The [https://help.ubuntu.com/community/WifiDocs/WirelessCardsSupported Ubuntu Wiki] has a good list of wireless cards and whether or not they are supported either in the Linux kernel or by a user-space driver (includes driver name).<br />
* [http://linux-wless.passys.nl/ Linux Wireless Support] and The Linux Questions' [https://web.archive.org/web/20110711100256/http://www.linuxquestions.org/hcl/index.php?cat=10 Hardware Compatibility List] (HCL) also have a good database of kernel-friendly hardware.<br />
<br />
Note that some vendors ship products that may contain different chip sets, even if the product identifier is the same. Only the usb-id (for USB devices) or pci-id (for PCI devices) is authoritative.<br />
<br />
If your wireless card is listed above, follow the [[#Troubleshooting drivers and firmware]] subsection of this page, which contains information about installing drivers and firmware of some specific wireless cards. Then [[#Check the driver status|check the driver status]] again.<br />
<br />
If your wireless card is not listed above, it is likely supported only under Windows (some Broadcom, 3com, etc). For these, you can try to use [[#ndiswrapper]].<br />
<br />
== Utilities ==<br />
<br />
Just like other network interfaces, the wireless ones are controlled with ''ip'' from the {{Pkg|iproute2}} package.<br />
<br />
Managing a wireless connection requires a basic set of tools. Either use a [[network manager]] or use one of the following directly:<br />
<br />
{| class="wikitable"<br />
! Software !! Package !! [https://wireless.wiki.kernel.org/en/developers/documentation/wireless-extensions WEXT] !! [https://wireless.wiki.kernel.org/en/developers/documentation/nl80211 nl80211] !! WEP !! WPA/WPA2/WPA3 !! [[Archiso]] [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/packages.x86_64]<br />
|-<br />
| [https://hewlettpackard.github.io/wireless-tools/Tools.html wireless_tools]<sup>1</sup> || {{Pkg|wireless_tools}} || {{Yes}} || {{no}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [https://wireless.wiki.kernel.org/en/users/documentation/iw iw] || {{Pkg|iw}} || {{No}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [[wpa_supplicant]] || {{Pkg|wpa_supplicant}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}} || {{Yes}}<br />
|-<br />
| [[iwd]] || {{Pkg|iwd}} || {{No}} || {{Yes}} || {{No}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
# Deprecated.<br />
<br />
Note that some cards only support WEXT.<br />
<br />
=== iw and wireless_tools comparison ===<br />
<br />
The table below gives an overview of comparable commands for ''iw'' and ''wireless_tools''. See [https://wireless.wiki.kernel.org/en/users/Documentation/iw/replace-iwconfig iw replaces iwconfig] for more examples.<br />
<br />
{| class="wikitable"<br />
! ''iw'' command<br />
! ''wireless_tools'' command<br />
! Description<br />
|-<br />
| iw dev ''wlan0'' link<br />
| iwconfig ''wlan0''<br />
| Getting link status.<br />
|-<br />
| iw dev ''wlan0'' scan<br />
| iwlist ''wlan0'' scan<br />
| Scanning for available access points.<br />
|-<br />
| iw dev ''wlan0'' set type ibss<br />
| iwconfig ''wlan0'' mode ad-hoc<br />
| Setting the operation mode to ''ad-hoc''.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid''<br />
| iwconfig ''wlan0'' essid ''your_essid''<br />
| Connecting to open network.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid'' 2432<br />
| iwconfig ''wlan0'' essid ''your_essid'' freq 2432M<br />
| Connecting to open network specifying channel.<br />
|-<br />
| rowspan="2" | iw dev ''wlan0'' connect ''your_essid'' key 0:''your_key''<br />
| iwconfig ''wlan0'' essid ''your_essid'' key ''your_key''<br />
| Connecting to WEP encrypted network using hexadecimal key.<br />
|-<br />
| iwconfig ''wlan0'' essid ''your_essid'' key s:''your_key''<br />
| Connecting to WEP encrypted network using ASCII key.<br />
|-<br />
| iw dev ''wlan0'' set power_save on<br />
| iwconfig ''wlan0'' power on<br />
| Enabling power save.<br />
|}<br />
<br />
== iw ==<br />
<br />
{{Note|<br />
* Note that most of the commands have to be executed with [[Users and groups|root permissions]]. Executed with normal user rights, some of the commands (e.g. ''iw list'') will exit without error but not produce the correct output either, which can be confusing.<br />
* Depending on your hardware and encryption type, some of these steps may not be necessary. Some cards are known to require interface activation and/or access point scanning before being associated to an access point and being given an IP address. Some experimentation may be required. For instance, WPA/WPA2 users may try to directly activate their wireless network from step [[#Connect to an access point]].}}<br />
<br />
Examples in this section assume that your wireless device interface is {{ic|''interface''}} and that you are connecting to {{ic|''your_essid''}} WiFi access point. Replace both accordingly.<br />
<br />
=== Get the name of the interface ===<br />
<br />
{{Tip|See [https://wireless.wiki.kernel.org/en/users/documentation/iw official documentation] of the ''iw'' tool for more examples.}}<br />
<br />
To get the name of your wireless interface, do:<br />
<br />
$ iw dev<br />
<br />
The name of the interface will be output after the word "Interface". For example, it is commonly {{ic|wlan0}}.<br />
<br />
=== Get the status of the interface ===<br />
<br />
To check link status, use the following command.<br />
<br />
$ iw dev ''interface'' link<br />
<br />
You can get statistic information, such as the amount of tx/rx bytes, signal strength etc., with the following command:<br />
<br />
$ iw dev ''interface'' station dump<br />
<br />
=== Activate the interface ===<br />
<br />
{{Tip|Usually this step is not required.}}<br />
<br />
Some cards require that the kernel interface be activated before you can use ''iw'' or ''wireless_tools'':<br />
<br />
# ip link set ''interface'' up<br />
<br />
{{Note|If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.}}<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|$ ip link show ''interface''|<br />
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 12:34:56:78:9a:bc brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
=== Discover access points ===<br />
<br />
To see what access points are available:<br />
<br />
# iw dev ''interface'' scan | less<br />
<br />
{{Note|If it displays {{ic|Interface does not support scanning}}, then you probably forgot to install the firmware. In some cases, this message is also displayed when not running ''iw'' as root.}}<br />
<br />
{{Tip|Depending on your location, you might need to set the correct [[#Respecting the regulatory domain|regulatory domain]] in order to see all available networks.}}<br />
<br />
The important points to check:<br />
* '''SSID:''' the name of the network.<br />
* '''Signal:''' is reported in a wireless power ratio in dBm (e.g. from -100 to 0). The closer the negative value gets to zero, the better the signal. Observing the reported power on a good quality link and a bad one should give an idea about the individual range. <br />
* '''Security:''' it is not reported directly, check the line starting with {{ic|capability}}. If there is {{ic|Privacy}}, for example {{ic|capability: ESS Privacy ShortSlotTime (0x0411)}}, then the network is protected somehow.<br />
** If you see an {{ic|RSN}} information block, then the network is protected by [[Wikipedia:IEEE 802.11i-2004|Robust Security Network]] protocol, also known as WPA2.<br />
** If you see an {{ic|WPA}} information block, then the network is protected by [[Wikipedia:Wi-Fi Protected Access|Wi-Fi Protected Access]] protocol.<br />
** In the {{ic|RSN}} and {{ic|WPA}} blocks, you may find the following information:<br />
*** '''Group cipher:''' value in TKIP, CCMP, both, others.<br />
*** '''Pairwise ciphers:''' value in TKIP, CCMP, both, others. Not necessarily the same value than Group cipher.<br />
*** '''Authentication suites:''' value in PSK, 802.1x, others. For home router, you will usually find PSK (''i.e.'' passphrase). In universities, you are more likely to find 802.1x suite which requires login and password. Then you will need to know which key management is in use (e.g. EAP), and what encapsulation it uses (e.g. PEAP). See [[#WPA2 Enterprise]] and [[Wikipedia:Authentication protocol]] for details.<br />
** If you see neither {{ic|RSN}} nor {{ic|WPA}} blocks but there is {{ic|Privacy}}, then WEP is used.<br />
<br />
=== Set operating mode ===<br />
<br />
You might need to set the proper operating mode of the wireless card. More specifically, if you are going to connect an [[Ad-hoc networking|ad-hoc network]], you need to set the operating mode to {{ic|ibss}}:<br />
<br />
# iw dev ''interface'' set type ibss<br />
<br />
{{Note|Changing the operating mode on some cards might require the wireless interface to be ''down'' ({{ic|ip link set ''interface'' down}}).}}<br />
<br />
{{Note|During changing of the operating mode to AP ({{ic|iw ''interface'' set type ap}}) you will get an error like this:<br />
You need to run a management daemon, e.g. hostapd,<br />
see https://wireless.wiki.kernel.org/en/users/documentation/hostapd<br />
for more information on how to do that.<br />
<br />
This can be bypassed by changing the operating mode to {{ic|__ap}} ({{ic|iw ''interface'' set type __ap}}).}}<br />
<br />
=== Connect to an access point ===<br />
<br />
Depending on the encryption, you need to associate your wireless device with the access point to use and pass the encryption key:<br />
<br />
* '''No encryption''' {{bc|# iw dev ''interface'' connect "''your_essid''"}}<br />
* '''WEP'''<br />
** using a hexadecimal or ASCII key (the format is distinguished automatically, because a WEP key has a fixed length): {{bc|# iw dev ''interface'' connect "''your_essid''" key 0:''your_key''}}<br />
** using a hexadecimal or ASCII key, specifying the third set up key as default (keys are counted from zero, four are possible): {{bc|# iw dev ''interface'' connect "''your_essid''" key d:2:''your_key''}}<br />
* '''Other'''<br />
** ''iw'' can only handle WEP. To connect using other encryption schemes, see the section on [[#Authentication]] below.<br />
<br />
Regardless of the method used, you can check if you have associated successfully:<br />
<br />
# iw dev ''interface'' link<br />
<br />
== Authentication ==<br />
<br />
{{Expansion|Add [[Wikipedia:Opportunistic Wireless Encryption|Opportunistic Wireless Encryption (OWE) a.k.a. Enhanced Open]]. Warn against WEP and open networks.}}<br />
<br />
=== WPA2 Personal ===<br />
<br />
WPA2 Personal, a.k.a. WPA2-PSK, is a mode of [[Wikipedia:Wi-Fi Protected_Access|Wi-Fi Protected Access]].<br />
<br />
You can authenticate to WPA2 Personal networks using [[wpa_supplicant]] or [[iwd]], or connect using a [[network manager]]. If you only authenticated to the network, then to have a fully functional connection, you will still need to assign the IP address(es) and routes either [[Network configuration#Static IP address|manually]] or using a [[DHCP]] client.<br />
<br />
=== WPA2 Enterprise ===<br />
<br />
''WPA2 Enterprise'' is a mode of [[Wikipedia:Wi-Fi_Protected_Access|Wi-Fi Protected Access]]. It provides better security and key management than ''WPA2 Personal'', and supports other enterprise-type functionality, such as VLANs and [[wikipedia:Network Access Protection|NAP]]. However, it requires an external authentication server, called [[wikipedia:RADIUS|RADIUS]] server, to handle the authentication of users. This is in contrast to Personal mode which does not require anything beyond the wireless router or access points (APs), and uses a single passphrase or password for all users.<br />
<br />
The Enterprise mode enables users to log onto the Wi-Fi network with a username and password and/or a digital certificate. Since each user has a dynamic and unique encryption key, it also helps to prevent user-to-user snooping on the wireless network, and improves encryption strength.<br />
<br />
This section describes the configuration of [[List of applications#Network managers|network clients]] to connect to a wireless access point with WPA2 Enterprise mode. See [[Software access point#RADIUS]] for information on setting up an access point itself. <br />
<br />
{{Note|Enterprise mode requires a more complex client configuration, whereas Personal mode only requires entering a passphrase when prompted. Clients likely need to install the server’s CA certificate (plus per-user certificates if using EAP-TLS), and then manually configure the wireless security and 802.1X authentication settings.}}<br />
<br />
For a comparison of protocols, see the following [http://deployingradius.com/documents/protocols/compatibility.html table].<br />
<br />
{{Warning|It is possible to use WPA2 Enterprise without the client checking the server CA certificate. However, you should always seek to do so, because without authenticating the access point, the connection can be subject to a man-in-the-middle attack. This may happen because while the connection handshake itself may be encrypted, the most widely used setups transmit the password itself either in plain text or the easily breakable [[#MS-CHAPv2]]. Hence, the client might send the password to a malicious access point which then proxies the connection.}}<br />
<br />
==== MS-CHAPv2 ====<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require {{Pkg|pptpclient}} in addition to the stock {{Pkg|ppp}} package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option.<br />
<br />
==== eduroam ====<br />
<br />
[[Wikipedia:eduroam|eduroam]] is an international roaming service for users in research, higher education and further education, based on WPA2 Enterprise.<br />
<br />
{{Note|<br />
* Check connection details '''first''' with your institution before applying any profiles listed in this section. Example profiles are not guaranteed to work or match any security requirements.<br />
* When storing connection profiles unencrypted, it is recommended restrict read access to the root account by specifying {{ic|chmod 600 ''profile''}} as root.<br />
}}<br />
<br />
{{Tip|Configuration for [[NetworkManager]] can be generated with the [https://cat.eduroam.org/ eduroam Configuration Assistant Tool]. It requires {{Pkg|python}} and {{Pkg|dbus-python}} to be installed.}}<br />
<br />
==== Manual/automatic setup ====<br />
<br />
* [[wpa_supplicant#Advanced usage|wpa_supplicant]] can be configured directly by its configuration file or using its CLI/GUI front ends and used in combination with a DHCP client. See the examples in {{ic|/usr/share/doc/wpa_supplicant/wpa_supplicant.conf}} for configuring the connection details.<br />
* [[iwd#WPA Enterprise]]<br />
* [[NetworkManager]] can create WPA2 Enterprise profiles with ''nmcli'' or the [[NetworkManager#Front-ends|graphical front ends]]. ''nmtui'' does not support this ([https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/376 NetworkManager issue 376]), but may use existing profiles.<br />
* [[ConnMan]] needs a separate configuration file before [[ConnMan#Wi-Fi|connecting]] to the network. See {{man|5|connman-service.config}} and [[ConnMan#Connecting to eduroam (802.1X)]] for details.<br />
* [[netctl]] supports wpa_supplicant configuration through blocks included with {{ic|1=WPAConfigSection=}}. See {{man|5|netctl.profile}} for details.<br />
: {{Note|Special quoting rules apply: see {{man|5|netctl.profile|SPECIAL QUOTING RULES}}.}}<br />
: {{Tip|Custom certificates can be specified by adding the line {{ic|1='ca_cert="/path/to/special/certificate.cer"'}} in {{ic|WPAConfigSection}}.}}<br />
<br />
=== WPA3 Personal ===<br />
<br />
WPA3 Personal, a.k.a. WPA3-SAE, is a mode of [[Wikipedia:Wi-Fi Protected Access#WPA3|Wi-Fi Protected Access]].<br />
<br />
Both [[wpa_supplicant]] and [[iwd]] support WPA3 Personal.<br />
<br />
=== WPA3 Enterprise ===<br />
<br />
WPA3 Enterprise is a mode of [[Wikipedia:Wi-Fi Protected Access#WPA3|Wi-Fi Protected Access]].<br />
<br />
[[wpa_supplicant]] (since version 2:2.10-8) supports WPA3 Enterprise. See {{Bug|65314}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Respecting the regulatory domain ===<br />
<br />
The [[wikipedia:IEEE_802.11#Regulatory_domains_and_legal_compliance|regulatory domain]], or "regdomain", is used to reconfigure wireless drivers to make sure that wireless hardware usage complies with local laws set by the FCC, ETSI and other organizations. Regdomains use [[wikipedia:ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country codes]]. For example, the regdomain of the United States would be "US", China would be "CN", etc.<br />
<br />
Regdomains affect the availability of wireless channels. In the 2.4GHz band, the allowed channels are 1-11 for the US, 1-14 for Japan, and 1-13 for most of the rest of the world. In the 5GHz band, the rules for allowed channels are much more complex. In either case, consult [[wikipedia:List_of_WLAN_channels|this list of WLAN channels]] for more detailed information.<br />
<br />
Regdomains also affect the limit on the [[wikipedia:Equivalent_isotropically_radiated_power|effective isotropic radiated power (EIRP)]] from wireless devices. This is derived from transmit power/"tx power", and is measured in [[wikipedia:DBm|dBm/mBm (1dBm=100mBm) or mW (log scale)]]. In the 2.4GHz band, the maximum is 30dBm in the US and Canada, 20dBm in most of Europe, and 20dBm-30dBm for the rest of the world. In the 5GHz band, maximums are usually lower. Consult the [https://git.kernel.org/cgit/linux/kernel/git/linville/wireless-regdb.git/tree/db.txt wireless-regdb] for more detailed information (EIRP dBm values are in the second set of brackets for each line).<br />
<br />
Misconfiguring the regdomain can be useful - for example, by allowing use of an unused channel when other channels are crowded, or by allowing an increase in tx power to widen transmitter range. However, '''this is not recommended''' as it could break local laws and cause interference with other radio devices.<br />
<br />
The kernel loads the database directly when {{Pkg|wireless-regdb}} is [[install]]ed. For direct loading, the kernel should, for security's sake, be configured with {{ic|CONFIG_CFG80211_USE_KERNEL_REGDB_KEYS}} set to yes to allow for cryptographic verification of the database. This is true of the stock Arch kernel, but if you are using an alternate kernel, or compiling your own, you should verify this. More information is available at [http://docker.hd-wireless.com/Support/WifiRegulatoryDomainsinLinux this guide].<br />
<br />
To configure the regdomain, install {{Pkg|wireless-regdb}} and reboot, then edit {{ic|/etc/conf.d/wireless-regdom}} and uncomment the appropriate domain.<br />
<br />
The current regdomain can be temporarily set to the United States with:<br />
<br />
# iw reg set US<br />
<br />
And queried with:<br />
<br />
$ iw reg get<br />
<br />
{{Note|Your device may be set to country "00", which is the "world regulatory domain" and contains generic settings. If this cannot be unset, check your configuration as detailed bellow.}}<br />
<br />
However, setting the regdomain may not alter your settings. Some devices have a regdomain set in firmware/EEPROM, which dictates the limits of the device, meaning that setting regdomain in software [https://wiki.openwrt.org/doc/howto/wireless.utilities#iw can only increase restrictions], not decrease them. For example, a CN device could be set in software to the US regdomain, but because CN has an EIRP maximum of 20dBm, the device will not be able to transmit at the US maximum of 30dBm.<br />
<br />
For example, to see if the regdomain is being set in firmware for an Atheros device:<br />
<br />
# dmesg | grep ath:<br />
<br />
For other chipsets, it may help to search for "EEPROM", "regdomain", or simply the name of the device driver.<br />
<br />
To see if your regdomain change has been successful, and to query the number of available channels and their allowed transmit power:<br />
<br />
$ iw list | grep -A 15 Frequencies:<br />
<br />
[[wpa_supplicant]] can also use a regdomain in the {{ic|1=country=}} line of {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}.<br />
<br />
It is also possible to configure the [https://wireless.wiki.kernel.org/en/developers/documentation/cfg80211 cfg80211] kernel module to use a specific regdomain by adding, for example, {{ic|1=options cfg80211 ieee80211_regdom=JP}} as [[Kernel modules#Setting module options|module options]]. The module option is inherited from the [https://wireless.wiki.kernel.org/en/developers/regulatory#the_ieee80211_regdom_module_parameter old regulatory implementation] and in modern kernels act as a userspace regulatory hint as if it came through {{ic|nl80211}} through utilities like {{ic|iw}} and {{ic|wpa_supplicant}}.<br />
<br />
=== Rfkill caveat ===<br />
<br />
Many laptops have a hardware button (or switch) to turn off the wireless card; however, the card can also be blocked by the kernel. This can be handled by ''rfkill''. To show the current status:<br />
<br />
{{hc|$ rfkill|<br />
ID TYPE DEVICE SOFT HARD<br />
0 bluetooth hci0 unblocked unblocked<br />
1 wlan phy0 unblocked unblocked<br />
}}<br />
<br />
If the card is ''hard-blocked'', use the hardware button (switch) to unblock it. If the card is not ''hard-blocked'' but ''soft-blocked'', use the following command:<br />
<br />
# rfkill unblock wlan<br />
<br />
{{Note|It is possible that the card will go from ''hard-blocked'' and ''soft-unblocked'' state into ''hard-unblocked'' and ''soft-blocked'' state by pressing the hardware button (i.e. the ''soft-blocked'' bit is just switched no matter what). This can be adjusted by tuning some options of the {{ic|rfkill}} [[kernel module]].}}<br />
<br />
Hardware buttons to toggle wireless cards are handled by a vendor specific [[kernel module]]. Frequently, these are [https://lwn.net/Articles/391230/ WMI] modules. Particularly for very new hardware models, it happens that the model is not fully supported in the latest stable kernel yet. In this case, it often helps to search the kernel bug tracker for information and report the model to the maintainer of the respective vendor kernel module, if it has not happened already. <br />
<br />
See also [https://askubuntu.com/questions/62166/siocsifflags-operation-not-possible-due-to-rf-kill].<br />
<br />
=== Power saving ===<br />
<br />
See [[Power saving#Network interfaces]].<br />
<br />
== Troubleshooting ==<br />
<br />
This section contains general troubleshooting tips, not strictly related to problems with drivers or firmware. For such topics, see next section [[#Troubleshooting drivers and firmware]].<br />
<br />
=== Temporary internet access ===<br />
<br />
If you have problematic hardware and need internet access to, for example, download some software or get help in forums, you can make use of Android's built-in feature for internet sharing via USB cable. See [[Android tethering#USB tethering]] for more information.<br />
<br />
=== Observing logs ===<br />
<br />
A good first measure to troubleshoot is to analyze the system's logfiles first. In order not to manually parse through them all, it can help to open a second terminal/console window and watch the kernels messages with <br />
<br />
# dmesg -w<br />
<br />
while performing the action, e.g. the wireless association attempt. <br />
<br />
When using a tool for network management, the same can be done for systemd with <br />
<br />
# journalctl -f <br />
<br />
Frequently, a wireless error is accompanied by a deauthentication with a particular reason code, for example: <br />
<br />
wlan0: deauthenticating from XX:XX:XX:XX:XX:XX by local choice (reason=3)<br />
<br />
Looking up [http://www.aboutcher.co.uk/2012/07/linux-wifi-deauthenticated-reason-codes/ the reason code] might give a first hint. Maybe it also helps you to look at the control message [https://wireless.wiki.kernel.org/en/developers/documentation/mac80211/auth-assoc-deauth flowchart], the journal messages will follow it. <br />
<br />
The individual tools used in this article further provide options for more detailed debugging output, which can be used in a second step of the analysis, if required.<br />
<br />
=== Failed to get IP address ===<br />
<br />
{{Accuracy|The {{Pkg|dhcpcd}} vs {{Pkg|dhclient}} is mostly FUD.}}<br />
{{Out of date|''iwconfig'' is deprecated, see [[#iw and wireless tools comparison]].}}<br />
<br />
* If getting an IP address repeatedly fails using the default {{Pkg|dhcpcd}} client, try installing and using {{Pkg|dhclient}} instead. Do not forget to select ''dhclient'' as the primary DHCP client in the [[#Manual/automatic setup|connection manager]].<br />
<br />
* If you can get an IP address for a wired interface and not for a wireless interface, try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
* If you get a timeout error due to a ''waiting for carrier'' problem, then you might have to set the channel mode to {{ic|auto}} for the specific device:<br />
<br />
# iwconfig wlan0 channel auto<br />
<br />
Before changing the channel to auto, make sure your wireless interface is down. After it has successfully changed it, you can bring the interface up again and continue from there.<br />
<br />
=== Valid IP address but cannot resolve host ===<br />
<br />
If you are on a public wireless network that may have a [[wikipedia:Captive_portal|captive portal]], make sure to query an HTTP page (not an HTTPS page) from your web browser, as some captive portals only redirect HTTP.<br />
If this is not the issue, [[Domain name resolution#Resolve a domain name using NSS|check if you can resolve domain names]], it may be necessary to use the DNS server advertised via DHCP.<br />
<br />
=== Setting RTS and fragmentation thresholds ===<br />
<br />
Wireless hardware disables RTS and fragmentation by default. These are two different methods of increasing throughput at the expense of bandwidth (i.e. reliability at the expense of speed). These are useful in environments with wireless noise or many adjacent access points, which may create interference leading to timeouts or failing connections. <br />
<br />
Packet fragmentation improves throughput by splitting up packets with size exceeding the fragmentation threshold. The maximum value (2346) effectively disables fragmentation since no packet can exceed it. The minimum value (256) maximizes throughput, but may carry a significant bandwidth cost.<br />
<br />
# iw phy0 set frag 512<br />
<br />
[[Wikipedia:IEEE 802.11 RTS/CTS|RTS]] improves throughput by performing a handshake with the access point before transmitting packets with size exceeding the RTS threshold. The maximum threshold (2347) effectively disables RTS since no packet can exceed it. The minimum threshold (0) enables RTS for all packets, which is probably excessive for most situations.<br />
<br />
# iw phy0 set rts 500<br />
<br />
{{Note|{{ic|phy0}} is the name of the wireless device as listed by {{ic|iw phy}}.}}<br />
<br />
=== Random disconnections ===<br />
<br />
==== Cause #1 ====<br />
<br />
If your [[journal]] says {{ic|1=wlan0: deauthenticating from MAC by local choice (reason=3)}} and you lose your Wi-Fi connection, it is likely that you have a bit too aggressive power-saving on your Wi-Fi card. Try disabling the wireless card's [[Power management#Network interfaces|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
If your card does not support enabling/disabling power save mode, check the BIOS for power management options. Disabling PCI-Express power management in the BIOS of a Lenovo W520 resolved this issue.<br />
<br />
==== Cause #2 ====<br />
<br />
If you are experiencing frequent disconnections and your [[journal]] shows messages such as <br />
<br />
{{ic|1=ieee80211 phy0: wlan0: No probe response from AP xx:xx:xx:xx:xx:xx after 500ms, disconnecting}}<br />
<br />
try changing the channel bandwidth to {{ic|20MHz}} through your router's settings page.<br />
<br />
==== Cause #3 ====<br />
<br />
On some laptop models with hardware rfkill switches (e.g., Thinkpad X200 series), due to wear or bad design, the switch (or its connection to the mainboard) might become loose over time resulting in seemingly random hardblocks/disconnects when you accidentally touch the switch or move the laptop.<br />
There is no software solution to this, unless your switch is electrical and the BIOS offers the option to disable the switch.<br />
If your switch is mechanical (and most are), there are lots of possible solutions, most of which aim to disable the switch: Soldering the contact point on the mainboard/wifi-card, gluing or blocking the switch, using a screw nut to tighten the switch or removing it altogether.<br />
<br />
==== Cause #4 ====<br />
<br />
Another cause for frequent disconnects or a complete failure to connect may also be a sub-standard router, incomplete settings of the router, interference by other wireless devices or low quality signal. <br />
<br />
To troubleshoot, first try to connect to the router with no authentication and by getting closer to it. <br />
<br />
If that works, enable WPA/WPA2 again but choose fixed and/or limited router settings. For example: <br />
* If the router is considerably older than the wireless device you use for the client, test if it works with setting the router to one wireless mode <br />
* Disable mixed-mode authentication (e.g. only WPA2 with AES, or TKIP if the router is old) <br />
* Try a fixed/free channel rather than "auto" channel (maybe the router next door is old and interfering) <br />
* Disable [[Wikipedia:Wi-Fi Protected Setup|WPS]]<br />
* Change the router's 5 GHz channel(s) to a [[Wikipedia:List of WLAN channels#5 GHz (802.11a/h/j/n/ac/ax)|non-DFS (Dynamic Frequency Selection) channel]]. Connections on such channels [https://wifinigel.blogspot.com/2018/05/the-5ghz-problem-for-wi-fi-networks-dfs.html may be dropped or suddenly switched] due to interference from nearby weather radar.<br />
* Try setting your client to 2.4 GHz only instead of letting it choose what it thinks is best between 5 GHz and 2.4 GHz (the later has a lower throughput but will provide a more stable connection over longer distances)<br />
* Disable {{ic|40MHz}} channel bandwidth (lower throughput but less likely collisions) with {{ic|1=cfg80211.cfg80211_disable_40mhz_24ghz=1}}<br />
* If the router has quality of service settings, check completeness of settings (e.g. Wi-Fi Multimedia (WMM) is part of optional QoS flow control. An erroneous router firmware may advertise its existence although the setting is not enabled)<br />
<br />
==== Cause #5 ====<br />
<br />
On some wireless network adapters (e.g. Qualcomm Atheros AR9485), random disconnects can happen with a DMA error:<br />
<br />
{{hc|# journalctl -xb|2=<br />
ath: phy0: DMA failed to stop in 10 ms AR_CR=0x00000024 AR_DIAG_SW=0x02000020 DMADBG_7=0x0000a400<br />
wlp1s0: authenticate with 56:e7:ee:7b:55:bc<br />
wlp1s0: send auth to 56:e7:ee:7b:55:bc (try 1/3)<br />
wlp1s0: send auth to 56:e7:ee:7b:55:bc (try 2/3)<br />
wlp1s0: send auth to 56:e7:ee:7b:55:bc (try 3/3)<br />
wlp1s0: authentication with 56:e7:ee:7b:55:bc timed out<br />
}}<br />
<br />
A possible workaround is to disable the [https://docs.kernel.org/x86/iommu.html Intel IOMMU driver (DMA)], adding {{ic|1=intel_iommu=off}} to the [[kernel parameters]] [https://bbs.archlinux.org/viewtopic.php?pid=1907446#p1907446].<br />
<br />
{{Note|The Intel IOMMU driver is needed for some advanced virtual machine features, like PCI pass-through.}}<br />
<br />
==== Cause #6 ====<br />
<br />
If you are using a device with {{ic|iwlwifi}} and {{ic|iwlmvm}} for wireless connectivity, and your Wi-Fi card appears to disappear when on battery power (perhaps after a reboot or resuming from suspend), this can be fixed by configuring power saving settings in iwlmvm.<br />
<br />
Create the file {{ic|/etc/modprobe.d/iwlmvm.conf}} if it does not exist already, then add the following line to it:<br />
<br />
{{hc|/etc/modprobe.d/iwlmvm.conf|2=<br />
options iwlmvm power_scheme=1<br />
}}<br />
<br />
A {{ic|power_scheme}} of 1 sets iwlmvm to "Always Active." Available options are:<br />
<br />
{| class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 1 || Always Active<br />
|-<br />
| 2 || Balanced<br />
|-<br />
| 3 || Low-power<br />
|}<br />
<br />
This fix was discovered at [https://forums.debian.net/viewtopic.php?t=121696#p576208].<br />
<br />
==== Cause #7 ====<br />
<br />
If your device undergoes long periods of inactivity (e.g. a file server), the disconnection may be due to power saving, which will block incoming traffic and prevent connections. Try disabling power saving for the interface:<br />
<br />
# iw dev ''interface'' set power_save off<br />
<br />
You can create a udev rule to do this on boot, see [[Power management#Network interfaces]].<br />
<br />
==== Cause #8 ====<br />
<br />
If you notice occasional interruptions when connected to a mesh network (e.g., WiFi6) and notice a message such as:<br />
<br />
{{hc|# journalctl -b|<br />
kernel: wlan0: disconnect from AP aa:bb:cc:dd:ee:ff for new auth to 11:22:33:44:55:66<br />
}}<br />
<br />
You are experiencing roaming issues. Depending on your mean of connection and the issue at hand, one could:<br />
<br />
* Lock the BSSID (the {{ic|aa:bb:cc:dd:ee:ff}} show above) in NetworkManager if roaming is not desired (see [[NetworkManager#Regular network disconnects, latency and lost packets (WiFi)]]).<br />
* Adjust the {{ic|bgscan}} setting in [[Wpa_supplicant#Roaming]]<br />
<br />
=== Wi-Fi networks invisible because of incorrect regulatory domain ===<br />
<br />
If the computer's Wi-Fi channels do not match those of the user's country, some in-range Wi-Fi networks might be invisible because they use wireless channels that are not allowed by default. The solution is to configure the regulatory domain correctly; see [[#Respecting the regulatory domain]].<br />
<br />
== Troubleshooting drivers and firmware ==<br />
<br />
This section covers methods and procedures for installing kernel modules and ''firmware'' for specific chipsets, that differ from generic method.<br />
<br />
See [[Kernel modules]] for general information on operations with modules.<br />
<br />
=== Ralink/Mediatek ===<br />
<br />
==== rt2x00 ====<br />
<br />
Unified driver for Ralink chipsets (it replaces {{ic|rt2500}}, {{ic|rt61}}, {{ic|rt73}}, etc). This driver has been in the Linux kernel since 2.6.24, you only need to load the right module for the chip: {{ic|rt2400pci}}, {{ic|rt2500pci}}, {{ic|rt2500usb}}, {{ic|rt61pci}} or {{ic|rt73usb}} which will autoload the respective {{ic|rt2x00}} modules too.<br />
<br />
A list of devices supported by the modules is available at the project's [https://web.archive.org/web/20150507023412/http://rt2x00.serialmonkey.com/wiki/index.php/Hardware homepage].<br />
<br />
; Additional notes<br />
* Since kernel 3.0, rt2x00 includes also these drivers: {{ic|rt2800pci}}, {{ic|rt2800usb}}.<br />
* Since kernel 3.0, the staging drivers {{ic|rt2860sta}} and {{ic|rt2870sta}} are replaced by the mainline drivers {{ic|rt2800pci}} and {{ic|rt2800usb}} [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=fefecc6989b4b24276797270c0e229c07be02ad3].<br />
* Some devices have a wide range of options that can be configured with {{ic|iwpriv}}. These are documented in the [https://web.archive.org/web/20111105120212/http://web.ralinktech.com:80/ralink/Home/Support/Linux.html source tarballs] available from Ralink.<br />
<br />
==== rt3090 ====<br />
<br />
For devices which use the rt3090 chipset, it should be possible to use the {{ic|rt2800pci}} driver; however, it does not work with this chipset very well (e.g. sometimes it is not possible to use higher rate than 2Mb/s).<br />
<br />
==== rt3290 ====<br />
<br />
The rt3290 chipset is recognised by the kernel {{ic|rt2800pci}} module. However, some users experience problems and reverting to a patched Ralink driver seems to be beneficial in these [https://bbs.archlinux.org/viewtopic.php?id=161952 cases].<br />
<br />
==== rt3573 ====<br />
<br />
New chipset as of 2012. It may require proprietary drivers from Ralink. Different manufacturers use it; see the [https://bbs.archlinux.org/viewtopic.php?pid=1164228#p1164228 Belkin N750 DB wireless usb adapter] forums thread.<br />
<br />
==== mt7612u ====<br />
<br />
New chipset as of 2014, released under their new commercial name Mediatek. It is an AC1200 or AC1300 chipset. Manufacturer provides drivers for Linux on their [https://www.mediatek.com/products/broadbandWifi/mt7612u support page]. As of kernel 5.5 it should be supported by the included {{ic|mt76}} driver.<br />
<br />
=== Realtek ===<br />
<br />
See [https://wikidevi.com/wiki/Realtek]{{Dead link|2022|11|10}} for a list of Realtek chipsets and specifications.<br />
<br />
==== rtl8192cu ====<br />
<br />
The driver is now in the kernel, but many users have reported being unable to make a connection although scanning for networks does work.<br />
<br />
{{AUR|8192cu-dkms}} includes many patches; try this if it does not work fine with the driver in kernel.<br />
<br />
==== rtl8723ae/rtl8723be ====<br />
<br />
The {{ic|rtl8723ae}} and {{ic|rtl8723be}} modules are included in the mainline Linux kernel.<br />
<br />
Some users may encounter errors with powersave on this card. This is shown with occasional disconnects that are not recognized by high level network managers ([[netctl]], [[NetworkManager]]). This error can be confirmed by running {{ic|dmesg -w}} as root or {{ic|journalctl -f}} as root and looking for output related to powersave and the {{ic|rtl8723ae}}/{{ic|rtl8723be}} module. If you have this issue, use the {{ic|1=fwlps=0}} kernel option which should prevent the WiFi card from automatically sleeping and halting connection. See [[Kernel module#Setting module options]].<br />
<br />
If you have poor signal, perhaps your device has only one physical antenna connected, and antenna autoselection is broken. You can force the choice of antenna with {{ic|1=ant_sel=1}} or {{ic|1=ant_sel=2}} kernel option. [https://bbs.archlinux.org/viewtopic.php?id=208472]<br />
<br />
==== rtl88xxau ====<br />
<br />
Realtek chipsets rtl8811au, rtl8812au, rtl8814au and rtl8821au designed for various USB adapters ranging from AC600 to AC1900. Several packages provide various kernel drivers, these require [[DKMS]] (the {{Pkg|dkms}} package and the kernel headers installed):<br />
<br />
{| class="wikitable"<br />
! Chipset || Package || Notes<br />
|-<br />
| rtl8811au, rtl8812au, rtl8821au || {{AUR|rtl88xxau-aircrack-dkms-git}} || Aircrack-ng kernel module for 8811au, 8812au and 8821au chipsets with monitor mode and injection support.<br />
|-<br />
| rtl8812au || {{AUR|rtl8812au-dkms-git}} || Latest official Realtek driver version for rtl8812au '''only'''.<br />
|-<br />
| rtl8811au, rtl8821au || {{AUR|rtl8821au-dkms-git}} || Newer driver version for rtl8821au.<br />
|-<br />
| rtl8814au || {{AUR|rtl8814au-dkms-git}} || Possibly works for rtl8813au too. <br />
|}<br />
<br />
==== rtl8811cu/rtl8821cu ====<br />
<br />
{{AUR|rtl8821cu-dkms-git}} provides a kernel module for the Realtek 8811cu and 8821cu chipset.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
If no wireless interface shows up even though the {{ic|8821cu}} module is loaded, you may need to manually specify the {{ic|rtw_RFE_type}} option [https://forums.linuxmint.com/viewtopic.php?p=1913190&sid=68f2d6eff91cd47e184ae5a56385dc02#p1913190][https://github.com/brektrou/rtl8821CU/issues/83]. Try e.g. {{ic|1=rtw_RFE_type=0x26}}, other values might also work. See [[Kernel module#Setting module options]] for details.<br />
<br />
==== rtl8821ce ====<br />
<br />
{{AUR|rtl8821ce-dkms-git}} provides a kernel module for the Realtek 8821ce chipset found in the Asus X543UA.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
{{Note|1=It has been reported [https://bbs.archlinux.org/viewtopic.php?id=273440] that the default {{ic|rtl8821ce}} module provided by Realtek is broken for Linux kernel ≥ 5.9, which may lead to low connectivity. The AUR version above should be preferred. See [https://github.com/tomaspinho/rtl8821ce#wi-fi-not-working-for-kernel--59 the statement on GitHub.] Use {{ic|lspci -k}} to check whether the default kernel driver ({{ic|rtw88_8821ce}}) is in use. If it is, [[blacklist]] it and reboot your system.}}<br />
<br />
==== rtl8822bu ====<br />
<br />
{{AUR|rtl88x2bu-dkms-git}} provides a kernel module for the Realtek 8822bu chipset found in the Edimax EW7822ULC USB3, Asus AC53 Nano USB 802.11ac and TP-Link Archer T3U adapter.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8xxxu ====<br />
<br />
{{Expansion|Specific issues with the mainline module and kernel versions should be stated.}}<br />
<br />
Issues with the {{ic|rtl8xxxu}} mainline kernel module may be solved by compiling a third-party module for the specific chipset. The source code can be found in [https://github.com/lwfinger?tab=repositories GitHub repositories].<br />
<br />
Some drivers may be already prepared in the AUR, e.g. {{AUR|rtl8723bu-dkms-git}}.<br />
<br />
==== RTW88 ====<br />
<br />
An RTW88 kernel module patchset has been recently posted to the kernel mailing list, which should hopefully make it into the mainstream kernel.<br />
<br />
Upstream kernels or those with the patchset will support most RTW88 chip devices if configured and compiled to do so. {{Pkg|linux-zen}} and {{AUR|linux-zen-git}} both include these patches, with the packaged version already having the module built.<br />
<br />
The driver supports: 882BE, 8822BU, 8822CE, 8822CU, 8723DE, 8723DU, 8821CE, and 8821CU.<br />
<br />
=== Atheros ===<br />
<br />
The [http://madwifi-project.org/ MadWifi team] currently maintains three different drivers for devices with Atheros chipset:<br />
<br />
* {{ic|madwifi}} is an old, obsolete driver. Not present in Arch kernel since 2.6.39.1[https://lists.archlinux.org/archives/list/arch-dev-public@lists.archlinux.org/message/N5VBSKHSPV72HLNSZHPZXEBENOSB542C/].<br />
* {{ic|ath5k}} is a newer driver which replaces the {{ic|madwifi}} driver. Currently a better choice for some chipsets, but not all chipsets are supported (see below)<br />
* {{ic|ath9k}} is the newest of these three drivers. It is intended for newer Atheros chipsets. All of the chips with 802.11n capabilities are supported.<br />
<br />
There are some other drivers for some Atheros devices. See [https://wireless.wiki.kernel.org/en/users/Drivers/Atheros#pcipci-eahb_driversrs Linux Wireless documentation] for details.<br />
<br />
==== ath5k ====<br />
<br />
External resources:<br />
* https://wireless.wiki.kernel.org/en/users/drivers/ath5k<br />
* [[Debian:ath5k]]<br />
<br />
If you find web pages randomly loading very slow, or if the device is unable to lease an IP address, try to switch from hardware to software encryption by loading the {{ic|ath5k}} module with {{ic|1=nohwcrypt=1}} option. See [[Kernel modules#Setting module options]] for details.<br />
<br />
Some laptops may have problems with their wireless LED indicator flickering red and blue. To solve this problem, do:<br />
<br />
# echo none > /sys/class/leds/ath5k-phy0::tx/trigger<br />
# echo none > /sys/class/leds/ath5k-phy0::rx/trigger<br />
<br />
For alternatives, see [https://bugzilla.redhat.com/show_bug.cgi?id=618232 this bug report].<br />
<br />
==== ath9k ====<br />
<br />
External resources:<br />
* https://wireless.wiki.kernel.org/en/users/drivers/ath9k<br />
* [[Debian:ath9k]]<br />
<br />
As of Linux 3.15.1, some users have been experiencing a decrease in bandwidth. In some cases, this can fixed by setting the {{ic|1=nohwcrypt=1}} option for the {{ic|ath9k}} module. See [[Kernel module#Setting module options]].<br />
<br />
{{Note|Use the command {{ic|lsmod}} to see what modules are in use and change {{ic|ath9k}} if it is named differently (e.g. {{ic|ath9k_htc}}).}}<br />
<br />
An [https://web.archive.org/web/20201118232556/http://lists.ath9k.org/mailman/listinfo/ath9k-devel ath9k mailing list] exists for support and development related discussions.<br />
<br />
===== Power saving =====<br />
<br />
Although [https://wireless.wiki.kernel.org/en/users/Documentation/dynamic-power-save Linux Wireless] says that dynamic power saving is enabled for Atheros ath9k single-chips newer than AR9280, for some devices (e.g. AR9285), {{Pkg|powertop}} might still report that power saving is disabled. In this case, enable it manually.<br />
<br />
On some devices (e.g. AR9285), enabling the power saving might result in the following error:<br />
<br />
{{hc|# iw dev wlan0 set power_save on|<br />
command failed: Operation not supported (-95)<br />
}}<br />
<br />
The solution is to set the {{ic|1=ps_enable=1}} option for the {{ic|ath9k}} module; see [[Kernel module#Setting module options]].<br />
<br />
=== Intel ===<br />
<br />
==== iwlegacy ====<br />
<br />
[https://wireless.wiki.kernel.org/en/users/Drivers/iwlegacy iwlegacy] is the wireless driver for Intel's 3945 and 4965 wireless chips. The firmware is included in the {{Pkg|linux-firmware}} package.<br />
<br />
[[udev]] should load the driver automatically, otherwise load {{ic|iwl3945}} or {{ic|iwl4965}} manually. See [[Kernel modules]] for details.<br />
<br />
If you have problems connecting to networks in general (e.g. random failures with your card on bootup or your link quality is very poor), try to disable 802.11n:<br />
<br />
{{hc|/etc/modprobe.d/iwl4965.conf|2=<br />
options iwl4965 11n_disable=1<br />
}}<br />
<br />
If the failures persist during bootup and you are using Nouveau driver, try [[Nouveau#Enable early KMS|enabling early KMS]] to prevent the conflict [https://bbs.archlinux.org/viewtopic.php?pid=1748667#p1748667].<br />
<br />
==== iwlwifi ====<br />
<br />
[https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi iwlwifi] is the wireless driver for Intel's current wireless chips, such as 5100AGN, 5300AGN, and 5350AGN. See the [https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi#supported_devices full list of supported devices]. The firmware is included in the {{Pkg|linux-firmware}} package. The {{AUR|linux-firmware-iwlwifi-git}} may contain some updates sooner.<br />
<br />
If you have problems connecting to networks in general or your link quality is very poor, try to disable 802.11n, and perhaps also enable software encryption:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=1 swcrypto=1<br />
}}<br />
<br />
If you have a problem with slow uplink speed in 802.11n mode, for example 20Mbps, try to enable antenna aggregation:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=8<br />
}}<br />
<br />
Do not be confused with the option name, when the value is set to {{ic|8}} it does not disable anything but re-enables transmission antenna aggregation.[https://forums.gentoo.org/viewtopic-t-996692.html?sid=81bdfa435c089360bdfd9368fe0339a9] [https://bugzilla.kernel.org/show_bug.cgi?id=81571]<br />
<br />
In case this does not work for you, you may try disabling [[Power saving#Network interfaces|power saving]] for your wireless adapter.<br />
<br />
[https://ubuntuforums.org/showthread.php?t=2183486&p=12845473#post12845473 Some] have never gotten this to work. [https://ubuntuforums.org/showthread.php?t=2205733&p=12935783#post12935783 Others] found salvation by disabling N in their router settings after trying everything. This is known to have been the only solution on more than one occasion. The second link there mentions a 5ghz option that might be worth exploring.<br />
<br />
If you have an 802.11ax (WiFi 6) access point and have problems detecting the beacons or an unreliable connection, review [https://www.intel.com/content/www/us/en/support/articles/000054799/network-and-i-o/wireless.html Intel Article 54799].<br />
<br />
{{Note|Using {{ic|1=11n_disable=0}} will also prevent 802.11ac and only allow connection with slower protocols (802.11a in the 5GHz band or 802.11b/g in the 2.4 GHz band).}}<br />
<br />
===== Bluetooth coexistence =====<br />
<br />
If you have difficulty connecting a bluetooth headset and maintaining good downlink speed, try disabling bluetooth coexistence [https://wireless.wiki.kernel.org/en/users/Drivers/iwlwifi#wi-fibluetooth_coexistence]:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi bt_coex_active=0<br />
}}<br />
<br />
{{Note|Since kernel version 5.8, the {{ic|bt_coex_active}} and {{ic|sw_crypto}} module options have been disabled for the hardware handled by the {{ic|iwlmvm}} kernel module. For older hardware handled by the {{ic|iwldvm}} module, the options are still enabled.}}<br />
<br />
===== Firmware issues =====<br />
<br />
You may have some issue where the driver outputs stack traces & errors, which can cause some stuttering.<br />
<br />
{{hc|# dmesg|2=<br />
Microcode SW error detected. Restarting 0x2000000.<br />
}}<br />
<br />
Alternatively, you may simply experience miscellaneous issues (e.g. [https://www.reddit.com/r/archlinux/comments/x0v5jj/rant_intel_wifi_firmwares_are_utter_garbage/ connection issues on 5GHz, random disconnections, no connection on resume]).<br />
<br />
To confirm it is the cause of the issues, [[downgrade]] the package {{Pkg|linux-firmware}}. <br />
<br />
If confirmed, move the buggy firmware files so that an older version is loaded (to be able to have an up to date {{Pkg|linux-firmware}} since it is not only providing firmware updates for your Intel WiFi card): <br />
<br />
# for i in {64..73} ; do mv /usr/lib/firmware/iwlwifi-ty-a0-gf-a0-$i.ucode.xz /usr/lib/firmware/iwlwifi-ty-a0-gf-a0-$i.ucode.xz.bak ; done<br />
<br />
To avoid having to repeat these steps manually after each update, use the {{ic|NoExtract}} array in {{ic|pacman.conf}} with a wildcard to block their installation. See [[pacman#Skip files from being installed to system]].<br />
<br />
===== Adapter not detected after booting from Windows =====<br />
<br />
If the WiFi adapter is not getting detected after finishing a session in Windows, this might be due to Windows' '''Fast Startup''' feature which is enabled by default. Try [[Dual boot with Windows#Windows settings|disabling Fast Startup]]. The [https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi#about_dual-boot_with_windows_and_fast-boot_enabled iwlwifi kernel driver wiki has an entry for this].<br />
<br />
==== Disabling LED blink ====<br />
<br />
{{Note|This works with the {{ic|iwlegacy}} and {{ic|iwlwifi}} drivers.}}<br />
<br />
The default settings on the module are to have the LED blink on activity. Some people find this extremely annoying. To have the LED on solid when Wi-Fi is active, you can use the [[systemd-tmpfiles]]:<br />
<br />
{{hc|/etc/tmpfiles.d/phy0-led.conf|<br />
w /sys/class/leds/phy0-led/trigger - - - - phy0radio<br />
}}<br />
<br />
Run {{ic|systemd-tmpfiles --create phy0-led.conf}} for the change to take effect, or reboot.<br />
<br />
To see all the possible trigger values for this LED:<br />
<br />
# cat /sys/class/leds/phy0-led/trigger<br />
<br />
{{Tip|If you do not have {{ic|/sys/class/leds/phy0-led}}, you may try to use the {{ic|1=led_mode="1"}} [[Kernel modules#Setting module options|module option]]. It should be valid for both {{ic|iwlwifi}} and {{ic|iwlegacy}} drivers.}}<br />
<br />
=== Broadcom ===<br />
<br />
See [[Broadcom wireless]].<br />
<br />
=== Other drivers/devices ===<br />
<br />
==== Tenda w322u ====<br />
<br />
Treat this Tenda card as an {{ic|rt2870sta}} device. See [[#rt2x00]].<br />
<br />
==== orinoco ====<br />
<br />
This should be a part of the kernel package and be installed already.<br />
<br />
Some Orinoco chipsets are Hermes II. You can use the {{ic|wlags49_h2_cs}} driver instead of {{ic|orinoco_cs}} and gain WPA support. To use the driver, [[blacklist]] {{ic|orinoco_cs}} first.<br />
<br />
==== prism54 ====<br />
<br />
The driver {{ic|p54}} is included in kernel, but you have to download the appropriate firmware for your card from [https://wireless.wiki.kernel.org/en/users/drivers/p54#firmware this site] and install it into the {{ic|/usr/lib/firmware}} directory.<br />
<br />
{{Note|There is also an older, deprecated driver {{ic|prism54}}, which might conflict with the newer driver ({{ic|p54pci}} or {{ic|p54usb}}). Make sure to [[blacklist]] {{ic|prism54}}.}}<br />
<br />
==== zd1211rw ====<br />
<br />
[https://sourceforge.net/projects/zd1211/ zd1211rw] is a driver for the ZyDAS ZD1211 802.11b/g USB WLAN chipset, and it is included in recent versions of the Linux kernel. See [https://wireless.wiki.kernel.org/en/users/Drivers/zd1211rw/devices] for a list of supported devices. You only need to [[install]] the firmware for the device, provided by the {{AUR|zd1211-firmware}} package.<br />
<br />
==== hostap_cs ====<br />
<br />
[https://hostap.epitest.fi/ Host AP] is a Linux driver for wireless LAN cards based on Intersil's Prism2/2.5/3 chipset. The driver is included in Linux kernel.<br />
<br />
{{Note|Make sure to [[blacklist]] the {{ic|orinico_cs}} driver, it may cause problems.}}<br />
<br />
=== ndiswrapper ===<br />
<br />
Ndiswrapper is a wrapper script that allows you to use some Windows drivers in Linux. You will need the ''.inf'' and ''.sys'' files from your Windows driver. <br />
<br />
{{Note|Be sure to use drivers appropriate to your architecture (x86 vs. x86_64).}}<br />
<br />
{{Tip|If you need to extract these files from an ''.exe'' file, you can use {{Pkg|cabextract}}.}}<br />
<br />
Follow these steps to configure ndiswrapper.<br />
<br />
# Install {{Pkg|ndiswrapper-dkms}}.<br />
# Install the driver to {{ic|/etc/ndiswrapper/}}: {{bc|# ndiswrapper -i filename.inf}}<br />
# List all installed drivers for ndiswrapper: {{bc|$ ndiswrapper -l}}<br />
# Let ndiswrapper write its configuration in {{ic|/etc/modprobe.d/ndiswrapper.conf}}:{{bc|# ndiswrapper -m<br># depmod -a}}<br />
<br />
The ndiswrapper install is almost finished; you can [[load the module at boot]].<br />
<br />
Test that ndiswrapper will load now:<br />
<br />
# modprobe ndiswrapper<br />
# iwconfig<br />
<br />
and ''wlan0'' should now exist. If you have problems, some help is available at:<br />
[https://sourceforge.net/p/ndiswrapper/ndiswrapper/HowTos/ ndiswrapper howto] and [https://sourceforge.net/p/ndiswrapper/ndiswrapper/FAQ/ ndiswrapper FAQ].<br />
<br />
== See also ==<br />
<br />
* [https://wireless.wiki.kernel.org/ The Linux Wireless project]<br />
* [https://aircrack-ng.org/doku.php?id=install_drivers Aircrack-ng guide on installing drivers]<br />
* [https://wikidevi.wi-cat.ru Wireless Device Database Wiki] (This fork is hosted by wi-cat.ru since the original wiki has shut down. There are two less complete versions available: [http://en.techinfodepot.shoutwiki.com TechInfoDepot], [https://deviwiki.com/ deviwiki])</div>Iaz3https://wiki.archlinux.org/index.php?title=Chromium&diff=767301Chromium2023-02-11T08:13:30Z<p>Iaz3: /* KDE integration */ The plasma browser integration package already includes the extension for both chromium and google chrome, with no further action needed. https://developer.chrome.com/docs/extensions/mv3/external_extensions/#preference-linux</p>
<hr />
<div>[[Category:Web browser]]<br />
[[Category:Google]]<br />
[[de:Chromium]]<br />
[[ja:Chromium]]<br />
[[zh-hans:Chromium]]<br />
{{Related articles start}}<br />
{{Related|Browser extensions}}<br />
{{Related|Firefox}}<br />
{{Related|Opera}}<br />
{{Related|Vivaldi}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Chromium (web browser)|Chromium]] is an open-source graphical web browser based on the [[Wikipedia:Blink (web engine)|Blink]] rendering engine. It is the basis for the proprietary Google Chrome browser.<br />
<br />
See [https://chromium.googlesource.com/chromium/src/+/master/docs/chromium_browser_vs_google_chrome.md this page] for an explanation of the differences between Chromium and Google Chrome. Additionally:<br />
<br />
* Sync is unavailable in Chromium 89+ (2021-03-02) [https://archlinux.org/news/chromium-losing-sync-support-in-early-march/]<br />
<br />
{{Note|Sync can be temporarily restored by [https://gist.github.com/foutrelis/14e339596b89813aa9c37fd1b4e5d9d5 using Chrome's OAuth2 credentials] or [https://www.chromium.org/developers/how-tos/api-keys getting your own], but pay attention to the disclaimers and do not consider this to be a long-term solution.<br />
Consider switching to [https://www.xbrowsersync.org xbrowsersync] for bookmarks syncing as long term solution.<br />
}}<br />
<br />
See [[List of applications/Internet#Blink-based]] for other browsers based on Chromium.<br />
<br />
== Installation ==<br />
<br />
There are several packages available to [[install]] Chromium with:<br />
<br />
* {{Pkg|chromium}} — stable release;<br />
* {{AUR|chromium-dev}} — development release;<br />
* {{AUR|chromium-snapshot-bin}} — nightly build.<br />
<br />
Google Chrome packages:<br />
<br />
* {{AUR|google-chrome}} — stable release;<br />
* {{AUR|google-chrome-beta}} — beta release;<br />
* {{AUR|google-chrome-dev}} — development release.<br />
<br />
{{Note|From the [https://www.chromium.org/Home/chromium-privacy Chromium privacy page]: "Features that communicate with Google made available through the compilation of code in Chromium are subject to the [https://www.google.com/policies/privacy/ Google Privacy Policy]." For those who want to avoid all integration with Google services, there are some [[List of applications/Internet#Privacy-focused chromium spin-offs|privacy-focused spin-offs]].}}<br />
<br />
== Configuration ==<br />
<br />
{{Merge|Chromium#Tips and tricks 2|Most of the content in this section should be split between [[Chromium#Tips and tricks 2]] and maybe [[Chromium#Troubleshooting]] for the applicable sections.}}<br />
<br />
=== Default applications ===<br />
<br />
To set Chromium as the default browser and to change which applications Chromium launches when opening downloaded files, see [[default applications]].<br />
<br />
=== Certificates ===<br />
<br />
Chromium uses [[Network Security Services]] for certificate management. Certificates can be managed in {{ic|chrome://settings/certificates}}.<br />
<br />
=== Making flags persistent ===<br />
<br />
{{Note|The {{ic|chromium-flags.conf}} file and the accompanying custom launcher script are specific to the Arch Linux {{Pkg|chromium}} package. For {{AUR|google-chrome}} and {{AUR|google-chrome-dev}}, use {{ic|chrome-flags.conf}} and {{ic|chrome-dev-flags.conf}} instead.}}<br />
<br />
You can put your flags in a {{ic|chromium-flags.conf}} file under {{ic|$HOME/.config/}} (or under {{ic|$XDG_CONFIG_HOME}} if you have configured that environment variable) or {{ic|/etc/}} for global.<br />
<br />
No special syntax is used; flags are defined as if they were written in a terminal.<br />
<br />
* The arguments are split on whitespace and shell quoting rules apply, but no further parsing is performed.<br />
* In case of improper quoting anywhere in the file, a fatal error is raised.<br />
* Flags can be placed in separate lines for readability, but this is not required.<br />
* Lines starting with a hash symbol (#) are skipped. (This is only supported by the {{Pkg|chromium}} launcher script and will not work when using {{ic|chrome-flags.conf}} with the {{AUR|google-chrome}} package.)<br />
<br />
Below is an example {{ic|chromium-flags.conf}} file that defines the flags {{ic|--start-maximized --incognito}}:<br />
<br />
{{hc|~/.config/chromium-flags.conf|<br />
# This line will be ignored.<br />
--start-maximized<br />
--incognito<br />
}}<br />
<br />
=== Force GPU acceleration ===<br />
<br />
{{Warning|Disabling the rendering blacklist may cause unstable behavior, including crashes of the host. See the bug reports in {{ic|chrome://gpu}} for details.}}<br />
<br />
By default Chromium on Linux does not use any GPU acceleration. To force GPU acceleration, [[append]] the following flags to [[/Tips and tricks#Making flags persistent|persistent configuration]]:<br />
<br />
{{hc|~/.config/chromium-flags.conf|<br />
--ignore-gpu-blocklist<br />
--enable-gpu-rasterization<br />
--enable-zero-copy<br />
}}<br />
<br />
Additionally the flag {{ic|--disable-gpu-driver-bug-workarounds}} may need to be passed to prevent GPU workaround from being used. Flags in {{ic|chrome://gpu}} should state "Hardware accelerated" when configured and available.<br />
<br />
{{Out of date|A fix has been merged into mesa as of May 2021. [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/10850]}}<br />
<br />
{{ic|--enable-native-gpu-memory-buffers}} is broken since mesa 20.1.1 [https://gitlab.freedesktop.org/mesa/mesa/-/issues/3119#note_533902]<br />
<br />
=== Hardware video acceleration ===<br />
<br />
{{Note|1=<nowiki/><br />
* There is no official support from Chromium or Arch Linux for this feature [https://chromium.googlesource.com/chromium/src/+/master/docs/gpu/vaapi.md#vaapi-on-linux]. However, {{Pkg|chromium}} from official repositories is compiled with VA-API support and you may ask for help in [https://bbs.archlinux.org/viewtopic.php?id=244031 the dedicated forum thread].<br />
* VA-API does not work with the {{Pkg|chromium}} package when using the native Wayland backend, but it does work in {{AUR|chromium-wayland-vaapi}}.<br />
}}<br />
<br />
To enable VA-API support in Chromium:<br />
<br />
* Install the correct VA-API driver for your video card and verify VA-API has been enabled and working correctly, see [[Hardware video acceleration]]. For proprietary NVIDIA support, installing {{AUR|libva-vdpau-driver-chromium}} or {{AUR|libva-vdpau-driver-vp9-git}} is required.<br />
* Set the option {{ic|1=--enable-features=VaapiVideoDecoder}}. This is enough when using ANGLE GL renderer and {{Pkg|libva-intel-driver}}.<br />
* When using ANGLE, Chromium forces the older i965 driver and fails when {{Pkg|intel-media-driver}} is used. As a workaround, [[Hardware video acceleration#Configuring VA-API|configure VA-API manually]]. See [https://github.com/intel/media-driver/issues/818] for details.<br />
* To use the system GL renderer on Xorg, use either {{ic|1=--use-gl=egl}} or {{ic|1=--use-gl=desktop}}. On XWayland, use the {{ic|1=--use-gl=egl}} flag.<br />
* If VA-API still does not work, try the {{ic|1=--enable-features=VaapiIgnoreDriverChecks}} or{{ic|1=--disable-features=UseChromeOSDirectVideoDecoder}} flag<br />
<br />
==== Tips and tricks ====<br />
<br />
To check if it is working play a video which is using a codec supported by your VA-API driver (''vainfo'' tells you which codecs are supported, but Chromium will only support VP9 and h264):<br />
<br />
* Open the DevTools by pressing {{ic|Ctrl+Shift+I}} or on the ''Inspect'' button of the context (right-click) menu<br />
* Add the Media inspection tab: ''Hamburger menu > More tools > Media''<br />
* In the newly opened Media tab, look at the hardware decoder state of the video decoder<br />
<br />
Test on a large enough video. Starting with version 86, Chromium on desktop [https://bugs.chromium.org/p/chromium/issues/detail?id=684792 will only accelerate videos larger than 720p].<br />
<br />
To reduce CPU usage while watching YouTube where VP8/VP9 hardware decoding is not available use the [https://chrome.google.com/webstore/detail/h264ify/aleakchihdccplidncghkekgioiakgal h264ify], [https://chrome.google.com/webstore/detail/enhanced-h264ify/omkfmpieigblcllmkgbflkikinpkodlk enhanced-h264ify] or [https://chrome.google.com/webstore/detail/not-yet-av1/dcmllfkiihingappljlkffafnlhdpbai Not yet, AV1][https://bbs.archlinux.org/viewtopic.php?pid=2039884#p2039884] extension.<br />
<br />
On some systems (especially on XWayland) you might need to [[#Force GPU acceleration]]. Only {{ic|--ignore-gpu-blocklist}} is enough for our purposes.<br />
<br />
{{Expansion|Provide a link to some bug report.}}<br />
<br />
You might need to disable the Skia renderer, as it is currently not compatible with video decode acceleration: {{ic|1=--disable-features=UseSkiaRenderer}}<br />
<br />
=== KDE integration ===<br />
<br />
For integration into [[Plasma]] install {{Pkg|plasma-browser-integration}}. See [https://community.kde.org/Plasma/Browser_Integration KDE Plasma Browser Integration] for more details.<br />
<br />
=== PDF viewer plugin ===<br />
<br />
Chromium and Google Chrome are bundled with the ''Chromium PDF Viewer'' plugin. If you do not want to use this plugin, check ''Download PDFs'' in {{ic|chrome://settings/content/pdfDocuments}}.<br />
<br />
=== Running on XWayland ===<br />
<br />
If you are using NVIDIA's proprietary driver, running Chromium on XWayland may cause the GPU process to occasionally crash. To prevent the GPU process from crashing, add the following flags:<br />
<br />
--use-angle=vulkan --use-cmd-decoder=passthrough<br />
<br />
{{Note|This does not prevent all XWayland-related crashes.}}<br />
<br />
=== Native Wayland support ===<br />
<br />
Since version 97, native [[Wayland]] support in Chromium can be enabled with the following flags [https://chromium.googlesource.com/chromium/src/+/43cfb2f92a5cdc1a787d7326e74676884abf5052]:<br />
<br />
--ozone-platform-hint=auto<br />
<br />
If this doesn't work, e.g. on version 106 under [[Weston]], then use:<br />
<br />
--ozone-platform=wayland<br />
<br />
See [[#Making flags persistent]] for a permanent configuration. The flag is also available via [[#chrome:// URLs|browser flags menu]].<br />
<br />
This will select wayland Ozone backend when in wayland session, so you can use a single desktop entry if you switch between X11 and Wayland often.<br />
<br />
{{Note|When changing the "ozone-platform-hint" in browser flags menu, the browser will provide you a relaunch button. Do not use it, because the browser will still be relaunched in a platform it was before changing the flag. You need to close the browser, then open it.}}<br />
<br />
== Tips and tricks ==<br />
<br />
The following tips and tricks should work for both Chromium and Chrome unless explicitly stated.<br />
<br />
=== Browsing experience ===<br />
<br />
==== chrome:// URLs ====<br />
<br />
A number of tweaks can be accessed via Chrome URLs. See '''chrome://chrome-urls''' for a complete list.<br />
<br />
* '''chrome://flags''' - access experimental features such as WebGL and rendering webpages with GPU, etc.<br />
* '''chrome://extensions''' - view, enable and disable the currently used Chromium extensions.<br />
* '''chrome://gpu''' - status of different GPU options.<br />
* '''chrome://sandbox''' - indicate sandbox status.<br />
* '''chrome://version''' - display version and switches used to invoke the active {{ic|/usr/bin/chromium}}.<br />
<br />
An automatically updated, complete listing of Chromium switches (command line parameters) is available [https://peter.sh/experiments/chromium-command-line-switches/ here].<br />
<br />
==== Chromium task manager ====<br />
<br />
Shift+ESC can be used to bring up the browser task manager wherein memory, CPU, and network usage can be viewed.<br />
<br />
==== Chromium overrides/overwrites Preferences file ====<br />
<br />
If you enabled syncing with a Google Account, then Chromium will override any direct edits to the Preferences file found under {{ic|~/.config/chromium/Default/Preferences}}. To work around this, start Chromium with the {{ic|--disable-sync-preferences}} switch:<br />
$ chromium --disable-sync-preferences<br />
<br />
If Chromium is started in the background when you login in to your desktop environment, make sure the command your desktop environment uses is:<br />
$ chromium --disable-sync-preferences --no-startup-window<br />
<br />
==== Search engines ====<br />
<br />
Make sites like [https://wiki.archlinux.org wiki.archlinux.org] and [https://en.wikipedia.org wikipedia.org] easily searchable by first executing a search on those pages, then going to ''Settings > Search'' and click the ''Manage search engines..'' button. From there, "Edit" the Wikipedia entry and change its keyword to '''w''' (or some other shortcut you prefer). Now searching Wikipedia for "Arch Linux" from the address bar is done simply by entering "'''w arch linux'''".<br />
<br />
{{Note| Google search is used automatically when typing something into the URL bar. A hard-coded keyword trigger is also available using the '''?''' prefix.}}<br />
<br />
==== Tmpfs ====<br />
<br />
===== Cache in tmpfs =====<br />
<br />
{{Note|Chromium stores its cache separate from its browser profile directory.}}<br />
<br />
To limit Chromium from writing its cache to a physical disk, one can define an alternative location via the {{ic|--disk-cache-dir}} flag:<br />
$ chromium --disk-cache-dir="$XDG_RUNTIME_DIR/chromium-cache"<br />
<br />
Cache should be considered temporary and will '''not''' be saved after a reboot or hard lock. Another option is to setup the space in {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|2=<br />
tmpfs /home/''username''/.cache tmpfs noatime,nodev,nosuid,size=400M 0 0<br />
}}<br />
<br />
===== Profile in tmpfs =====<br />
<br />
Relocate the browser profile to a [[Wikipedia:Tmpfs|tmpfs]] filesystem, including {{ic|/tmp}}, or {{ic|/dev/shm}} for improvements in application response as the entire profile is now stored in RAM.<br />
<br />
Use an active profile management tool such as {{Pkg|profile-sync-daemon}} for maximal reliability and ease of use. It symlinks or bind mounts and syncs the browser profile directories to RAM. For more, see [[Profile-sync-daemon]].<br />
<br />
==== Launch a new browser instance ====<br />
<br />
When you launch the browser, it first checks if another instance using the same data directory is already running. If there is one, the new window is associated with the old instance. If you want to launch an independent instance of the browser, you must specify separate directory using the {{ic|--user-data-dir}} parameter:<br />
<br />
$ chromium --user-data-dir=''/path/to/some/directory''<br />
<br />
{{Note|The default location of the user data is {{ic|~/.config/chromium/}}.}}<br />
<br />
==== Directly open *.torrent files and magnet links with a torrent client ====<br />
<br />
By default, Chromium downloads {{ic|*.torrent}} files directly and you need to click the notification from the bottom-left corner of the screen in order for the file to be opened with your default torrent client. This can be avoided with the following method:<br />
<br />
* Download a {{ic|*.torrent}} file.<br />
* Right-click the notification displayed at the bottom-left corner of the screen.<br />
* Check the "''Always Open Files of This Type''" checkbox.<br />
<br />
See [[xdg-open]] to change the default assocation.<br />
<br />
==== Touch Scrolling on touchscreen devices ====<br />
<br />
You may need to specify which touch device to use. Find your touchscreen device with {{ic| xinput list}} then launch Chromium with the {{ic|1=--touch-devices='''x'''}} parameter, where "'''x'''" is the id of your device. {{Note|If the device is designated as a slave pointer, using this may not work, use the master pointer's ID instead.}}<br />
<br />
==== Reduce memory usage ====<br />
<br />
By default, Chromium uses a separate OS process for each ''instance'' of a visited web site. [https://www.chromium.org/developers/design-documents/process-models#Supported_Models] However, you can specify command-line switches when starting Chromium to modify this behaviour.<br />
<br />
For example, to share one process for all instances of a website:<br />
<br />
$ chromium --process-per-site<br />
<br />
To use a single process model:<br />
<br />
$ chromium --single-process<br />
<br />
{{Warning|The single-process model is discouraged because it is unsafe and may contain bugs not present in other models.[https://www.chromium.org/developers/design-documents/process-models#TOC-Single-process]}}<br />
<br />
In addition, you can suspend or store inactive Tabs with extensions such as [https://chrome.google.com/webstore/detail/tab-suspender/fiabciakcmgepblmdkmemdbbkilneeeh?hl=en Tab Suspender] and [https://chrome.google.com/webstore/detail/onetab/chphlpgkkbolifaimnlloiipkdnihall?hl=en OneTab].<br />
<br />
==== User Agent ====<br />
<br />
The User Agent can be arbitrarily modified at the start of Chromium's base instance via its {{Ic|<nowiki>--user-agent="[string]"</nowiki>}} parameter.<br />
<br />
==== DOM Distiller ====<br />
<br />
Chromium has a similar reader mode to Firefox. In this case it is called DOM Distiller, which is an [https://github.com/chromium/dom-distiller open source project].<br />
It is disabled by default, but can be enabled using the {{Ic|chrome://flags/#enable-reader-mode}} flag, which you can also make [[#Making flags persistent|persistent]].<br />
Not only does DOM Distiller provide a better reading experience by distilling the content of the page, it also simplifies pages for print. Even though the latter checkbox option has been removed from the print dialog, you can still print the distilled page, which basically has the same effect.<br />
<br />
After enabling the flag, you will find a new "Enter reader mode" menu item and corresponding icon in the address bar when Chromium thinks the website you are visiting could do with some distilling.<br />
<br />
==== Forcing specific GPU ====<br />
<br />
In multi-GPU systems, Chromium automatically detects which GPU should be used for rendering (discrete or integrated). This works 99% of the time, except when it does not - if a unavailable GPU is picked (for example, discrete graphics on VFIO GPU passthrough-enabled systems), {{ic|chrome://gpu}} will complain about not being able to initialize the GPU process. On the same page below '''Driver Information''' there will be multiple GPUs shown (GPU0, GPU1, ...). There is no way to switch between them in a user-friendly way, but you can read the device/vendor IDs present there and configure Chromium to use a specific GPU with flags:<br />
<br />
$ chromium --gpu-testing-vendor-id=0x8086 --gpu-testing-device-id=0x1912<br />
<br />
...where {{ic|0x8086}} and {{ic|0x1912}} is replaced by the IDs of the GPU you want to use (as shown on the {{ic|chrome://gpu}} page).<br />
<br />
==== Import bookmarks from Firefox ====<br />
<br />
To ease the transition, you can import bookmarks from [[Firefox]] into Chromium.<br />
<br />
Navigate Chromium to {{ic|chrome://settings/importData}}<br />
<br />
If Firefox is already installed on your computer, you can directly import bookmarks as well as many other things from Firefox.<br />
<br />
Make sure '''Mozilla Firefox''' is selected. Optionally, you can uncheck some unwanted items here. Click the '''Import''' and then '''Done'''. You are done with it.<br />
<br />
{{note|If you have not created any bookmarks in Chromium yet, the bookmarks will show up in your bookmarks bar. If you already have bookmarks, the bookmarks will be in a new folder labeled "Imported From Firefox"}}<br />
<br />
If you import bookmarks from another PC, you have to export bookmarks from Firefox first.<br />
<br />
{{ic|''Ctrl + Shift + O > Import and Backup > Export Bookmarks To HTML}} in Firefox''<br />
<br />
The procedure is pretty much the same. You need to go to {{ic|chrome://settings/importData}}. However, this time, in the '''From''' drop-down menu, select '''Bookmarks HTML File''' and click the '''Choose File''' button and upload the desired bookmark file.<br />
<br />
==== Enabling native notifications ====<br />
<br />
Go to {{ic|chrome://flags#enable-system-notifications}} and select ''Enabled''.<br />
<br />
==== U2F authentication ====<br />
<br />
Install {{Pkg|libfido2}} library. This provides the udev rules required to enable access to the [[U2F]] key as a user.<br />
U2F keys are by default only accessible by root, and without these rules Chromium will give an error.<br />
<br />
==== Dark mode ====<br />
<br />
To enable dark mode (used in ''prefers-color-scheme'' in CSS, JavaScript, Settings and Dev-Tools) and enable the dark theme (normally used for incognito mode) [[append]] the following flag to [[#Making flags persistent|persistent configuration]]:<br />
<br />
{{hc|1=~/.config/chromium-flags.conf|2=<br />
--force-dark-mode<br />
--enable-features=WebUIDarkMode<br />
}}<br />
<br />
===== Dark mode by system preference =====<br />
<br />
[https://bugs.chromium.org/p/chromium/issues/detail?id=998903 This Chromium issue] aims to bring dark mode based on GTK theme selection into Chromium.<br />
<br />
In the future, all that will be required to properly use system preference, is setting ''Designs'' to GTK in {{ic|chrome://settings/appearance}}.<br />
<br />
==== Enable Side Panel ====<br />
<br />
The Side Panel can be enabled through {{ic|chrome://flags}}. You can enable or disable '''Side panel''', and change options such as '''Side panel border''' and '''Side panel drag and drop'''.<br />
<br />
=== Profile maintenance ===<br />
<br />
Chromium uses [[SQLite]] databases to manage history and the like. Sqlite databases become fragmented over time and empty spaces appear all around. But, since there are no managing processes checking and optimizing the database, these factors eventually result in a performance hit. A good way to improve startup and some other bookmarks- and history-related tasks is to defragment and trim unused space from these databases.<br />
<br />
{{Pkg|profile-cleaner}} and {{AUR|browser-vacuum}} in the [[AUR]] do just this.<br />
<br />
=== Security ===<br />
<br />
==== Disable JIT ====<br />
<br />
At the cost of reduced performance, you can disable just-in-time compilation of JavaScript to native code, which is responsible for [https://microsoftedge.github.io/edgevr/posts/Super-Duper-Secure-Mode/ roughly half of the security vulnerabilities in the JS engine], using the flag {{ic|1=--js-flags=--jitless}}.<br />
<br />
==== WebRTC ====<br />
<br />
WebRTC is a communication protocol that relies on JavaScript that can leak one's actual IP address and hardware hash from behind a VPN. While some software may prevent the leaking scripts from running, it is probably a good idea to block this protocol directly as well, just to be safe. As of October 2016, there is no way to disable WebRTC on Chromium on desktop, there are extensions available to disable local IP address leak, one is this [https://chrome.google.com/webstore/detail/webrtc-network-limiter/npeicpdbkakmehahjeeohfdhnlpdklia extension].<br />
<br />
One can test WebRTC via https://browserleaks.com/webrtc.<br />
<br />
{{Warning|Even though IP leak can be prevented, Chromium still sends your unique hash, and there is no way to prevent this. Read more on https://www.browserleaks.com/webrtc#webrtc-disable}}<br />
<br />
==== SSL certificates ====<br />
<br />
Chromium does not have an SSL certificate manager. It relies on the NSS Shared DB {{ic|~/.pki/nssdb}}. In order to add SSL certificates to the database, users will have to use the shell.<br />
<br />
===== Adding CAcert certificates for self-signed certificates =====<br />
<br />
Grab the CAcerts and create an {{ic|nssdb}}, if one does not already exist. To do this, first install the {{Pkg|nss}} package, then complete these steps:<br />
<br />
$ mkdir -p $HOME/.pki/nssdb<br />
$ cd $HOME/.pki/nssdb<br />
$ certutil -N -d sql:.<br />
<br />
$ curl -k -o "cacert-root.crt" "http://www.cacert.org/certs/root.crt"<br />
$ curl -k -o "cacert-class3.crt" "http://www.cacert.org/certs/class3.crt"<br />
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "CAcert.org" -i cacert-root.crt <br />
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "CAcert.org Class 3" -i cacert-class3.crt<br />
<br />
{{Note|Users will need to create a password for the database, if it does not exist.}}<br />
<br />
Now users may manually import a self-signed certificate.<br />
<br />
===== Example 1: Using a shell script to isolate the certificate from TomatoUSB =====<br />
<br />
Below is a simple script that will extract and add a certificate to the user's {{ic|nssdb}}:<br />
<br />
#!/bin/sh<br />
#<br />
# usage: import-cert.sh remote.host.name [port]<br />
#<br />
REMHOST=$1<br />
REMPORT=${2:-443}<br />
exec 6>&1<br />
exec > $REMHOST<br />
echo | openssl s_client -connect ${REMHOST}:${REMPORT} 2>&1 |sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'<br />
certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n "$REMHOST" -i $REMHOST <br />
exec 1>&6 6>&-<br />
<br />
Syntax is advertised in the commented lines.<br />
<br />
References:<br />
*https://web.archive.org/web/20180718193807/https://blog.avirtualhome.com/adding-ssl-certificates-to-google-chrome-linux-ubuntu<br />
*https://chromium.googlesource.com/chromium/src/+/master/docs/linux/cert_management.md<br />
<br />
===== Example 2: Using Firefox to isolate the certificate from TomatoUSB =====<br />
<br />
The {{Pkg|firefox}} browser can be used to save the certificate to a file for manual import into the database.<br />
<br />
Using firefox:<br />
#Browse to the target URL.<br />
#Upon seeing the "This Connection is Untrusted" warning screen, click: ''I understand the Risks > Add Exception...''<br />
#Click: ''View > Details > Export'' and save the certificate to a temporary location ({{ic|/tmp/easy.pem}} in this example).<br />
<br />
Now import the certificate for use in Chromium:<br />
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "easy" -i /tmp/easy.pem<br />
<br />
{{Note|Adjust the name to match that of the certificate. In the example above, "easy" is the name of the certificate.}}<br />
<br />
Reference:<br />
*https://sahissam.blogspot.com/2012/06/new-ssl-certificates-for-tomatousb-and.html<br />
<br />
==== Canvas Fingerprinting ====<br />
<br />
Canvas fingerprinting is a technique that allows websites to identify users by detecting differences when rendering to an HTML5 canvas. This information can be made inaccessible by using the {{ic|--disable-reading-from-canvas}} flag.<br />
<br />
To confirm this is working run [https://panopticlick.eff.org this test] and make sure "hash of canvas fingerprint" is reported as undetermined in the full results.<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* Some extensions require reading from canvas and may be broken by setting {{ic|--disable-reading-from-canvas}}.<br />
* YouTube player does not work properly without canvas reading. [https://github.com/qutebrowser/qutebrowser/issues/5345][https://bbs.archlinux.org/viewtopic.php?pid=1907406]<br />
}}<br />
<br />
==== Privacy extensions ====<br />
<br />
See [[Browser extensions#Privacy]].<br />
<br />
{{Tip|Installing too many extensions might take up much space in the toolbar. Those extensions which you would not interact with anyway (e.g. [https://chrome.google.com/webstore/detail/gcbommkclmclpchllfjekcdonpmejbdp HTTPS Everywhere]) can be hidden by right-clicking on the extension and choosing ''Hide in Chromium menu''.}}<br />
<br />
==== Do Not Track ====<br />
<br />
To enable [[wikipedia:Do Not Track|Do Not Track]], visit {{ic|chrome://settings}}, scroll down to ''Advanced'' and under ''Privacy and security'', check ''Send a "Do Not Track" request with your browsing traffic''.<br />
<br />
==== Force a password store ====<br />
<br />
Chromium uses a password store to store your passwords and the ''Chromium Safe Storage'' key, which is used to encrypt cookie values. [https://codereview.chromium.org/24734007]<br />
<br />
By default Chromium auto-detects which password store to use, which can lead to you apparently losing your passwords and cookies when switching to another desktop environment or window manager.<br />
<br />
You can force Chromium to use a specific password store by launching it with the {{ic|--password-store}} flag with one of following the values [https://chromium.googlesource.com/chromium/src/+/master/docs/linux/password_storage.md]:<br />
<br />
* {{ic|gnome}}, uses [[Gnome Keyring]]<br />
* {{ic|kwallet5}}, uses [[KDE Wallet]]<br />
* {{ic|basic}}, saves the passwords and the cookies' encryption key as plain text in the file {{ic|Login Data}}<br />
* {{ic|detect}}, the default auto-detect behavior<br />
<br />
For example, to force Chromium to use Gnome Keyring in another desktop or WM use {{ic|1=--password-store=gnome}}, see [[#Making flags persistent]] for making it permanent.<br />
<br />
When using a password store of another desktop environment you probably also want to unlock it automatically. See [[GNOME/Keyring#Using the keyring]] and [[KDE Wallet#Unlock KDE Wallet automatically on login]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Fonts ===<br />
<br />
{{Note|Chromium does not fully integrate with fontconfig/GTK/Pango/X/etc. due to its sandbox. For more information, see the [https://dev.chromium.org/developers/linux-technical-faq Linux Technical FAQ].}}<br />
<br />
==== Tab font size is too large ====<br />
<br />
Chromium will use the GTK settings as described in [[GTK#Configuration]]. When configured, Chromium will use the {{ic|gtk-font-name}} setting for tabs (which may mismatch window font size). To override these settings, use {{ic|1=--force-device-scale-factor=1.0}}.<br />
<br />
=== WebGL ===<br />
<br />
There is the possibility that your graphics card has been blacklisted by Chromium. See [[#Force GPU acceleration]].<br />
<br />
If you are using Chromium with [[Bumblebee]], WebGL might crash due to GPU sandboxing. In this case, you can disable GPU sandboxing with {{ic|optirun chromium --disable-gpu-sandbox}}.<br />
<br />
Visit {{ic|chrome://gpu/}} for debugging information about WebGL support.<br />
<br />
Chromium can save incorrect data about your GPU in your user profile (e.g. if you use switch between an Nvidia card using Optimus and Intel, it will show the Nvidia card in {{ic|chrome://gpu}} even when you are not using it or primusrun/optirun). Running using a different user directory, e.g, {{ic|1=chromium --user-data-dir=$(mktemp -d)}} may solve this issue. For a persistent solution you can reset the GPU information by deleting {{ic|~/.config/chromium/Local\ State}}.<br />
<br />
=== Incorrect HiDPI rendering ===<br />
<br />
Chromium will automatically scale for a [[HiDPI]] display, however, this may cause an incorrect rendered GUI.<br />
<br />
The flag {{ic|1=--force-device-scale-factor=1}} may be used to overrule the automatic scaling factor.<br />
<br />
When [[#Native Wayland support|native Wayland support]] is enabled, Chromium will automatically scale based on the configured scale of each monitor.<br />
<br />
=== Password prompt on every start with GNOME Keyring ===<br />
<br />
See [[GNOME/Keyring#Passwords are not remembered]].<br />
<br />
=== Chromecasts in the network are not discovered ===<br />
<br />
You will need to enable the Media Router Component Extension in {{ic|chrome://flags/#load-media-router-component-extension}}.<br />
<br />
=== Everything is syncing except for password ===<br />
<br />
If synchronization is not working for password only (you can check it on {{ic|chrome://sync-internals/}}) delete profile login data:<br />
<br />
$ rm ~/.config/chromium/Default/Login\ Data*<br />
<br />
See [https://support.google.com/chrome/thread/9947763?hl=en&msgid=23687608 Google Chrome Help forum] for details.<br />
<br />
=== Losing cookies and passwords when switching between desktop environments ===<br />
<br />
If you see the message {{ic|Failed to decrypt token for service AccountId-*}} in the terminal when you start Chromium, it might try to use the wrong password storage backend. This might happen when you switch between Desktop Environments.<br />
<br />
See [[#Force a password store]].<br />
<br />
=== Hang on startup when Google Sync enabled ===<br />
<br />
Try launching Chrome with {{ic|1=--password-store=basic}} or another appropriate password store.<br />
<br />
See [[#Force a password store]].<br />
<br />
=== Chromium asks to be set as the default browser every time it starts ===<br />
<br />
If you are using KDE and have once set Firefox as the default browser (by clicking the button inside Firefox), you might find Chromium asks to be set as the default browser every time it starts, even if you click the "set as default" button.<br />
<br />
Chromium checks for this status by running {{ic|xdg-settings check default-web-browser chromium.desktop}}. If the output is "no", it is not considering itself to be the default browser. The script {{ic|xdg-settings}} checks for the following MIME associations and expect all of them to be {{ic|chromium.desktop}}:<br />
<br />
{{bc|<br />
x-scheme-handler/http<br />
x-scheme-handler/https<br />
text/html}}<br />
<br />
To fix it, go to ''System settings > Applications > Default applications > Web browser'' and choose Chromium. Then, set the MIME association for {{ic|text/html}}:<br />
<br />
$ xdg-mime default chromium.desktop text/html<br />
<br />
Finally, [[XDG MIME Applications#New MIME types|update the MIME database]]:<br />
<br />
$ update-mime-database ~/.local/share/mime<br />
<br />
=== "This browser or app may not be secure" error logging in to Google ===<br />
<br />
As of 2020.04.20 if you run chromium with {{ic|1=--remote-debugging-port=9222}} flag for web development, you cannot log in to your Google account. Temporarily disable this flag to login and then you can enable it back.<br />
<br />
=== Chromium stuck at 60fps when using a 144Hz + 60Hz monitor ===<br />
<br />
There is a suitable workaround for this issue, [[append]] the following flags to [[#Making flags persistent|persistent configuration]]:<br />
<br />
{{hc|1=~/.config/chromium-flags.conf|2=<br />
--use-gl=egl<br />
--ignore-gpu-blocklist<br />
--enable-gpu-rasterization<br />
}}<br />
<br />
This should make Chromium run at 144fps when used on your 144hz display, assuming your compositor is refreshing at 144fps. <br />
Keep in mind it might be a little choppy {{Bug|67035}}, but this is way better than it being stuck at 60fps.<br />
<br />
=== Chromium slow scroll speed ===<br />
<br />
Mouse whell scrolling in chromium and electron based applications may be too slow for daily usage. Here are some solutions.<br />
<br />
[[Libinput#Mouse wheel scrolling speed scaling]] injects {{ic|libinput_event_pointer_get_axis_value}} function in libinput and provides an interface to change scale factor. This is not a application level injection, so an addition script for application specific scale factor tuning is needed. Note that scroll on chromium's small height developer tools may be too fast when scale factor is big enough.<br />
<br />
[[IMWheel]] increases scroll distance by replaying X wheel button event for multiple times. However, chromium assumes the real scroll and the replayed ones as two events. There is a small but noticeable delay between them, so one mouse wheel scroll leads to twice page jumps. Also, touchpad scroll needs additional care.<br />
<br />
[https://chrome.google.com/webstore/detail/linux-scroll-speed-fix/mlboohjioameadaedfjcpemcaangkkbp Linux Scroll Speed Fix] and [https://chrome.google.com/webstore/detail/smoothscroll/nbokbjkabcmbfdlbddjidfmibcpneigj SmoothScroll] are two chromium extensions with suppport for scroll distance modification. Upon wheel scroll in a web page, the closest scrollable ancestor of current focused node will be found, then a scroll method with given pixel distance will be called on it, even if it has been scrolled to bottom. So once you scroll into a text editor or any scrollable element, you can never scroll out of it, except moving mouse. Also, extension based methods can not be used outside chromium.<br />
<br />
=== Videos load but do not play ===<br />
<br />
This may be a PulseAudio issue. See the suggested fix in [[PulseAudio/Troubleshooting#Browsers load videos but do no play]].<br />
<br />
== See also ==<br />
<br />
* [https://www.chromium.org/ Chromium homepage]<br />
* [https://chromereleases.googleblog.com/ Google Chrome release notes]<br />
* [https://chrome.google.com/webstore/ Chrome web store]<br />
* [[Wikipedia:Chromium (web browser)#Differences from Google Chrome|Differences between Chromium and Google Chrome]]<br />
* [https://peter.sh/experiments/chromium-command-line-switches/ List of Chromium command-line switches]<br />
* [[Profile-sync-daemon]] - Systemd service that saves Chromium profile in tmpfs and syncs to disk<br />
* [[Tmpfs]] - Tmpfs Filesystem in {{ic|/etc/fstab}}<br />
* [https://docs.kernel.org/filesystems/tmpfs.html Official tmpfs kernel Documentation]</div>Iaz3https://wiki.archlinux.org/index.php?title=Chromium&diff=767300Chromium2023-02-11T07:37:11Z<p>Iaz3: /* KDE integration */ "and" is wrong, this package is the same as the extension</p>
<hr />
<div>[[Category:Web browser]]<br />
[[Category:Google]]<br />
[[de:Chromium]]<br />
[[ja:Chromium]]<br />
[[zh-hans:Chromium]]<br />
{{Related articles start}}<br />
{{Related|Browser extensions}}<br />
{{Related|Firefox}}<br />
{{Related|Opera}}<br />
{{Related|Vivaldi}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Chromium (web browser)|Chromium]] is an open-source graphical web browser based on the [[Wikipedia:Blink (web engine)|Blink]] rendering engine. It is the basis for the proprietary Google Chrome browser.<br />
<br />
See [https://chromium.googlesource.com/chromium/src/+/master/docs/chromium_browser_vs_google_chrome.md this page] for an explanation of the differences between Chromium and Google Chrome. Additionally:<br />
<br />
* Sync is unavailable in Chromium 89+ (2021-03-02) [https://archlinux.org/news/chromium-losing-sync-support-in-early-march/]<br />
<br />
{{Note|Sync can be temporarily restored by [https://gist.github.com/foutrelis/14e339596b89813aa9c37fd1b4e5d9d5 using Chrome's OAuth2 credentials] or [https://www.chromium.org/developers/how-tos/api-keys getting your own], but pay attention to the disclaimers and do not consider this to be a long-term solution.<br />
Consider switching to [https://www.xbrowsersync.org xbrowsersync] for bookmarks syncing as long term solution.<br />
}}<br />
<br />
See [[List of applications/Internet#Blink-based]] for other browsers based on Chromium.<br />
<br />
== Installation ==<br />
<br />
There are several packages available to [[install]] Chromium with:<br />
<br />
* {{Pkg|chromium}} — stable release;<br />
* {{AUR|chromium-dev}} — development release;<br />
* {{AUR|chromium-snapshot-bin}} — nightly build.<br />
<br />
Google Chrome packages:<br />
<br />
* {{AUR|google-chrome}} — stable release;<br />
* {{AUR|google-chrome-beta}} — beta release;<br />
* {{AUR|google-chrome-dev}} — development release.<br />
<br />
{{Note|From the [https://www.chromium.org/Home/chromium-privacy Chromium privacy page]: "Features that communicate with Google made available through the compilation of code in Chromium are subject to the [https://www.google.com/policies/privacy/ Google Privacy Policy]." For those who want to avoid all integration with Google services, there are some [[List of applications/Internet#Privacy-focused chromium spin-offs|privacy-focused spin-offs]].}}<br />
<br />
== Configuration ==<br />
<br />
{{Merge|Chromium#Tips and tricks 2|Most of the content in this section should be split between [[Chromium#Tips and tricks 2]] and maybe [[Chromium#Troubleshooting]] for the applicable sections.}}<br />
<br />
=== Default applications ===<br />
<br />
To set Chromium as the default browser and to change which applications Chromium launches when opening downloaded files, see [[default applications]].<br />
<br />
=== Certificates ===<br />
<br />
Chromium uses [[Network Security Services]] for certificate management. Certificates can be managed in {{ic|chrome://settings/certificates}}.<br />
<br />
=== Making flags persistent ===<br />
<br />
{{Note|The {{ic|chromium-flags.conf}} file and the accompanying custom launcher script are specific to the Arch Linux {{Pkg|chromium}} package. For {{AUR|google-chrome}} and {{AUR|google-chrome-dev}}, use {{ic|chrome-flags.conf}} and {{ic|chrome-dev-flags.conf}} instead.}}<br />
<br />
You can put your flags in a {{ic|chromium-flags.conf}} file under {{ic|$HOME/.config/}} (or under {{ic|$XDG_CONFIG_HOME}} if you have configured that environment variable) or {{ic|/etc/}} for global.<br />
<br />
No special syntax is used; flags are defined as if they were written in a terminal.<br />
<br />
* The arguments are split on whitespace and shell quoting rules apply, but no further parsing is performed.<br />
* In case of improper quoting anywhere in the file, a fatal error is raised.<br />
* Flags can be placed in separate lines for readability, but this is not required.<br />
* Lines starting with a hash symbol (#) are skipped. (This is only supported by the {{Pkg|chromium}} launcher script and will not work when using {{ic|chrome-flags.conf}} with the {{AUR|google-chrome}} package.)<br />
<br />
Below is an example {{ic|chromium-flags.conf}} file that defines the flags {{ic|--start-maximized --incognito}}:<br />
<br />
{{hc|~/.config/chromium-flags.conf|<br />
# This line will be ignored.<br />
--start-maximized<br />
--incognito<br />
}}<br />
<br />
=== Force GPU acceleration ===<br />
<br />
{{Warning|Disabling the rendering blacklist may cause unstable behavior, including crashes of the host. See the bug reports in {{ic|chrome://gpu}} for details.}}<br />
<br />
By default Chromium on Linux does not use any GPU acceleration. To force GPU acceleration, [[append]] the following flags to [[/Tips and tricks#Making flags persistent|persistent configuration]]:<br />
<br />
{{hc|~/.config/chromium-flags.conf|<br />
--ignore-gpu-blocklist<br />
--enable-gpu-rasterization<br />
--enable-zero-copy<br />
}}<br />
<br />
Additionally the flag {{ic|--disable-gpu-driver-bug-workarounds}} may need to be passed to prevent GPU workaround from being used. Flags in {{ic|chrome://gpu}} should state "Hardware accelerated" when configured and available.<br />
<br />
{{Out of date|A fix has been merged into mesa as of May 2021. [https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/10850]}}<br />
<br />
{{ic|--enable-native-gpu-memory-buffers}} is broken since mesa 20.1.1 [https://gitlab.freedesktop.org/mesa/mesa/-/issues/3119#note_533902]<br />
<br />
=== Hardware video acceleration ===<br />
<br />
{{Note|1=<nowiki/><br />
* There is no official support from Chromium or Arch Linux for this feature [https://chromium.googlesource.com/chromium/src/+/master/docs/gpu/vaapi.md#vaapi-on-linux]. However, {{Pkg|chromium}} from official repositories is compiled with VA-API support and you may ask for help in [https://bbs.archlinux.org/viewtopic.php?id=244031 the dedicated forum thread].<br />
* VA-API does not work with the {{Pkg|chromium}} package when using the native Wayland backend, but it does work in {{AUR|chromium-wayland-vaapi}}.<br />
}}<br />
<br />
To enable VA-API support in Chromium:<br />
<br />
* Install the correct VA-API driver for your video card and verify VA-API has been enabled and working correctly, see [[Hardware video acceleration]]. For proprietary NVIDIA support, installing {{AUR|libva-vdpau-driver-chromium}} or {{AUR|libva-vdpau-driver-vp9-git}} is required.<br />
* Set the option {{ic|1=--enable-features=VaapiVideoDecoder}}. This is enough when using ANGLE GL renderer and {{Pkg|libva-intel-driver}}.<br />
* When using ANGLE, Chromium forces the older i965 driver and fails when {{Pkg|intel-media-driver}} is used. As a workaround, [[Hardware video acceleration#Configuring VA-API|configure VA-API manually]]. See [https://github.com/intel/media-driver/issues/818] for details.<br />
* To use the system GL renderer on Xorg, use either {{ic|1=--use-gl=egl}} or {{ic|1=--use-gl=desktop}}. On XWayland, use the {{ic|1=--use-gl=egl}} flag.<br />
* If VA-API still does not work, try the {{ic|1=--enable-features=VaapiIgnoreDriverChecks}} or{{ic|1=--disable-features=UseChromeOSDirectVideoDecoder}} flag<br />
<br />
==== Tips and tricks ====<br />
<br />
To check if it is working play a video which is using a codec supported by your VA-API driver (''vainfo'' tells you which codecs are supported, but Chromium will only support VP9 and h264):<br />
<br />
* Open the DevTools by pressing {{ic|Ctrl+Shift+I}} or on the ''Inspect'' button of the context (right-click) menu<br />
* Add the Media inspection tab: ''Hamburger menu > More tools > Media''<br />
* In the newly opened Media tab, look at the hardware decoder state of the video decoder<br />
<br />
Test on a large enough video. Starting with version 86, Chromium on desktop [https://bugs.chromium.org/p/chromium/issues/detail?id=684792 will only accelerate videos larger than 720p].<br />
<br />
To reduce CPU usage while watching YouTube where VP8/VP9 hardware decoding is not available use the [https://chrome.google.com/webstore/detail/h264ify/aleakchihdccplidncghkekgioiakgal h264ify], [https://chrome.google.com/webstore/detail/enhanced-h264ify/omkfmpieigblcllmkgbflkikinpkodlk enhanced-h264ify] or [https://chrome.google.com/webstore/detail/not-yet-av1/dcmllfkiihingappljlkffafnlhdpbai Not yet, AV1][https://bbs.archlinux.org/viewtopic.php?pid=2039884#p2039884] extension.<br />
<br />
On some systems (especially on XWayland) you might need to [[#Force GPU acceleration]]. Only {{ic|--ignore-gpu-blocklist}} is enough for our purposes.<br />
<br />
{{Expansion|Provide a link to some bug report.}}<br />
<br />
You might need to disable the Skia renderer, as it is currently not compatible with video decode acceleration: {{ic|1=--disable-features=UseSkiaRenderer}}<br />
<br />
=== KDE integration ===<br />
<br />
For integration into [[Plasma]] install {{aur|chromium-extension-plasma-integration}} or the [https://chrome.google.com/webstore/detail/plasma-integration/cimiefiiaegbelhefglklhhakcgmhkai plasma-integration] addon. See [https://community.kde.org/Plasma/Browser_Integration KDE Plasma Browser Integration] for more details.<br />
<br />
=== PDF viewer plugin ===<br />
<br />
Chromium and Google Chrome are bundled with the ''Chromium PDF Viewer'' plugin. If you do not want to use this plugin, check ''Download PDFs'' in {{ic|chrome://settings/content/pdfDocuments}}.<br />
<br />
=== Running on XWayland ===<br />
<br />
If you are using NVIDIA's proprietary driver, running Chromium on XWayland may cause the GPU process to occasionally crash. To prevent the GPU process from crashing, add the following flags:<br />
<br />
--use-angle=vulkan --use-cmd-decoder=passthrough<br />
<br />
{{Note|This does not prevent all XWayland-related crashes.}}<br />
<br />
=== Native Wayland support ===<br />
<br />
Since version 97, native [[Wayland]] support in Chromium can be enabled with the following flags [https://chromium.googlesource.com/chromium/src/+/43cfb2f92a5cdc1a787d7326e74676884abf5052]:<br />
<br />
--ozone-platform-hint=auto<br />
<br />
If this doesn't work, e.g. on version 106 under [[Weston]], then use:<br />
<br />
--ozone-platform=wayland<br />
<br />
See [[#Making flags persistent]] for a permanent configuration. The flag is also available via [[#chrome:// URLs|browser flags menu]].<br />
<br />
This will select wayland Ozone backend when in wayland session, so you can use a single desktop entry if you switch between X11 and Wayland often.<br />
<br />
{{Note|When changing the "ozone-platform-hint" in browser flags menu, the browser will provide you a relaunch button. Do not use it, because the browser will still be relaunched in a platform it was before changing the flag. You need to close the browser, then open it.}}<br />
<br />
== Tips and tricks ==<br />
<br />
The following tips and tricks should work for both Chromium and Chrome unless explicitly stated.<br />
<br />
=== Browsing experience ===<br />
<br />
==== chrome:// URLs ====<br />
<br />
A number of tweaks can be accessed via Chrome URLs. See '''chrome://chrome-urls''' for a complete list.<br />
<br />
* '''chrome://flags''' - access experimental features such as WebGL and rendering webpages with GPU, etc.<br />
* '''chrome://extensions''' - view, enable and disable the currently used Chromium extensions.<br />
* '''chrome://gpu''' - status of different GPU options.<br />
* '''chrome://sandbox''' - indicate sandbox status.<br />
* '''chrome://version''' - display version and switches used to invoke the active {{ic|/usr/bin/chromium}}.<br />
<br />
An automatically updated, complete listing of Chromium switches (command line parameters) is available [https://peter.sh/experiments/chromium-command-line-switches/ here].<br />
<br />
==== Chromium task manager ====<br />
<br />
Shift+ESC can be used to bring up the browser task manager wherein memory, CPU, and network usage can be viewed.<br />
<br />
==== Chromium overrides/overwrites Preferences file ====<br />
<br />
If you enabled syncing with a Google Account, then Chromium will override any direct edits to the Preferences file found under {{ic|~/.config/chromium/Default/Preferences}}. To work around this, start Chromium with the {{ic|--disable-sync-preferences}} switch:<br />
$ chromium --disable-sync-preferences<br />
<br />
If Chromium is started in the background when you login in to your desktop environment, make sure the command your desktop environment uses is:<br />
$ chromium --disable-sync-preferences --no-startup-window<br />
<br />
==== Search engines ====<br />
<br />
Make sites like [https://wiki.archlinux.org wiki.archlinux.org] and [https://en.wikipedia.org wikipedia.org] easily searchable by first executing a search on those pages, then going to ''Settings > Search'' and click the ''Manage search engines..'' button. From there, "Edit" the Wikipedia entry and change its keyword to '''w''' (or some other shortcut you prefer). Now searching Wikipedia for "Arch Linux" from the address bar is done simply by entering "'''w arch linux'''".<br />
<br />
{{Note| Google search is used automatically when typing something into the URL bar. A hard-coded keyword trigger is also available using the '''?''' prefix.}}<br />
<br />
==== Tmpfs ====<br />
<br />
===== Cache in tmpfs =====<br />
<br />
{{Note|Chromium stores its cache separate from its browser profile directory.}}<br />
<br />
To limit Chromium from writing its cache to a physical disk, one can define an alternative location via the {{ic|--disk-cache-dir}} flag:<br />
$ chromium --disk-cache-dir="$XDG_RUNTIME_DIR/chromium-cache"<br />
<br />
Cache should be considered temporary and will '''not''' be saved after a reboot or hard lock. Another option is to setup the space in {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|2=<br />
tmpfs /home/''username''/.cache tmpfs noatime,nodev,nosuid,size=400M 0 0<br />
}}<br />
<br />
===== Profile in tmpfs =====<br />
<br />
Relocate the browser profile to a [[Wikipedia:Tmpfs|tmpfs]] filesystem, including {{ic|/tmp}}, or {{ic|/dev/shm}} for improvements in application response as the entire profile is now stored in RAM.<br />
<br />
Use an active profile management tool such as {{Pkg|profile-sync-daemon}} for maximal reliability and ease of use. It symlinks or bind mounts and syncs the browser profile directories to RAM. For more, see [[Profile-sync-daemon]].<br />
<br />
==== Launch a new browser instance ====<br />
<br />
When you launch the browser, it first checks if another instance using the same data directory is already running. If there is one, the new window is associated with the old instance. If you want to launch an independent instance of the browser, you must specify separate directory using the {{ic|--user-data-dir}} parameter:<br />
<br />
$ chromium --user-data-dir=''/path/to/some/directory''<br />
<br />
{{Note|The default location of the user data is {{ic|~/.config/chromium/}}.}}<br />
<br />
==== Directly open *.torrent files and magnet links with a torrent client ====<br />
<br />
By default, Chromium downloads {{ic|*.torrent}} files directly and you need to click the notification from the bottom-left corner of the screen in order for the file to be opened with your default torrent client. This can be avoided with the following method:<br />
<br />
* Download a {{ic|*.torrent}} file.<br />
* Right-click the notification displayed at the bottom-left corner of the screen.<br />
* Check the "''Always Open Files of This Type''" checkbox.<br />
<br />
See [[xdg-open]] to change the default assocation.<br />
<br />
==== Touch Scrolling on touchscreen devices ====<br />
<br />
You may need to specify which touch device to use. Find your touchscreen device with {{ic| xinput list}} then launch Chromium with the {{ic|1=--touch-devices='''x'''}} parameter, where "'''x'''" is the id of your device. {{Note|If the device is designated as a slave pointer, using this may not work, use the master pointer's ID instead.}}<br />
<br />
==== Reduce memory usage ====<br />
<br />
By default, Chromium uses a separate OS process for each ''instance'' of a visited web site. [https://www.chromium.org/developers/design-documents/process-models#Supported_Models] However, you can specify command-line switches when starting Chromium to modify this behaviour.<br />
<br />
For example, to share one process for all instances of a website:<br />
<br />
$ chromium --process-per-site<br />
<br />
To use a single process model:<br />
<br />
$ chromium --single-process<br />
<br />
{{Warning|The single-process model is discouraged because it is unsafe and may contain bugs not present in other models.[https://www.chromium.org/developers/design-documents/process-models#TOC-Single-process]}}<br />
<br />
In addition, you can suspend or store inactive Tabs with extensions such as [https://chrome.google.com/webstore/detail/tab-suspender/fiabciakcmgepblmdkmemdbbkilneeeh?hl=en Tab Suspender] and [https://chrome.google.com/webstore/detail/onetab/chphlpgkkbolifaimnlloiipkdnihall?hl=en OneTab].<br />
<br />
==== User Agent ====<br />
<br />
The User Agent can be arbitrarily modified at the start of Chromium's base instance via its {{Ic|<nowiki>--user-agent="[string]"</nowiki>}} parameter.<br />
<br />
==== DOM Distiller ====<br />
<br />
Chromium has a similar reader mode to Firefox. In this case it is called DOM Distiller, which is an [https://github.com/chromium/dom-distiller open source project].<br />
It is disabled by default, but can be enabled using the {{Ic|chrome://flags/#enable-reader-mode}} flag, which you can also make [[#Making flags persistent|persistent]].<br />
Not only does DOM Distiller provide a better reading experience by distilling the content of the page, it also simplifies pages for print. Even though the latter checkbox option has been removed from the print dialog, you can still print the distilled page, which basically has the same effect.<br />
<br />
After enabling the flag, you will find a new "Enter reader mode" menu item and corresponding icon in the address bar when Chromium thinks the website you are visiting could do with some distilling.<br />
<br />
==== Forcing specific GPU ====<br />
<br />
In multi-GPU systems, Chromium automatically detects which GPU should be used for rendering (discrete or integrated). This works 99% of the time, except when it does not - if a unavailable GPU is picked (for example, discrete graphics on VFIO GPU passthrough-enabled systems), {{ic|chrome://gpu}} will complain about not being able to initialize the GPU process. On the same page below '''Driver Information''' there will be multiple GPUs shown (GPU0, GPU1, ...). There is no way to switch between them in a user-friendly way, but you can read the device/vendor IDs present there and configure Chromium to use a specific GPU with flags:<br />
<br />
$ chromium --gpu-testing-vendor-id=0x8086 --gpu-testing-device-id=0x1912<br />
<br />
...where {{ic|0x8086}} and {{ic|0x1912}} is replaced by the IDs of the GPU you want to use (as shown on the {{ic|chrome://gpu}} page).<br />
<br />
==== Import bookmarks from Firefox ====<br />
<br />
To ease the transition, you can import bookmarks from [[Firefox]] into Chromium.<br />
<br />
Navigate Chromium to {{ic|chrome://settings/importData}}<br />
<br />
If Firefox is already installed on your computer, you can directly import bookmarks as well as many other things from Firefox.<br />
<br />
Make sure '''Mozilla Firefox''' is selected. Optionally, you can uncheck some unwanted items here. Click the '''Import''' and then '''Done'''. You are done with it.<br />
<br />
{{note|If you have not created any bookmarks in Chromium yet, the bookmarks will show up in your bookmarks bar. If you already have bookmarks, the bookmarks will be in a new folder labeled "Imported From Firefox"}}<br />
<br />
If you import bookmarks from another PC, you have to export bookmarks from Firefox first.<br />
<br />
{{ic|''Ctrl + Shift + O > Import and Backup > Export Bookmarks To HTML}} in Firefox''<br />
<br />
The procedure is pretty much the same. You need to go to {{ic|chrome://settings/importData}}. However, this time, in the '''From''' drop-down menu, select '''Bookmarks HTML File''' and click the '''Choose File''' button and upload the desired bookmark file.<br />
<br />
==== Enabling native notifications ====<br />
<br />
Go to {{ic|chrome://flags#enable-system-notifications}} and select ''Enabled''.<br />
<br />
==== U2F authentication ====<br />
<br />
Install {{Pkg|libfido2}} library. This provides the udev rules required to enable access to the [[U2F]] key as a user.<br />
U2F keys are by default only accessible by root, and without these rules Chromium will give an error.<br />
<br />
==== Dark mode ====<br />
<br />
To enable dark mode (used in ''prefers-color-scheme'' in CSS, JavaScript, Settings and Dev-Tools) and enable the dark theme (normally used for incognito mode) [[append]] the following flag to [[#Making flags persistent|persistent configuration]]:<br />
<br />
{{hc|1=~/.config/chromium-flags.conf|2=<br />
--force-dark-mode<br />
--enable-features=WebUIDarkMode<br />
}}<br />
<br />
===== Dark mode by system preference =====<br />
<br />
[https://bugs.chromium.org/p/chromium/issues/detail?id=998903 This Chromium issue] aims to bring dark mode based on GTK theme selection into Chromium.<br />
<br />
In the future, all that will be required to properly use system preference, is setting ''Designs'' to GTK in {{ic|chrome://settings/appearance}}.<br />
<br />
==== Enable Side Panel ====<br />
<br />
The Side Panel can be enabled through {{ic|chrome://flags}}. You can enable or disable '''Side panel''', and change options such as '''Side panel border''' and '''Side panel drag and drop'''.<br />
<br />
=== Profile maintenance ===<br />
<br />
Chromium uses [[SQLite]] databases to manage history and the like. Sqlite databases become fragmented over time and empty spaces appear all around. But, since there are no managing processes checking and optimizing the database, these factors eventually result in a performance hit. A good way to improve startup and some other bookmarks- and history-related tasks is to defragment and trim unused space from these databases.<br />
<br />
{{Pkg|profile-cleaner}} and {{AUR|browser-vacuum}} in the [[AUR]] do just this.<br />
<br />
=== Security ===<br />
<br />
==== Disable JIT ====<br />
<br />
At the cost of reduced performance, you can disable just-in-time compilation of JavaScript to native code, which is responsible for [https://microsoftedge.github.io/edgevr/posts/Super-Duper-Secure-Mode/ roughly half of the security vulnerabilities in the JS engine], using the flag {{ic|1=--js-flags=--jitless}}.<br />
<br />
==== WebRTC ====<br />
<br />
WebRTC is a communication protocol that relies on JavaScript that can leak one's actual IP address and hardware hash from behind a VPN. While some software may prevent the leaking scripts from running, it is probably a good idea to block this protocol directly as well, just to be safe. As of October 2016, there is no way to disable WebRTC on Chromium on desktop, there are extensions available to disable local IP address leak, one is this [https://chrome.google.com/webstore/detail/webrtc-network-limiter/npeicpdbkakmehahjeeohfdhnlpdklia extension].<br />
<br />
One can test WebRTC via https://browserleaks.com/webrtc.<br />
<br />
{{Warning|Even though IP leak can be prevented, Chromium still sends your unique hash, and there is no way to prevent this. Read more on https://www.browserleaks.com/webrtc#webrtc-disable}}<br />
<br />
==== SSL certificates ====<br />
<br />
Chromium does not have an SSL certificate manager. It relies on the NSS Shared DB {{ic|~/.pki/nssdb}}. In order to add SSL certificates to the database, users will have to use the shell.<br />
<br />
===== Adding CAcert certificates for self-signed certificates =====<br />
<br />
Grab the CAcerts and create an {{ic|nssdb}}, if one does not already exist. To do this, first install the {{Pkg|nss}} package, then complete these steps:<br />
<br />
$ mkdir -p $HOME/.pki/nssdb<br />
$ cd $HOME/.pki/nssdb<br />
$ certutil -N -d sql:.<br />
<br />
$ curl -k -o "cacert-root.crt" "http://www.cacert.org/certs/root.crt"<br />
$ curl -k -o "cacert-class3.crt" "http://www.cacert.org/certs/class3.crt"<br />
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "CAcert.org" -i cacert-root.crt <br />
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "CAcert.org Class 3" -i cacert-class3.crt<br />
<br />
{{Note|Users will need to create a password for the database, if it does not exist.}}<br />
<br />
Now users may manually import a self-signed certificate.<br />
<br />
===== Example 1: Using a shell script to isolate the certificate from TomatoUSB =====<br />
<br />
Below is a simple script that will extract and add a certificate to the user's {{ic|nssdb}}:<br />
<br />
#!/bin/sh<br />
#<br />
# usage: import-cert.sh remote.host.name [port]<br />
#<br />
REMHOST=$1<br />
REMPORT=${2:-443}<br />
exec 6>&1<br />
exec > $REMHOST<br />
echo | openssl s_client -connect ${REMHOST}:${REMPORT} 2>&1 |sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'<br />
certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n "$REMHOST" -i $REMHOST <br />
exec 1>&6 6>&-<br />
<br />
Syntax is advertised in the commented lines.<br />
<br />
References:<br />
*https://web.archive.org/web/20180718193807/https://blog.avirtualhome.com/adding-ssl-certificates-to-google-chrome-linux-ubuntu<br />
*https://chromium.googlesource.com/chromium/src/+/master/docs/linux/cert_management.md<br />
<br />
===== Example 2: Using Firefox to isolate the certificate from TomatoUSB =====<br />
<br />
The {{Pkg|firefox}} browser can be used to save the certificate to a file for manual import into the database.<br />
<br />
Using firefox:<br />
#Browse to the target URL.<br />
#Upon seeing the "This Connection is Untrusted" warning screen, click: ''I understand the Risks > Add Exception...''<br />
#Click: ''View > Details > Export'' and save the certificate to a temporary location ({{ic|/tmp/easy.pem}} in this example).<br />
<br />
Now import the certificate for use in Chromium:<br />
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "easy" -i /tmp/easy.pem<br />
<br />
{{Note|Adjust the name to match that of the certificate. In the example above, "easy" is the name of the certificate.}}<br />
<br />
Reference:<br />
*https://sahissam.blogspot.com/2012/06/new-ssl-certificates-for-tomatousb-and.html<br />
<br />
==== Canvas Fingerprinting ====<br />
<br />
Canvas fingerprinting is a technique that allows websites to identify users by detecting differences when rendering to an HTML5 canvas. This information can be made inaccessible by using the {{ic|--disable-reading-from-canvas}} flag.<br />
<br />
To confirm this is working run [https://panopticlick.eff.org this test] and make sure "hash of canvas fingerprint" is reported as undetermined in the full results.<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* Some extensions require reading from canvas and may be broken by setting {{ic|--disable-reading-from-canvas}}.<br />
* YouTube player does not work properly without canvas reading. [https://github.com/qutebrowser/qutebrowser/issues/5345][https://bbs.archlinux.org/viewtopic.php?pid=1907406]<br />
}}<br />
<br />
==== Privacy extensions ====<br />
<br />
See [[Browser extensions#Privacy]].<br />
<br />
{{Tip|Installing too many extensions might take up much space in the toolbar. Those extensions which you would not interact with anyway (e.g. [https://chrome.google.com/webstore/detail/gcbommkclmclpchllfjekcdonpmejbdp HTTPS Everywhere]) can be hidden by right-clicking on the extension and choosing ''Hide in Chromium menu''.}}<br />
<br />
==== Do Not Track ====<br />
<br />
To enable [[wikipedia:Do Not Track|Do Not Track]], visit {{ic|chrome://settings}}, scroll down to ''Advanced'' and under ''Privacy and security'', check ''Send a "Do Not Track" request with your browsing traffic''.<br />
<br />
==== Force a password store ====<br />
<br />
Chromium uses a password store to store your passwords and the ''Chromium Safe Storage'' key, which is used to encrypt cookie values. [https://codereview.chromium.org/24734007]<br />
<br />
By default Chromium auto-detects which password store to use, which can lead to you apparently losing your passwords and cookies when switching to another desktop environment or window manager.<br />
<br />
You can force Chromium to use a specific password store by launching it with the {{ic|--password-store}} flag with one of following the values [https://chromium.googlesource.com/chromium/src/+/master/docs/linux/password_storage.md]:<br />
<br />
* {{ic|gnome}}, uses [[Gnome Keyring]]<br />
* {{ic|kwallet5}}, uses [[KDE Wallet]]<br />
* {{ic|basic}}, saves the passwords and the cookies' encryption key as plain text in the file {{ic|Login Data}}<br />
* {{ic|detect}}, the default auto-detect behavior<br />
<br />
For example, to force Chromium to use Gnome Keyring in another desktop or WM use {{ic|1=--password-store=gnome}}, see [[#Making flags persistent]] for making it permanent.<br />
<br />
When using a password store of another desktop environment you probably also want to unlock it automatically. See [[GNOME/Keyring#Using the keyring]] and [[KDE Wallet#Unlock KDE Wallet automatically on login]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Fonts ===<br />
<br />
{{Note|Chromium does not fully integrate with fontconfig/GTK/Pango/X/etc. due to its sandbox. For more information, see the [https://dev.chromium.org/developers/linux-technical-faq Linux Technical FAQ].}}<br />
<br />
==== Tab font size is too large ====<br />
<br />
Chromium will use the GTK settings as described in [[GTK#Configuration]]. When configured, Chromium will use the {{ic|gtk-font-name}} setting for tabs (which may mismatch window font size). To override these settings, use {{ic|1=--force-device-scale-factor=1.0}}.<br />
<br />
=== WebGL ===<br />
<br />
There is the possibility that your graphics card has been blacklisted by Chromium. See [[#Force GPU acceleration]].<br />
<br />
If you are using Chromium with [[Bumblebee]], WebGL might crash due to GPU sandboxing. In this case, you can disable GPU sandboxing with {{ic|optirun chromium --disable-gpu-sandbox}}.<br />
<br />
Visit {{ic|chrome://gpu/}} for debugging information about WebGL support.<br />
<br />
Chromium can save incorrect data about your GPU in your user profile (e.g. if you use switch between an Nvidia card using Optimus and Intel, it will show the Nvidia card in {{ic|chrome://gpu}} even when you are not using it or primusrun/optirun). Running using a different user directory, e.g, {{ic|1=chromium --user-data-dir=$(mktemp -d)}} may solve this issue. For a persistent solution you can reset the GPU information by deleting {{ic|~/.config/chromium/Local\ State}}.<br />
<br />
=== Incorrect HiDPI rendering ===<br />
<br />
Chromium will automatically scale for a [[HiDPI]] display, however, this may cause an incorrect rendered GUI.<br />
<br />
The flag {{ic|1=--force-device-scale-factor=1}} may be used to overrule the automatic scaling factor.<br />
<br />
When [[#Native Wayland support|native Wayland support]] is enabled, Chromium will automatically scale based on the configured scale of each monitor.<br />
<br />
=== Password prompt on every start with GNOME Keyring ===<br />
<br />
See [[GNOME/Keyring#Passwords are not remembered]].<br />
<br />
=== Chromecasts in the network are not discovered ===<br />
<br />
You will need to enable the Media Router Component Extension in {{ic|chrome://flags/#load-media-router-component-extension}}.<br />
<br />
=== Everything is syncing except for password ===<br />
<br />
If synchronization is not working for password only (you can check it on {{ic|chrome://sync-internals/}}) delete profile login data:<br />
<br />
$ rm ~/.config/chromium/Default/Login\ Data*<br />
<br />
See [https://support.google.com/chrome/thread/9947763?hl=en&msgid=23687608 Google Chrome Help forum] for details.<br />
<br />
=== Losing cookies and passwords when switching between desktop environments ===<br />
<br />
If you see the message {{ic|Failed to decrypt token for service AccountId-*}} in the terminal when you start Chromium, it might try to use the wrong password storage backend. This might happen when you switch between Desktop Environments.<br />
<br />
See [[#Force a password store]].<br />
<br />
=== Hang on startup when Google Sync enabled ===<br />
<br />
Try launching Chrome with {{ic|1=--password-store=basic}} or another appropriate password store.<br />
<br />
See [[#Force a password store]].<br />
<br />
=== Chromium asks to be set as the default browser every time it starts ===<br />
<br />
If you are using KDE and have once set Firefox as the default browser (by clicking the button inside Firefox), you might find Chromium asks to be set as the default browser every time it starts, even if you click the "set as default" button.<br />
<br />
Chromium checks for this status by running {{ic|xdg-settings check default-web-browser chromium.desktop}}. If the output is "no", it is not considering itself to be the default browser. The script {{ic|xdg-settings}} checks for the following MIME associations and expect all of them to be {{ic|chromium.desktop}}:<br />
<br />
{{bc|<br />
x-scheme-handler/http<br />
x-scheme-handler/https<br />
text/html}}<br />
<br />
To fix it, go to ''System settings > Applications > Default applications > Web browser'' and choose Chromium. Then, set the MIME association for {{ic|text/html}}:<br />
<br />
$ xdg-mime default chromium.desktop text/html<br />
<br />
Finally, [[XDG MIME Applications#New MIME types|update the MIME database]]:<br />
<br />
$ update-mime-database ~/.local/share/mime<br />
<br />
=== "This browser or app may not be secure" error logging in to Google ===<br />
<br />
As of 2020.04.20 if you run chromium with {{ic|1=--remote-debugging-port=9222}} flag for web development, you cannot log in to your Google account. Temporarily disable this flag to login and then you can enable it back.<br />
<br />
=== Chromium stuck at 60fps when using a 144Hz + 60Hz monitor ===<br />
<br />
There is a suitable workaround for this issue, [[append]] the following flags to [[#Making flags persistent|persistent configuration]]:<br />
<br />
{{hc|1=~/.config/chromium-flags.conf|2=<br />
--use-gl=egl<br />
--ignore-gpu-blocklist<br />
--enable-gpu-rasterization<br />
}}<br />
<br />
This should make Chromium run at 144fps when used on your 144hz display, assuming your compositor is refreshing at 144fps. <br />
Keep in mind it might be a little choppy {{Bug|67035}}, but this is way better than it being stuck at 60fps.<br />
<br />
=== Chromium slow scroll speed ===<br />
<br />
Mouse whell scrolling in chromium and electron based applications may be too slow for daily usage. Here are some solutions.<br />
<br />
[[Libinput#Mouse wheel scrolling speed scaling]] injects {{ic|libinput_event_pointer_get_axis_value}} function in libinput and provides an interface to change scale factor. This is not a application level injection, so an addition script for application specific scale factor tuning is needed. Note that scroll on chromium's small height developer tools may be too fast when scale factor is big enough.<br />
<br />
[[IMWheel]] increases scroll distance by replaying X wheel button event for multiple times. However, chromium assumes the real scroll and the replayed ones as two events. There is a small but noticeable delay between them, so one mouse wheel scroll leads to twice page jumps. Also, touchpad scroll needs additional care.<br />
<br />
[https://chrome.google.com/webstore/detail/linux-scroll-speed-fix/mlboohjioameadaedfjcpemcaangkkbp Linux Scroll Speed Fix] and [https://chrome.google.com/webstore/detail/smoothscroll/nbokbjkabcmbfdlbddjidfmibcpneigj SmoothScroll] are two chromium extensions with suppport for scroll distance modification. Upon wheel scroll in a web page, the closest scrollable ancestor of current focused node will be found, then a scroll method with given pixel distance will be called on it, even if it has been scrolled to bottom. So once you scroll into a text editor or any scrollable element, you can never scroll out of it, except moving mouse. Also, extension based methods can not be used outside chromium.<br />
<br />
=== Videos load but do not play ===<br />
<br />
This may be a PulseAudio issue. See the suggested fix in [[PulseAudio/Troubleshooting#Browsers load videos but do no play]].<br />
<br />
== See also ==<br />
<br />
* [https://www.chromium.org/ Chromium homepage]<br />
* [https://chromereleases.googleblog.com/ Google Chrome release notes]<br />
* [https://chrome.google.com/webstore/ Chrome web store]<br />
* [[Wikipedia:Chromium (web browser)#Differences from Google Chrome|Differences between Chromium and Google Chrome]]<br />
* [https://peter.sh/experiments/chromium-command-line-switches/ List of Chromium command-line switches]<br />
* [[Profile-sync-daemon]] - Systemd service that saves Chromium profile in tmpfs and syncs to disk<br />
* [[Tmpfs]] - Tmpfs Filesystem in {{ic|/etc/fstab}}<br />
* [https://docs.kernel.org/filesystems/tmpfs.html Official tmpfs kernel Documentation]</div>Iaz3https://wiki.archlinux.org/index.php?title=Wine&diff=724859Wine2022-03-31T00:18:50Z<p>Iaz3: /* Prevent Wine from creating filetype associations */ add how to do the change from the command-line</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}} (development), {{AUR|wine-stable}} (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-git}}}}<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 />
To make this change via the command-line, run the following command<br />
<br />
wine reg add "HKEY_CURRENT_USER\Software\Wine\FileOpenAssociations" /v Enable /d N<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/sh<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 ~/.wine/drive_c/windows/temp<br />
$ ln -s /tmp/ ~/.wine/drive_c/users/$USER/Temp<br />
$ ln -s /tmp/ ~/.wine/drive_c/windows/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 />
=== WineASIO ===<br />
<br />
If you need professional audio support under wine you can use {{Aur|wineasio}} which provides an ASIO interface for wine that you can then use with [[JACK]].<br />
<br />
In order to use wineasio you must add yourself to the {{ic|realtime}} [[user group]].<br />
<br />
Next you need to register wineasio in your desired wine prefix. Register the 32-bit and/or 64-bit version as needed:<br />
$ regsvr32 /usr/lib32/wine/i386-windows/wineasio.dll<br />
$ wine64 regsvr32 /usr/lib/wine/x86_64-windows/wineasio.dll<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<br />
* [https://github.com/wineasio/wineasio WineASIO] - GitHub page of the WineASIO project with further information</div>Iaz3https://wiki.archlinux.org/index.php?title=AMDGPU&diff=722150AMDGPU2022-03-09T17:09:26Z<p>Iaz3: /* 10-bit color */ More clearly warn that enabling 10-bit color is able and known to break applications</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X server]]<br />
[[de:AMDGPU]]<br />
[[ja:AMDGPU]]<br />
[[zh-hans:AMDGPU]]<br />
{{Related articles start}}<br />
{{Related|ATI}}<br />
{{Related|Xorg}}<br />
{{Related|Vulkan}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:AMDGPU|AMDGPU]] is the open source graphics driver for AMD Radeon graphics cards from the [[wikipedia:Graphics_Core_Next|Graphics Core Next]] family.<br />
<br />
== Selecting the right driver ==<br />
<br />
Depending on the card you have, find the right driver in [[Xorg#AMD]]. This page has instructions for '''AMDGPU''' and '''AMDGPU PRO'''. <br />
At the moment there is Xorg [[radeon]] driver support for [https://www.x.org/wiki/RadeonFeature/ Southern Islands (SI)] through Arctic Islands (AI) cards. AMD has no plans to support pre-GCN GPUs.<br />
Owners of unsupported GPUs may use the open source [[radeon]] driver.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mesa}} package, which provides the DRI driver for 3D acceleration.<br />
<br />
* For 32-bit application support, also install the {{Pkg|lib32-mesa}} package from the [[multilib]] repostory.<br />
* For the DDX driver (which provides 2D acceleration in [[Xorg]]), install the {{Pkg|xf86-video-amdgpu}} package.<br />
* For [[Vulkan]] support, install the {{Pkg|vulkan-radeon}} or {{Pkg|amdvlk}} package. Optionally install the {{Pkg|lib32-vulkan-radeon}} or {{Pkg|lib32-amdvlk}} package for 32-bit application support.<br />
<br />
Support for [[#Video acceleration|accelerated video decoding]] is provided by {{Pkg|libva-mesa-driver}} and {{Pkg|lib32-libva-mesa-driver}} for VA-API and {{Pkg|mesa-vdpau}} and {{Pkg|lib32-mesa-vdpau}} packages for VDPAU.<br />
<br />
=== Experimental ===<br />
<br />
It may be worthwhile for some users to use the upstream experimental build of mesa, to enable features such as AMD Navi improvements that have not landed in the standard mesa packages.<br />
<br />
Install the {{AUR|mesa-git}} package, which provides the DRI driver for 3D acceleration.<br />
<br />
* For 32-bit application support, also install the {{AUR|lib32-mesa-git}} package from the ''mesa-git'' repository or the [[AUR]].<br />
* For the DDX driver (which provides 2D acceleration in [[Xorg]]), install the {{AUR|xf86-video-amdgpu-git}} package.<br />
* For [[Vulkan]] support using the ''mesa-git'' repository below, install the ''vulkan-radeon-git'' package. Optionally install the ''lib32-vulkan-radeon-git'' package for 32-bit application support. This should not be required if building {{AUR|mesa-git}} from the AUR.<br />
<br />
{{Note|It may be necessary to symlink LibLLVM for X to start. For example, {{ic|ln -s /usr/lib/libLLVM-10git.so /usr/lib/libLLVM-10svn.so}}}}<br />
<br />
{{Tip|Users who do not wish to go through the process of compiling the {{AUR|mesa-git}} package can use the [[Unofficial user repositories#mesa-git|mesa-git]] unofficial repository.}}<br />
<br />
=== Enable Southern Islands (SI) and Sea Islands (CIK) support ===<br />
<br />
The {{Pkg|linux}} package enables AMDGPU support for cards of the Southern Islands (HD 7000 Series, SI, ie. GCN 1) and Sea Islands (HD 8000 Series, CIK, ie. GCN 2). The {{ic|amdgpu}} kernel driver needs to be loaded before the [[radeon]]. You can check which kernel driver is loaded by running {{ic|lspci -k}}. It should be like this:<br />
<br />
{{hc|$ lspci -k|<br />
...<br />
01:00.0 VGA compatible controller: Advanced Micro Devices, Inc. [AMD/ATI] Curacao PRO [Radeon R7 370 / R9 270/370 OEM]<br />
Subsystem: Gigabyte Technology Co., Ltd Device 226c<br />
Kernel driver in use: amdgpu<br />
Kernel modules: radeon, amdgpu<br />
...<br />
}}<br />
<br />
If the {{ic|amdgpu}} driver is not in use, follow instructions in the next section.<br />
<br />
==== Load amdgpu driver ====<br />
<br />
The [[module parameters]] of both {{ic|amdgpu}} and {{ic|radeon}} modules are {{ic|1=cik_support=}} and {{ic|1=si_support=}}. <br />
<br />
They need to be set as kernel parameters or in a ''modprobe'' configuration file, and depend on the cards GCN version.<br />
<br />
You can use both parameters if you are unsure which kernel card you have.<br />
<br />
{{Tip|[[dmesg]] may indicate the correct kernel parameter to use: {{ic|1=[..] amdgpu 0000:01:00.0: Use radeon.cik_support=0 amdgpu.cik_support=1 to override}}.}}<br />
<br />
===== Set module parameters in kernel command line =====<br />
<br />
Set one of the following [[kernel parameters]]:<br />
<br />
* Southern Islands (SI): {{ic|1=radeon.si_support=0 amdgpu.si_support=1}}<br />
* Sea Islands (CIK): {{ic|1=radeon.cik_support=0 amdgpu.cik_support=1}}<br />
<br />
==== Specify the correct module order ====<br />
<br />
Make sure {{ic|amdgpu}} has been set as first module in the [[Mkinitcpio#MODULES]] array, e.g. {{ic|1=MODULES=(amdgpu radeon)}}.<br />
<br />
===== Set module parameters in modprobe.d =====<br />
<br />
Create the configuration [[modprobe]] files in {{ic|/etc/modprobe.d/}}, see {{man|5|modprobe.d}} for syntax details.<br />
<br />
For Southern Islands (SI) use option {{ic|1=si_support=1}}, for Sea Islands (CIK) use option {{ic|1=cik_support=1}}, e.g.:<br />
<br />
{{hc|/etc/modprobe.d/amdgpu.conf|2=<br />
options amdgpu si_support=1<br />
options amdgpu cik_support=1<br />
}}<br />
<br />
{{hc|/etc/modprobe.d/radeon.conf|2=<br />
options radeon si_support=0<br />
options radeon cik_support=0<br />
}}<br />
<br />
Make sure {{ic|modconf}} is in the the {{ic|HOOKS}} array in {{ic|/etc/mkinitcpio.conf}} and [[regenerate the initramfs]].<br />
<br />
===== Compile kernel which supports amdgpu driver =====<br />
When building or compiling a [[kernel]], {{ic|1=CONFIG_DRM_AMDGPU_SI=Y}} and/or {{ic|1=CONFIG_DRM_AMDGPU_CIK=Y}} should be set in the config.<br />
<br />
==== Disable loading radeon completely at boot ====<br />
<br />
The kernel may still probe and load the {{ic|radeon}} module depending on the specific graphics chip involved, but the module is unnecessary to have loaded after confirming {{ic|amdgpu}} works as expected. Reboot between each step to confirm it works before moving to the next step:<br />
<br />
# Use the module parameters on the kernel commandline method to ensure {{ic|amdgpu}} works as expected<br />
# Use the {{ic|1=MODULES=(amdgpu)}} mkinitcpio method but do '''not''' add {{ic|radeon}} to the configuration<br />
# Test that {{ic|1=modprobe -r radeon}} will remove the kernel module cleanly after logged into the desktop<br />
# Blacklist the {{ic|radeon}} module from being probed by the kernel during second stage boot:<br />
<br />
{{hc|/etc/modprobe.d/radeon.conf|2=<br />
blacklist radeon<br />
}}<br />
<br />
The output of {{ic|lsmod}} and {{ic|dmesg}} should now only show the amdpgu driver loading, radeon should not be present. The directory {{ic|1=/sys/modules/radeon}} should not exist.<br />
<br />
=== AMDGPU PRO ===<br />
<br />
AMD provides a proprietary, binary userland driver called [[AMDGPU PRO]], which works on top of the open-source AMDGPU kernel driver.<br />
<br />
From [https://www.phoronix.com/vr.php?view=27266 Radeon Software 18.50 vs Mesa 19 benchmarks] article: When it comes to OpenGL games, the RadeonSI Gallium3D driver simply dominates the proprietary AMD OpenGL driver.<br />
<br />
Install the {{AUR|amdgpu-pro-libgl}}. Optionally install the {{AUR|lib32-amdgpu-pro-libgl}} package for 32-bit application support.<br />
<br />
{{Note|Users of graphic cards other than Radeon Pro are [https://www.amd.com/en/support/kb/release-notes/amdgpu-installation advised to use the amdgpu graphics stack].}}<br />
<br />
=== ACO compiler ===<br />
<br />
The [https://steamcommunity.com/games/221410/announcements/detail/1602634609636894200 ACO compiler] is an open source shader compiler created and developed by [[wikipedia:Valve_Corporation|Valve Corporation]] to directly compete with the [https://llvm.org/ LLVM compiler], the [https://github.com/GPUOpen-Drivers/AMDVLK AMDVLK drivers], as well as [[wikipedia:Windows_10|Windows 10]]. It offers lesser compilation time and also performs better while gaming than LLVM and AMDVLK.<br />
<br />
Some benchmarks can be seen in [https://itsfoss.com/linux-games-performance-boost-amd-gpu/ It's FOSS] and Phoronix [https://www.phoronix.com/scan.php?page=article&item=radv-aco-llvm&num=1 (1)] [https://www.phoronix.com/scan.php?page=article&item=radv-aco-gcn10&num=1 (2)] [https://www.phoronix.com/scan.php?page=article&item=mesa20radv-aco-amdvlk&num=1 (3)].<br />
<br />
Since {{Pkg|mesa}} version 20.2, the ACO compiler is enabled by default.<br />
<br />
== Loading ==<br />
<br />
The {{ic|amdgpu}} kernel module is supposed to load automatically on system boot.<br />
<br />
If it does not:<br />
<br />
* Make sure to [[#Enable Southern Islands (SI) and Sea Islands (CIK) support]] when needed.<br />
* Make sure you have the latest {{Pkg|linux-firmware}} package installed. This driver requires the latest firmware for each model to successfully boot.<br />
* Make sure you do '''not''' have {{ic|nomodeset}} or {{ic|1=vga=}} as a [[kernel parameter]], since {{ic|amdgpu}} requires [[KMS]].<br />
* Check that you have not disabled {{ic|amdgpu}} by using any [[Kernel_modules#Blacklisting|kernel module blacklisting]].<br />
<br />
It is possible it loads, but late, after the X server requires it. In this case:<br />
<br />
* See [[Kernel mode setting#Early KMS start]].<br />
<br />
== Xorg configuration ==<br />
<br />
[[Xorg]] will automatically load the driver and it will use your monitor's EDID to set the native resolution. Configuration is only required for tuning the driver.<br />
<br />
If you want manual configuration, create {{ic|/etc/X11/xorg.conf.d/20-amdgpu.conf}}, and add the following:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-amdgpu.conf|2=<br />
Section "Device"<br />
Identifier "AMD"<br />
Driver "amdgpu"<br />
EndSection<br />
}}<br />
<br />
Using this section, you can enable features and tweak the driver settings, see {{man|4|amdgpu}} first before setting driver options.<br />
<br />
=== Tear free rendering ===<br />
<br />
''TearFree'' controls tearing prevention using the hardware page flipping mechanism. If this option is set, the default value of the property is 'on' or 'off' accordingly. If this option is not set, the default value of the property is auto, which means that TearFree is on for rotated outputs, outputs with RandR transforms applied and for RandR 1.4 slave outputs, otherwise off:<br />
<br />
Option "TearFree" "true"<br />
<br />
You can also enable TearFree temporarily with [[xrandr]]: <br />
<br />
$ xrandr --output ''output'' --set TearFree on<br />
<br />
Where {{ic|''output''}} should look like {{ic|DisplayPort-0}} or {{ic|HDMI-A-0}} and can be acquired by running {{ic|xrandr -q}}.<br />
<br />
=== DRI level ===<br />
<br />
''DRI'' sets the maximum level of DRI to enable. Valid values are ''2'' for DRI2 or ''3'' for DRI3. The default is ''3'' for DRI3 if the [[Xorg]] version is >= 1.18.3, otherwise DRI2 is used:<br />
<br />
Option "DRI" "3"<br />
<br />
=== Variable refresh rate ===<br />
<br />
See [[Variable refresh rate]].<br />
<br />
=== 10-bit color ===<br />
<br />
{{Warning|Many applications may have graphical artifacts or crash when 10-bit color is enabled.<br />
<br />
This notably includes [[Steam/Troubleshooting#Steam:_An_X_Error_occurred|Steam, which crashes with an X Error]], and all Vulkan applications<br />
}}<br />
<br />
Newer AMD cards support 10bpc color, but the default is 24-bit color and 30-bit color must be explicitly enabled. Enabling it can reduce visible banding/artifacts in gradients, if the applications support this too. To check if your monitor supports it search for "EDID" in your [[Xorg#General|Xorg log file]] (e.g. {{ic|/var/log/Xorg.0.log}} or {{ic|~/.local/share/xorg/Xorg.0.log}}):<br />
<br />
[ 336.695] (II) AMDGPU(0): EDID for output DisplayPort-0<br />
[ 336.695] (II) AMDGPU(0): EDID for output DisplayPort-1<br />
[ 336.695] (II) AMDGPU(0): Manufacturer: DEL Model: a0ec Serial#: 123456789<br />
[ 336.695] (II) AMDGPU(0): Year: 2018 Week: 23<br />
[ 336.695] (II) AMDGPU(0): EDID Version: 1.4<br />
[ 336.695] (II) AMDGPU(0): Digital Display Input<br />
'''[ 336.695] (II) AMDGPU(0): 10 bits per channel'''<br />
<br />
To check whether it is currently enabled search for "Depth"):<br />
<br />
[ 336.618] (**) AMDGPU(0): Depth 30, (--) framebuffer bpp 32<br />
[ 336.618] (II) AMDGPU(0): Pixel depth = 30 bits stored in 4 bytes (32 bpp pixmaps)<br />
<br />
With the default configuration it will instead say the depth is 24, with 24 bits stored in 4 bytes.<br />
<br />
To check whether 10-bit works, exit Xorg if you have it running and run {{ic|Xorg -retro}} which will display a black and white grid, then press {{ic|Ctrl-Alt-F1}} and {{ic|Ctrl-C}} to exit X, and run {{ic|Xorg -depth 30 -retro}}. If this works fine, then 10-bit is working.<br />
<br />
To launch in 10-bit via {{ic|startx}}, use {{ic|startx -- -depth 30}}. To permanently enable it, create or add to:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-amdgpu.conf|2=<br />
Section "Screen"<br />
Identifier "asdf"<br />
DefaultDepth 30<br />
EndSection<br />
}}<br />
<br />
=== Reduce output latency ===<br />
<br />
If you want to minimize latency you can disable page flipping and tear free:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-amdgpu.conf|2=<br />
Section "Device"<br />
Identifier "AMD"<br />
Driver "amdgpu"<br />
Option "EnablePageFlip" "off"<br />
Option "TearFree" "false"<br />
EndSection<br />
}}<br />
<br />
See [[Gaming#Reducing DRI latency]] to further reduce latency.<br />
<br />
{{Note|Setting these options may cause tearing and short-lived artifacts to appear.}}<br />
<br />
== Features ==<br />
<br />
=== Video acceleration ===<br />
<br />
See [[Hardware video acceleration]].<br />
<br />
=== Monitoring ===<br />
<br />
Monitoring your GPU is often used to check the temperature and also the P-states of your GPU.<br />
<br />
==== CLI (default) ====<br />
<br />
To check your GPU's P-states, execute:<br />
$ cat /sys/class/drm/card0/device/pp_od_clk_voltage<br />
To monitor your GPU, execute:<br />
$ watch -n 0.5 cat /sys/kernel/debug/dri/0/amdgpu_pm_info<br />
To check your GPU utilization, execute:<br />
$ cat /sys/class/drm/card0/device/gpu_busy_percent<br />
To check your GPU frequency, execute:<br />
$ cat /sys/class/drm/card0/device/pp_dpm_sclk<br />
To check your GPU temperature, execute:<br />
$ cat /sys/class/drm/card0/device/hwmon/hwmon*/temp1_input<br />
To check your VRAM frequency, execute:<br />
$ cat /sys/class/drm/card0/device/pp_dpm_mclk<br />
To check your VRAM usage, execute:<br />
$ cat /sys/class/drm/card0/device/mem_info_vram_used<br />
To check your VRAM size, execute:<br />
$ cat /sys/class/drm/card0/device/mem_info_vram_total<br />
<br />
With [https://github.com/clbr/radeontop radeontop] utility you can view your GPU utilization, both for the total activity percent and individual blocks. Install it with {{Pkg|radeontop}} package. If it does not recognize your GPU, try {{AUR|radeontop-git}}.<br />
<br />
==== GUI ====<br />
<br />
* {{App|WattmanGTK|A GTK GUI tool to monitor your GPU's temperatures P-states|https://github.com/BoukeHaarsma23/WattmanGTK|{{AUR|wattman-gtk-git}}}}.<br />
* {{App|TuxClocker|A Qt5 monitoring and overclocking tool.|https://github.com/Lurkki14/tuxclocker|{{AUR|tuxclocker}}}}<br />
<br />
=== Overclocking ===<br />
<br />
Since Linux 4.17, it is possible to adjust clocks and voltages of the graphics card via {{Ic|1=/sys/class/drm/card0/device/pp_od_clk_voltage}}.<br />
<br />
==== Boot parameter ====<br />
<br />
It is required to unlock access to adjust clocks and voltages in sysfs by appending the [[Kernel parameter]] {{Ic|1=amdgpu.ppfeaturemask=0xffffffff}}.<br />
<br />
==== Manual (default) ====<br />
<br />
{{Note|In sysfs, paths like {{Ic|1=/sys/class/drm/...}} are just symlinks and may change between reboots. Persistent locations can be found in {{Ic|1=/sys/devices/}}, e.g. {{Ic|1=/sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0/}}. Adjust the commands accordingly for a reliable result.}}<br />
<br />
To set the GPU clock for the maximum P-state 7 on e.g. a Polaris GPU to 1209MHz and 900mV voltage, run:<br />
# echo "s 7 1209 900" > /sys/class/drm/card0/device/pp_od_clk_voltage<br />
The same procedure can be applied to the VRAM, e.g. maximum P-state 2 on Polaris 5xx series cards:<br />
# echo "m 2 1850 850" > /sys/class/drm/card0/device/pp_od_clk_voltage<br />
{{Warning|1=Double check the entered values, as mistakes might instantly cause fatal hardware damage!}}<br />
To apply, run<br />
# echo "c" > /sys/class/drm/card0/device/pp_od_clk_voltage<br />
To check if it worked out, read out clocks and voltage under 3D load:<br />
# watch -n 0.5 cat /sys/kernel/debug/dri/0/amdgpu_pm_info<br />
You can reset to the default values using this:<br />
# echo "r" > /sys/class/drm/card0/device/pp_od_clk_voltage<br />
<br />
It is also possible to forbid the driver so switch to certain P-states, e.g. to workaround problems with deep powersaving P-states like flickering artifacts or stutter. To force the highest VRAM P-state on a Polaris RX 5xx card, while still allowing the GPU itself to run with lower clocks, run:<br />
# echo "manual" > /sys/class/drm/card0/device/power_dpm_force_performance_level<br />
# echo "2" > /sys/class/drm/card0/device/pp_dpm_mclk<br />
Allow only the three highest GPU P-states:<br />
# echo "5 6 7" > /sys/class/drm/card0/device/pp_dpm_sclk<br />
<br />
To set the allowed maximum power consumption of the GPU to e.g. 50 Watts, run<br />
# echo 50000000 > /sys/class/drm/card0/device/hwmon/hwmon0/power1_cap<br />
<br />
Until Linux kernel 4.20, it will only be possible to decrease the value, not increase.<br />
<br />
{{Note|The above procedure was tested with a Polaris RX 560 card. There may be different behavior or bugs with different GPUs.}}<br />
<br />
==== Assisted ====<br />
<br />
If you are not inclined to fully manually overclock your GPU, there are some overclocking tools that are offered by the community to assist you to overclock and monitor your AMD GPU.<br />
<br />
===== CLI tools =====<br />
<br />
* {{App|amdgpu-clocks|A script that can be used to monitor and set custom power states for AMD GPUs. It also offers a Systemd service to apply the settings automatically upon boot.|https://github.com/sibradzic/amdgpu-clocks|{{AUR|amdgpu-clocks-git}}}}<br />
<br />
===== GUI tools =====<br />
<br />
* {{App|TuxClocker|A Qt5 monitoring and overclocking tool.|https://github.com/Lurkki14/tuxclocker|{{AUR|tuxclocker}}}}<br />
* {{App|CoreCtrl|A GUI overclocking tool with a WattMan-like UI that supports per-application profiles.|https://gitlab.com/corectrl/corectrl|{{AUR|corectrl}}}}<br />
<br />
==== Startup on boot ====<br />
<br />
If you want your settings to apply automatically upon boot, consider looking at this [https://www.reddit.com/r/Amd/comments/agwroj/how_to_overclock_your_amd_gpu_on_linux/ Reddit thread] to configure and apply your settings on boot.<br />
<br />
=== Power profiles ===<br />
<br />
AMDGPU offers several optimizations via power profiles, one of the most commonly used is the compute mode for OpenCL intensive applications. Available power profiles can be listed with:<br />
{{hc|cat /sys/class/drm/card0/device/pp_power_profile_mode|<br />
NUM MODE_NAME SCLK_UP_HYST SCLK_DOWN_HYST SCLK_ACTIVE_LEVEL MCLK_UP_HYST MCLK_DOWN_HYST MCLK_ACTIVE_LEVEL<br />
0 BOOTUP_DEFAULT: - - - - - -<br />
1 3D_FULL_SCREEN: 0 100 30 0 100 10<br />
2 POWER_SAVING: 10 0 30 - - -<br />
3 VIDEO: - - - 10 16 31<br />
4 VR: 0 11 50 0 100 10<br />
5 COMPUTE *: 0 5 30 10 60 25<br />
6 CUSTOM: - - - - - -<br />
}}<br />
<br />
{{Note|{{ic|card0}} identifies a specific GPU in you machine, in case of multiple GPUs be sure to address the right one.}}<br />
<br />
To use a specific power profile you should first enable manual control over them with:<br />
# echo "manual" > /sys/class/drm/card0/device/power_dpm_force_performance_level<br />
<br />
Then to select a power profile by writing the NUM field associated with it, e.g. to enable COMPUTE run:<br />
# echo "5" > /sys/class/drm/card0/device/pp_power_profile_mode<br />
<br />
{{Note|Power profile changes should be reapplied at every boot, see [[#Startup on boot]] to automate this.}}<br />
<br />
=== Enable GPU display scaling ===<br />
<br />
{{Move|xrandr|Not specific to AMDGPU.|section=Moving "Enable GPU display scaling" to xrandr}}<br />
<br />
To avoid the usage of the scaler which is built in the display, and use the GPU own scaler instead, when not using the native resolution of the monitor, execute:<br />
$ xrandr --output ''output'' --set "scaling mode" ''scaling_mode''<br />
Possible values for {{ic|"scaling mode"}} are: {{ic|None}}, {{ic|Full}}, {{ic|Center}}, {{ic|Full aspect}}.<br />
<br />
* To show the available outputs and settings, execute:<br />
$ xrandr --prop<br />
<br />
* To set {{ic|1=scaling mode = Full aspect}} for just every available output, execute:<br />
$ for output in $(xrandr --prop | grep -E -o -i "^[A-Z\-]+-[0-9]+"); do xrandr --output "$output" --set "scaling mode" "Full aspect"; done<br />
<br />
== Troubleshooting ==<br />
<br />
=== Xorg or applications will not start ===<br />
<br />
* "(EE) AMDGPU(0): [DRI2] DRI2SwapBuffers: drawable has no back or front?" error after opening ''glxgears'', can open Xorg server but OpenGL applications crash.<br />
* "(EE) AMDGPU(0): Given depth (32) is not supported by amdgpu driver" error, Xorg will not start.<br />
<br />
Setting the screen's depth under Xorg to 16 or 32 will cause problems/crash. To avoid that, you should use a standard screen depth of 24 by adding this to your "screen" section:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/10-screen.conf|<br />
Section "Screen"<br />
Identifier "Screen"<br />
DefaultDepth 24<br />
SubSection "Display"<br />
Depth 24<br />
EndSubSection<br />
EndSection<br />
}}<br />
<br />
=== Screen artifacts and frequency problem ===<br />
<br />
[[ATI#Dynamic power management|Dynamic power management]] may cause screen artifacts to appear when displaying to monitors at higher frequencies (anything above 60Hz) due to issues in the way GPU clock speeds are managed[https://bugs.freedesktop.org/show_bug.cgi?id=96868][https://gitlab.freedesktop.org/drm/amd/-/issues/234].<br />
<br />
A workaround [https://bugs.freedesktop.org/show_bug.cgi?id=96868#c13] is saving {{ic|high}} or {{ic|low}} in {{ic|/sys/class/drm/card0/device/power_dpm_force_performance_level}}.<br />
<br />
To make it persistent, you may create a [[udev]] rule:<br />
<br />
{{hc|/etc/udev/rules.d/30-amdgpu-pm.rules|<nowiki><br />
KERNEL=="card0", SUBSYSTEM=="drm", DRIVERS=="amdgpu", ATTR{device/power_dpm_force_performance_level}="high"<br />
</nowiki>}}<br />
<br />
To determine the {{ic|KERNEL}} name execute: <br />
<br />
$ udevadm info --attribute-walk /sys/class/drm/card0 | grep "KERNEL="<br />
<br />
There is also a GUI solution [https://github.com/marazmista/radeon-profile] where you can manage the "power_dpm" with {{aur|radeon-profile-git}} and {{aur|radeon-profile-daemon-git}}.<br />
<br />
==== Artifacts in Chromium ====<br />
<br />
If you see artifacts in [[Chromium]], try to force the vulkan based backend. Go to {{ic|chrome://flags}} and ''enable'' {{ic|#ignore-gpu-blacklist}} and {{ic|#enable-vulkan}}.<br />
<br />
=== R9 390 series poor performance and/or instability ===<br />
<br />
If you experience issues [https://gitlab.freedesktop.org/mesa/mesa/-/issues/1222] with a AMD R9 390 series graphics card, set {{ic|1=radeon.cik_support=0 radeon.si_support=0 amdgpu.cik_support=1 amdgpu.si_support=1 amdgpu.dc=1}} as [[kernel parameters]] to force the use of amdgpu driver instead of radeon.<br />
<br />
If it still does not work, try disabling DPM, by setting the [[kernel parameters]] to: {{ic|1=radeon.cik_support=0 radeon.si_support=0 amdgpu.cik_support=1 amdgpu.si_support=1}}<br />
<br />
=== Freezes with "[drm] IP block:gmc_v8_0 is hung!" kernel error ===<br />
<br />
If you experience freezes and kernel crashes during a GPU intensive task with the kernel error " [drm] IP block:gmc_v8_0 is hung!" [https://gitlab.freedesktop.org/drm/amd/issues/226], a workaround is to set {{ic|1=amdgpu.vm_update_mode=3}} as [[kernel parameters]] to force the GPUVM page tables update to be done using the CPU. Downsides are listed here [https://gitlab.freedesktop.org/drm/amd/-/issues/226#note_308665].<br />
<br />
=== Cursor corruption ===<br />
<br />
If you experience issues with the mouse cursor sometimes not rendering properly, set {{ic|Option "SWCursor" "True"}} in the {{ic|"Device"}} section of the {{ic|/etc/X11/xorg.conf.d/20-amdgpu.conf}} configuration file.<br />
<br />
If you are using {{ic|xrandr}} for scaling and the cursor is flickering or disappearing, you may be able to fix it by setting the {{ic|TearFree}} property: {{ic|xrandr --output HDMI-A-0 --set TearFree on}}.<br />
<br />
=== System freeze or crash when gaming on Vega cards ===<br />
<br />
[[ATI#Dynamic power management|Dynamic power management]] may cause a complete system freeze whilst gaming due to issues in the way GPU clock speeds are managed. [https://gitlab.freedesktop.org/drm/amd/-/issues/716] A workaround is to disable dynamic power management, see [[ATI#Dynamic power management]] for details.<br />
<br />
=== Navi power consumption ===<br />
<br />
Some users have reported higher than usual idle power consumption when using kernel 5.3. There is a [https://cgit.freedesktop.org/~agd5f/linux/tag/?h=drm-next-5.4-2019-08-30 patch set] available for kernel 5.4 that appears to fix the issues.<br />
<br />
=== WebRenderer (Firefox) corruption ===<br />
<br />
Artifacts and other anomalies may present themselves (e.g. inability to select extension options) when [[Firefox/Tweaks#Enable WebRender compositor|WebRenderer]] is force enabled by the user. Workaround is to fall back to OpenGL compositing.<br />
<br />
=== Double-speed or "chipmunk" audio, or no audio when a 4K@60Hz device is connected ===<br />
<br />
This is sometimes caused by a communication issue between an AMDGPU device and a 4K display connected over HDMI. A possible workaround is to enable HDR or "Ultra HD Deep Color" via the display's built-in settings. On many Android based TVs, this means setting this to "Standard" instead of "Optimal".<br />
<br />
=== Issues with power management / dynamic re-activation of a discrete amdgpu graphics card ===<br />
<br />
If you encounter issues similar to [https://gitlab.freedesktop.org/drm/amd/-/issues/1820], you can workaround the issue by setting the [[kernel parameter]] {{ic|1=amdgpu.runpm=0}}, which prevents the dGPU from being powered down dynamically at runtime.<br />
<br />
== See also ==<br />
<br />
* [[Gentoo:AMDGPU]]</div>Iaz3https://wiki.archlinux.org/index.php?title=Steam/Game-specific_troubleshooting&diff=611594Steam/Game-specific troubleshooting2020-05-09T05:56:08Z<p>Iaz3: LD_PRELOAD isn't actually required to fix the problem, simply renaming the offending file will allow the system version to be used.</p>
<hr />
<div>[[Category:Gaming]]<br />
[[ja:Steam/ゲーム別のトラブルシューティング]]<br />
== Introduction ==<br />
<br />
See [[Steam/Troubleshooting]] first.<br />
<br />
This page assumes familiarity with the [[Steam#Directory structure]], [[Steam#Launch options]], [[environment variables]], the [[Steam runtime]] and [[Steam/Troubleshooting#Debugging shared libraries|shared libraries]]. The {{ic|''GAME''}} pseudo-variable is used to refer to a game's directory. When the text reads "''run the game with {{ic|1=FOO=bar}}''" it is implied that you either update your launch options or run the game from the command-line with the environment variable.<br />
<br />
== Contributing ==<br />
<br />
* Use "game directory" or the {{ic|''GAME''}} pseudo-variable to refer to a game's directory.<br />
* Link bug reports and sources of workarounds.<br />
<br />
== Other sources ==<br />
<br />
The following links offer even more fixes and tweaks for various games which would otherwise exceed this article's purpose:<br />
<br />
* [https://pcgamingwiki.com/wiki/Home PC Gaming Wiki]<br />
<br />
== Common steps ==<br />
<br />
=== OpenSSL 1.0 setup ===<br />
<br />
Some Steam games are built against OpenSSL 1.0. ({{bug|53618}})<br />
<br />
Install {{Pkg|lib32-openssl-1.0}} and run the game with {{ic|1=LD_LIBRARY_PATH=/usr/lib/openssl-1.0}}.<br />
<br />
=== Adobe Air setup ===<br />
<br />
The package {{AUR|adobe-air-sdk}} installs Adobe Air not in the place where the game expects it to be, fix this by creating the following symlink:<br />
<br />
# ln -s "/opt/adobe-air-sdk/runtimes/air/linux/Adobe AIR" "/opt/Adobe AIR"<br />
<br />
Adobe AIR requires you to accept its EULA by creating the file {{ic|~/.appdata/Adobe/AIR/eulaAccepted}} containing {{ic|2}}.<br />
<br />
=== Steam Link ===<br />
<br />
Currently Steam Link does not work with Wayland. You will only see a blank screen or even flickering when connecting to a Steam host running on Wayland. So you have to disable Wayland in /etc/gdm/custom.conf:<br />
<br />
WaylandEnable=false<br />
<br />
And reboot before trying again.<br />
<br />
=== Squares or invisible symbols, special characters and cyrillic letters in Source-based games ===<br />
<br />
Any special character may produce a square or an empty space mark in the game, main menu and game console. In practice, any characters other than latin ones are not working. The problem is that {{ic|Bitstream Vera Sans}} is configured as the system primary default font for latin sans-serif fonts.<br />
<br />
First, make sure that per-user font customization files are enabled, i.e. the following file exist:<br />
<br />
/etc/fonts/conf.d/50-user.conf<br />
<br />
Next, create {{ic|fonts.conf}} file in your fontconfig directory with the following content or if the file already exist, append only the alias section to the file:<br />
<br />
{{hc|~/.config/fontconfig/fonts.conf|2=<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>sans-serif</family><br />
<prefer><br />
<family>DejaVu Sans</family><br />
<family>Verdana</family><br />
<family>Arial</family><br />
<family>Albany AMT</family><br />
<family>Luxi Sans</family><br />
<family>Nimbus Sans L</family><br />
<family>Nimbus Sans</family><br />
<family>Helvetica</family><br />
<family>Lucida Sans Unicode</family><br />
<family>BPG Glaho International</family> <!-- lat,cyr,arab,geor --><br />
<family>Tahoma</family> <!-- lat,cyr,greek,heb,arab,thai --><br />
</prefer><br />
</alias><br />
</fontconfig><br />
}}<br />
<br />
== Games ==<br />
<br />
=== 7 Days To Die ===<br />
<br />
If game crash on start, add the following to Steam launch options:<br />
<br />
LD_PRELOAD="libpthread.so.0 libGL.so.1" __GL_THREADED_OPTIMIZATIONS=1 %command% -force-glcore<br />
<br />
If game does not recognize the resolution launch the game with '''Game Launcher''' and check the '''Unity screen selector''' option to correct the resolution. This will give you a GUI that can select the correct screen and when the game is started.<br />
<br />
{{Note|The game tends to crash or disfunction in windowed mode. It may be advisable to run it in full screen mode.}}<br />
<br />
If that does not help try running the game by checking the '''32-bit''' Game-engine in the launcher options.<br />
<br />
It will help the game performance if the '''GLCore''' option is checked in launcher options.<br />
<br />
{{Note|The game does not accept {{ic|.dll}} mods if installing mods. Always check if the mod is of {{ic|.dll}} type}}<br />
<br />
=== Alien Isolation ===<br />
<br />
==== Missing libpcre.so.3 and libidn.so.11 ====<br />
<br />
$ ln -s /usr/lib/libpcre.so '''GAME''/lib/x86_64/libpcre.so.3'<br />
$ ln -s /usr/lib/libidn.so '''GAME''/lib/x86_64/libidn.so.11'<br />
<br />
Append {{ic|./lib/x86_64}} to your {{ic|LD_LIBRARY_PATH}}.[https://steamcommunity.com/app/214490/discussions/0/154644705028020291/]<br />
<br />
=== Amnesia: The Dark Descent ===<br />
<br />
Dependencies:<br />
[https://steamcommunity.com/app/221410/discussions/0/864957183198111387/]<br />
<br />
* {{AUR|lib32-freealut}}<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libxmu}}<br />
* {{pkg|lib32-sdl_ttf}}<br />
<br />
=== And Yet It Moves ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|lib32-libjpeg6-turbo}}<br />
* {{Pkg|lib32-libpng12}}<br />
* {{Pkg|lib32-libtheora}}<br />
* {{Pkg|lib32-libtiff4}}<br />
<br />
==== Game does not start ====<br />
<br />
When the game refuses to launch and prints one of the following error messages:<br />
<br />
readlink: extra operand ‘Yet’<br>Try 'readlink --help' for more information.<br />
<br />
This script must be run as a user with write priviledges to game directory<br />
<br />
Open {{ic|''GAME''/AndYetItMovesSteam.sh}} and surround {{ic|${BASH_SOURCE[0]} }} in the following line with double quotes.<br />
<br />
ayim_dir="$(dirname "$(readlink -f ${BASH_SOURCE[0]})")"<br />
<br />
=== Anodyne ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|adobe-air-sdk}}, follow [[#Adobe Air setup]]<br />
* {{pkg|xterm}} (probably not required)<br />
<br />
==== Play with a controller: joy2key configuration ====<br />
<br />
Configuration example to play Anodyne with an XBox 360 Wireless Controller<br />
<br />
COMMON<br />
-dev /dev/input/js0<br />
-X<br />
-thresh -18000 18000 -18000 18000 -18000 18000 -18000 18000 -18000 18000 -18000 18000 -18000 18000 -18000 18000<br />
-axis Left Right Up Down blank blank blank blank blank blank blank blank Left Right Up Down<br />
-buttons c x Return<br />
<br />
Save this to {{ic|~/.joy2keyrc}} and start joy2key after you start Anodyne<br />
<br />
joy2key -rcfile ~/.joy2keyrc<br />
<br />
=== Anomaly Warzone Earth ===<br />
<br />
==== Leave fullsrceen ====<br />
<br />
There are no ingame settings for this, but fullscreen can be toggled with Alt-Enter<br />
<br />
==== Infinite loading ====<br />
<br />
Create file {{ic|loadfix.c}} next to the game executable: [https://steamcommunity.com/app/282070/discussions/0/610573751159186268/?ctp=4#c530647080133257413 src]<br />
<br />
#define _GNU_SOURCE <br />
#include <dlfcn.h> <br />
#include <semaphore.h> <br />
#include <stdio.h> <br />
#include <time.h> <br />
#include <unistd.h> <br />
static int (*_realSemTimedWait)(sem_t *, const struct timespec *) = NULL; <br />
<br />
int sem_timedwait(sem_t *sem, const struct timespec *abs_timeout)<br />
{ <br />
if (abs_timeout->tv_nsec >= 1000000000)<br />
{ <br />
//fprintf(stderr, "to: %lu:%lu\n", abs_timeout->tv_sec, abs_timeout->tv_nsec); <br />
((struct timespec *)abs_timeout)->tv_nsec -= 1000000000; <br />
((struct timespec *)abs_timeout)->tv_sec++; <br />
} <br />
return _realSemTimedWait(sem, abs_timeout); <br />
} <br />
<br />
__attribute__((constructor)) void init(void) <br />
{<br />
_realSemTimedWait = dlsym(RTLD_NEXT, "sem_timedwait");<br />
}<br />
<br />
Compile with {{ic|gcc -m32 -o loadfix.so loadfix.c -ldl -shared -fPIC -Wall -Wextra}}<br />
<br />
Launch with {{ic|1=LD_PRELOAD=$LD_PRELOAD:./loadfix.so %command%}}<br />
<br />
==== Gamepad not working ====<br />
<br />
You have to enable keyboard control and map gamepad to keys.<br />
<br />
Config for Steam: {{ic|steam://controllerconfig/91200/1498735506}}<br />
<br />
=== Aquaria ===<br />
<br />
==== Mouse pointer gets stuck in one direction ====<br />
<br />
If the mouse pointer gets stuck in one direction, make sure {{ic|''GAME''/usersettings.xml}} contains {{ic|1=<JoystickEnabled on="0" />}}.<br />
<br />
If that does not fix the issue, try unplugging any joysticks or joystick adapter devices you have plugged in.<br />
<br />
=== ARK: Survival Evolved ===<br />
<br />
==== Game does not start, displays text window with unreadable text ====<br />
<br />
Run the game with {{ic|1=MESA_GL_VERSION_OVERRIDE=4.0 MESA_GLSL_VERSION_OVERRIDE=400}}.<br />
<br />
==== Gray water ====<br />
<br />
Download the TheCenter map and copy {{ic|Water_DepthBlur_MIC.uasset}} from that map into TheIsland as described [https://www.gamingonlinux.com/articles/heres-a-way-to-fix-the-broken-water-in-ark-survival-evolved-on-linux.10530 here].<br />
<br />
Ragnarok uses TheIsland's texture, so the same procedure fixes the issue on Ragnarok as well.<br />
<br />
==== Segmentation fault on startup ====<br />
<br />
Caused by the games packaged libopenal. Use system libopenal to solve the segfault by running the game with with {{ic|1=LD_PRELOAD=/usr/lib/libopenal.so.1}}<br />
<br />
=== Crash on joining a game ===<br />
<br />
Set steam to 'offline mode' and try again<br />
<br />
=== Audiosurf 2 ===<br />
<br />
==== error. unable to load song <filename> ,came back with zero duration ====<br />
<br />
If you get this in your log, install {{pkg|pulseaudio-alsa}}.<br />
<br />
=== BADLAND: Game of the Year Edition ===<br />
<br />
Refer to [[#Missing libcurl.so.4 or version CURL_OPENSSL_3 not found]].<br />
<br />
=== Beat Cop ===<br />
<br />
==== "BeatCop.x86_64" is not responding ====<br />
<br />
Run {{ic|BeatCop.x86}} instead of {{ic|BeatCop.x86_64}}.<br />
<br />
=== Binding of Isaac: Rebirth ===<br />
<br />
==== No sound ====<br />
<br />
{{Note|This also helps with Never Alone (Kisima Ingitchuna) and No Time to Explain.}}<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
Adjust the audio levels in the game options.<br />
<br />
=== BioShock Infinite ===<br />
<br />
==== Game launching on wrong monitor in fullscreen mode ====<br />
<br />
Add the following launch option:<br />
--eon_force_display=1<br />
<br />
Various more fixes and tweaks can be found [https://pcgamingwiki.com/wiki/BioShock_Infinite here]<br />
<br />
=== BLACKHOLE ===<br />
<br />
Refer to [[#Missing libcurl.so.4 or version CURL_OPENSSL_3 not found]].<br />
<br />
=== Black Mesa ===<br />
<br />
Install {{AUR|lib32-gperftools}} for 32bit version of libtcmalloc_minimal.so.4 which is needed [https://steamcommunity.com/app/362890/discussions/1/340412628175324858/?ctp=7 Source].<br />
<br />
=== Block'hood ===<br />
<br />
==== White screen on startup ====<br />
<br />
When launched the game may only display a white screen with no interface and no way to play the game. Add "-screen-fullscreen 0" to launch options.<br />
<br />
=== The Book of Unwritten Tales ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|lib32-jasper}}<br />
* {{AUR|lib32-libxaw}}<br />
<br />
If the game does not start, uncheck: ''Properties > Enable Steam Community In-Game''.<br />
<br />
The game is known to segfault when opening the settings and possibly during or before playing. A workaround from the [http://steamcommunity.com/app/221410/discussions/3/846939071081758230/#p2 Steam discussions] is to replace the game's {{ic|RenderSystem_GL.so}} with one from Debian's repositories. To do that download [https://launchpad.net/ubuntu/+archive/primary/+files/libogre-1.7.4_1.7.4-3_i386.deb this deb file], and extract it with {{Pkg|dpkg}}:<br />
<br />
$ dpkg -x libogre-*.deb outdir<br />
<br />
Now replace {{ic|''GAME''/lib/32/RenderSystem_GL.so}} with the one extracted from the {{ic|.deb}} package.<br />
<br />
=== BRAIN/OUT ===<br />
<br />
If the game does not start with error message saying "invalid app configuration".<br />
Change directory to game folder:<br />
<br />
$ cd ~/.steam/steam/steamapps/common/BrainOut/<br />
<br />
Run game directly:<br />
<br />
$ java -jar brainout-steam.jar<br />
<br />
You need to have steam running in the background.<br />
<br />
=== The Book of Unwritten Tales: The Critter Chronicles ===<br />
<br />
See [[#The Book of Unwritten Tales]].<br />
<br />
To prevent the game from crashing at the end credits, change the size of the credits image as described [http://steamcommunity.com/app/221830/discussions/0/828925849276110960/#c810921273836530791 here].<br />
<br />
=== Borderlands 2 ===<br />
<br />
==== Migrating saves from other platforms ====<br />
<br />
Borderlands 2 does not support cross-platform Steam Cloud syncing,<br />
you have to manually copy the files between platforms.<br />
Save locations can be found [https://pcgamingwiki.com/wiki/Borderlands_2#Game_data here].<br />
Make sure your user can access the files.<br />
<br />
==== Using Ctrl Key ====<br />
<br />
Borderlands 2 does not allow the {{ic|Ctrl}} key to be used by default. The game seems to be accessing keycodes and not keysyms, therefore xmodmap has no affect. A workaround is using ''setkeycodes'' to map the Ctrl-scancode to some other key, as described in [[Map scancodes to keycodes#Using setkeycodes]]. I use {{ic|setkeycodes 0x1d 56}} (as root) to map Ctrl to Alt before starting the game and {{ic|setkeycodes 0x1d 29}} to restore the default.<br />
<br />
==== Logging into SHiFT ====<br />
<br />
Out of the box you will not be able to log into SHiFT since the game expects certificates to be in {{ic|/usr/lib/ssl}}, which is where Ubuntu stores them. Arch however uses {{ic|/etc/ssl}}.<br />
To resolve the problem, run the game with {{ic|1=SSL_CERT_DIR=/etc/ssl/certs}}.<br />
<br />
==== Game crashes nearly instantly ====<br />
<br />
The game crashes in libopenal directly after launch.<br />
<br />
Possible solution 0: Run the game with the {{ic|-nostartupmovies}} flag. It no longer crashes in libopenal with a general protection error.<br />
<br />
Possible solution 1: As of lib32-openal version 1.18.0-1, the game crashes instantly. The possible solutions are to downgrade lib32-openal to 1.17.2-1, or to start the game with {{ic|LD_PRELOAD<nowiki>=</nowiki>'$HOME/.steam/root/ubuntu12_32/steam-runtime/i386/usr/lib/i386-linux-gnu/libopenal.so.1'}}.<br />
<br />
In case there are messages like this in the terminal:<br />
<br />
[ 671.617205] Borderlands2[2772]: segfault at 0 ip (null) sp 00000000ff9a462c error 14 in Borderlands2[8048000+235a000]<br />
<br />
The following change may help ([http://steamcommunity.com/app/49520/discussions/0/348292787746982160/ source]):<br />
LD_PRELOAD='./libcxxrt.so:/usr/$LIB/libstdc++.so.6' %command%<br />
<br />
Possible solution 2: Launch steam as {{ic|steam-native}} as described in [[Steam/Troubleshooting #Steam native runtime|#Steam native runtime]]. If the game still fails to launch even after installing the {{Pkg|steam-native-runtime}} meta package, then you might be missing some libraries. You can find those missing libraries as described in [[Steam/Troubleshooting #Debugging shared libraries|#Debugging shared libraries]].<br />
<br />
=== Borderlands: The Pre-Sequel ===<br />
<br />
See [[#Borderlands 2]].<br />
<br />
==== Keyboard not working ====<br />
<br />
This can occur with certain window managers e.g. [[dwm]]. Try a different [[window manager]], or install {{pkg|wmname}} and run:<br />
$ wmname LG3D<br />
<br />
see [[Java#Impersonate another window manager]] for more information.<br />
<br />
==== Not starting via Steam ====<br />
<br />
If the game appears as ''Running'', then syncs and closes when you launch it from Steam, try creating a {{ic|steam_appid.txt}} in the game directory<br />
containing {{ic|261640}}. This should resolve the issue and let you start the game directly from the game directory. If that does not work, try using the {{Pkg|steam-native-runtime}}.<br />
<br />
=== Chaos Engine ===<br />
<br />
Set your [[launch option]]s to:<br />
<br />
LD_PRELOAD="/usr/lib32/libpng16.so.16" %command%<br />
<br />
If such error is seen in terminal output of steam-native:<br />
/home/$USER/.local/share/Steam/steamapps/common/Chaos engine/TheChaosEngineSteam: /home/$USER/.local/share/Steam/steamapps/common/Chaos engine/lib/libz.so.1: version `ZLIB_1.2.9' not found (required by /usr/lib32/libpng16.so.16)<br />
/home/$USER/.local/share/Steam/steamapps/common/Chaos engine/TheChaosEngineSteam: /home/$USER/.local/share/Steam/steamapps/common/Chaos engine/lib/libz.so.1: version `ZLIB_1.2.3.4' not found (required by /usr/lib32/libpng16.so.16)<br />
<br />
Then link the system libz.so:<br />
cd ~/.local/share/Steam/steamapps/common/Chaos\ engine/lib<br />
mv libz.so.1 libz.so.1.old<br />
ln -s /lib/libz.so.1<br />
<br />
=== Cities in Motion 2 ===<br />
<br />
==== Dialog boxes fail to display properly ====<br />
<br />
You will not be able to read or see anything, and you will have this in your logs:<br />
Fontconfig error: "/etc/fonts/conf.d/10-scale-bitmap-fonts.conf", line 69: non-double matrix element<br />
Fontconfig error: "/etc/fonts/conf.d/10-scale-bitmap-fonts.conf", line 69: wrong number of matrix elements<br />
<br />
Workaround for the bug {{Bug|35039}} is available [http://bpaste.net/show/167019/ here] {{Dead link|2020|04|03|status=404}} (replace {{ic|/etc/fonts/conf.d/10-scale-bitmap-fonts.conf}}).<br />
<br />
=== Cities Skylines ===<br />
<br />
==== Game not starting ====<br />
<br />
If you set {{ic|$XDG_DATA_HOME}} to something other than {{ic|$HOME/.local/share}}, Cities Skylines will put some files in {{ic|$XDG_DATA_HOME/Paradox Interactive}} and some hard-coded in {{ic|~/.local/share/Paradox Interactive}}.<br />
Unset the Variable to fix this issue.<br />
<br />
==== Textures not rendering properly ====<br />
<br />
Run the game with {{ic|1=UNITY_DISABLE_GRAPHICS_DRIVER_WORKAROUNDS=yes}}.<br />
<br />
=== Civilization V ===<br />
<br />
Run the game with {{ic|1=LD_PRELOAD=/usr/lib32/libopenal.so.1 %command% }}.[https://steamcommunity.com/app/8930/discussions/0/1621726179576099775/] For old versions of PulseAudio (<12.0), use {{ic|1=LD_PRELOAD='./libcxxrt.so:/usr/$LIB/libstdc++.so.6:/usr/lib32/libopenal.so.1' %command% }}.[https://github.com/ValveSoftware/steam-for-linux/issues/4379] If libopenal.so.1 is not in /usr/lib32, you may need to install {{Pkg|lib32-openal}} after making sure multilib is enabled.[[Official repositories#multilib]]<br />
<br />
If you are experiencing heavy lag (less than 1fps) or the game crashes on startup, try adding the following paths to LD_PRELOAD: {{ic|1='/usr/$LIB/libgcc_s.so.1 /usr/$LIB/libxcb.so.1 /usr/$LIB/libgpg-error.so ./libcxxrt.so /usr/lib32/libstdc++.so.6 /usr/lib32/libopenal.so.1'}}.[https://forum.manjaro.org/t/civ-v-wont-launch-after-update/10825/6]<br />
==== Stuttering sound with PulseAudio ====<br />
<br />
See [[PulseAudio/Troubleshooting#Laggy sound]].<br />
<br />
==== Game crashes seconds after loading a map ====<br />
<br />
If you have a CPU with more than 8 threads (such as AMD Ryzen), set {{ic|MaxSimultaneousThreads}} to {{ic|16}} in {{ic|config.ini}} in game directory.[https://www.reddit.com/r/civ5/comments/5z77jr/game_crashes_randomly_on_linux_amd_ryzen/]<br />
<br />
==== Game crashes after intro video with "Unable to load texture (LoadingBaseGame.dds)" ====<br />
<br />
The issue is a result of the game calling some file in a case-insensitive manner.<br />
<br />
The solution is either to install the game on a case-insensitive file system like VFAT, or on a mount point for {{AUR|ciopfs}}.<br />
<br />
==== Game crashes on startup with an error in libpulsecommon-12.0.so" ====<br />
<br />
Run the game with {{ic|1=LD_PRELOAD=/usr/lib32/libopenal.so.1 %command%}}<br />
<br />
==== Steam Overlay not working ====<br />
<br />
If the Steam Overlay doesn't show up simply add<br />
LD_PRELOAD='/home/USERNAME/.local/share/Steam/ubuntu12_32/gameoverlayrenderer.so' %command%<br />
<br />
to the launch options in the properties of the game in Steam.<br />
<br />
=== Civilization: Beyond earth ===<br />
<br />
If you are getting an instant crash/close upon launch, make sure you have the following packages installed:<br />
<br />
* {{aur|lib32-intel-tbb}}<br />
* {{pkg|lib32-libcurl-compat}}<br />
* {{pkg|lib32-libcurl-gnutls}}<br />
* {{pkg|lib32-openal}}<br />
<br />
==== Segfault after a few minutes ====<br />
Backtrace:<br />
#0 0x08b71d06 in FireGrafix::DynamicsLock<Graphics::BuildingSkinnedDataDynamicConsts>::DynamicsLock(Graphics::SurfaceSet**, FireGrafix::SurfaceSetPoolAllocator*, unsigned short) ()<br />
#1 0x08c25ffc in cvLandmarkVisSystem::cvLandmarkVisDynamicConstantUpdaterSS::HandleBuildingShaderSkinned(Graphics::FGXShaderPackageInstanceView*, FireGrafix::FGXModelNode*, FGXVector4*) ()<br />
#2 0x08c25f34 in cvLandmarkVisSystem::cvLandmarkVisDynamicConstantUpdaterSS::UpdateNode(Graphics::FGXShaderPackageInstanceView*, FireGrafix::FGXModelNode*, FGXVector4*) ()<br />
#3 0x08c25e2c in FireGrafix::FGXModelRenderByNodeSSExample_Shadow<cvLandmarkVisSystem::cvLandmarkVisDynamicConstantUpdaterSS, 2, FireGrafix::FGXModelRenderEndSuperclass>::RenderNode(unsigned int*, FireGrafix::FGX_SPIV_GENERIC*, FireGrafix::FGXModelNode*, FGXVector4*) ()<br />
#4 0x08c24ff5 in cvLandmarkVisSystem::LandmarkRenderJob::Execute(unsigned int) ()<br />
#5 0x093d26d9 in Platform::JobTask::execute() ()<br />
#6 0xf749f3c0 in ?? () from /usr/lib32/libtbb.so.2<br />
#7 0xf7497551 in ?? () from /usr/lib32/libtbb.so.2<br />
#8 0xf7495fc3 in ?? () from /usr/lib32/libtbb.so.2<br />
#9 0xf7491b7e in ?? () from /usr/lib32/libtbb.so.2<br />
#10 0xf7491db7 in ?? () from /usr/lib32/libtbb.so.2<br />
#11 0xf78f4346 in start_thread () from /usr/lib32/libpthread.so.0<br />
#12 0xf7716026 in clone () from /usr/lib32/libc.so.6<br />
<br />
Segfault is caused by {{aur|lib32-intel-tbb}}. To fix the issue:<br />
# Download the [http://archive.ubuntu.com/ubuntu/pool/universe/t/tbb/libtbb2_4.2~20130725-1.1ubuntu1_i386.deb libtbb2 deb-package] from the Ubuntu archive.<br />
# Unpack {{ic|libtbb.so.2}} from {{ic|libtbb2_4.2_20130725-1.1ubuntu1_i386.deb/data.tar.xz/usr/lib}} into the game directory.<br />
# Run the game with {{ic|1=LD_PRELOAD='./libtbb.so.2'}}.<br />
<br />
=== Civilization VI ===<br />
<br />
Either run with steam-native, launch option {{ic|1=LD_PRELOAD=/usr/lib/libfreetype.so.6 %command%}}, or {{ic|1=env LD_PRELOAD='./libcxxrt.so:/usr/$LIB/libstdc++.so.6'}}. The latter will disable the Steam overlay.<br />
<br />
Follow [[#OpenSSL 1.0 setup]]. <br />
<br />
Ensure that Steam Workshop mods are disabled as certain ones may cause issues following loading. <br />
<br />
==== If Segfault Immediately on Start ====<br />
<br />
This is a strange corner case which happens infrequently at best (and the prerequisites for reproducing it are unknown), but the crash would look like this:<br />
<br />
# Immediate segfault on start, before any windows get created<br />
# The game creates {{ic|~/.local/share/aspyr-media/Sid Meier's Civilization VI/AppOptions.txt}}<br />
# The string {{ic|AppHost::BugSubmissionPackager::BugSubmissionPackager}} appears inhttp://store.steampowered.com/app/310080/Hatoful_Boyfriend/ the backtrace output when running the game under {{pkg|gdb}}<br />
## To run under {{pkg|gdb}}, first launch a shell and change into the game directory.<br />
## Then {{ic|echo 289070 > steam_appid.txt}} ''(otherwise the game won't launch outside of Steam itself)''<br />
## Then run something like {{ic|gdb -ex run -ex bt -ex quit --args ./Civ6 ./Civ6}}<br />
## The relevant info towards the end of the output should look like this:<br />
Thread 3 "Civ6" received signal SIGSEGV, Segmentation fault.<br />
[Switching to Thread 0x7fffe5d06700 (LWP 12315)]<br />
0x000000000201121e in AppHost::BugSubmissionPackager::BugSubmissionPackager(unsigned long, String::BasicT<Platform::StaticHeapAllocator<5, 0>, (String::Encoding)4> const&, String::BasicT<Platform::StaticHeapAllocator<5, 0>, (String::Encoding)0> const&, AppHost::ModuleVersionInfo const&) ()<br />
#0 0x000000000201121e in AppHost::BugSubmissionPackager::BugSubmissionPackager(unsigned long, String::BasicT<Platform::StaticHeapAllocator<5, 0>, (String::Encoding)4> const&, String::BasicT<Platform::StaticHeapAllocator<5, 0>, (String::Encoding)0> const&, AppHost::ModuleVersionInfo const&) ()<br />
#1 0x000000000200c796 in AppHost::_INTERNAL::SetupFXSPlatform(AppHost::AppEnvironment const*, AppHost::AppOptions*)<br />
()<br />
#2 0x000000000200fea0 in AppHost::RunApp(int, char**, AppHost::Application*) ()<br />
#3 0x000000000200f9bc in AppHost::RunApp(char*, AppHost::Application*) ()<br />
#4 0x0000000001112d98 in WinMain ()<br />
#5 0x00000000010bdab0 in ?? ()<br />
#6 0x00000000010bfb31 in ThreadHANDLE::ThreadProc(void*) ()<br />
#7 0x00007ffff473e08a in start_thread () from /usr/lib/libpthread.so.0<br />
#8 0x00007ffff38f747f in clone () from /usr/lib/libc.so.6<br />
<br />
If all of that is the case for you, the fix is pretty simple. Edit {{ic|~/.local/share/aspyr-media/Sid Meier's Civilization VI/AppOptions.txt}} and change the line reading {{ic|EnableBugCollection 1}} to {{ic|EnableBugCollection 0}}.<br />
<br />
Presumably this fix will prevent any automated bug reports from reaching Aspyr, should you encounter crashes/bugs in the future, but it will at least let the game launch properly.<br />
<br />
<br />
==== If Crash with Error "undefined symbol FT_Done_MM_Var" ====<br />
<br />
If the game crashed with error<br />
./GameGuide/Civ6: symbol lookup error: /usr/lib/libfontconfig.so.1: undefined symbol: FT_Done_MM_Var<br />
<br />
The solution is to set launch option to be <br />
<br />
LD_PRELOAD=/usr/lib/libfreetype.so.6 %command%<br />
<br />
==== If the game ends up being a grey-color blank screen ====<br />
<br />
The solution is to disable mods.<br />
<br />
=== CrossCode ===<br />
<br />
==== If FontConfig Errors on Start ====<br />
{{bc|<br />
...<br />
Fontconfig error: "/etc/fonts/fonts.conf", line 6: invalid attribute 'translate'<br />
Fontconfig error: "/etc/fonts/fonts.conf", line 6: invalid attribute 'selector'<br />
Fontconfig error: "/etc/fonts/fonts.conf", line 7: invalid attribute 'xmlns:its'<br />
Fontconfig error: "/etc/fonts/fonts.conf", line 7: invalid attribute 'version'<br />
Fontconfig warning: "/etc/fonts/fonts.conf", line 9: unknown element "description"<br />
Fontconfig warning: "/etc/fonts/conf.d/10-hinting-slight.conf", line 4: unknown element "its:rules"<br />
Fontconfig warning: "/etc/fonts/conf.d/10-hinting-slight.conf", line 5: unknown element "its:translateRule"<br />
Fontconfig error: "/etc/fonts/conf.d/10-hinting-slight.conf", line 5: invalid attribute 'translate'<br />
Fontconfig error: "/etc/fonts/conf.d/10-hinting-slight.conf", line 5: invalid attribute 'selector'<br />
Fontconfig error: "/etc/fonts/conf.d/10-hinting-slight.conf", line 6: invalid attribute 'xmlns:its'<br />
Fontconfig error: "/etc/fonts/conf.d/10-hinting-slight.conf", line 6: invalid attribute 'version'<br />
Fontconfig warning: "/etc/fonts/conf.d/10-hinting-slight.conf", line 8: unknown element "description"<br />
Fontconfig warning: "/etc/fonts/conf.d/10-scale-bitmap-fonts.conf", line 4: unknown element "its:rules"<br />
Fontconfig warning: "/etc/fonts/conf.d/10-scale-bitmap-fonts.conf", line 5: unknown element "its:translateRule"<br />
...<br />
}}<br />
Download the latest version of nwjs from [https://nwjs.io/ here] and extract it's contents into your CrossCode directory, overwriting the files.<br />
<br />
Be sure to rename {{ic|nw}} to {{ic|CrossCode}} after.<br />
<br />
This solution was documented to work with CrossCode 1.2 and nwjs 0.41.2 and is based on [https://steamcommunity.com/app/368340/discussions/1/1727575977598417554/ this steam post]<br />
<br />
=== Deus Ex: Mankind Divided ===<br />
<br />
Follow [[#OpenSSL 1.0 setup]].<br />
<br />
Requires {{Pkg|libidn11}} & {{Pkg|librtmp0}}.<br />
<br />
Also if you use Bumblebee set your [[launch option]]s to:<br />
<br />
LD_PRELOAD="$LD_PRELOAD:libpthread.so.0:libGL.so.1" __GL_THREADED_OPTIMIZATIONS=1 optirun %command%<br />
<br />
=== The Clockwork Man ===<br />
<br />
Requires {{pkg|lib32-libidn}} (pulled in by {{pkg|steam-native-runtime}}).<br />
<br />
=== Company of Heroes 2 ===<br />
<br />
Make sure you have {{AUR|lib32-gconf}} installed.<br />
<br />
==== Missing libpcre.so.3 and libidn.so.11 ====<br />
<br />
Like with [[#Alien Isolation]] you need to symlink {{ic|/usr/lib/libpcre.so}} to {{ic|''GAME''/lib/''arch''/libpcre.so.3}}, as well as {{ic|/usr/lib/libidn.so}} to {{ic|''GAME''/lib/''arch''/libidn.so.11}}, otherwise the game will fail to start.<br />
<br />
=== Cossacks 3 ===<br />
<br />
==== No sound ====<br />
<br />
Use the steam-runtime, e.g. set the [https://support.steampowered.com/kb_article.php?ref=1040-JWMT-2947 launch options] to:<br />
<br />
~/.steam/root/ubuntu12_32/steam-runtime/run.sh %command%<br />
<br />
==== Flashing screen with primus ====<br />
<br />
Set {{ic|1=PRIMUS_SYNC=2}}in the launch options.<br />
<br />
=== Counter-Strike: Source (CS:S) ===<br />
<br />
==== Invisible symbols, special characters and cyrillic letters ====<br />
Check [[#Squares or invisible symbols, special characters and cyrillic letters in Source-based games]]<br />
<br />
=== Counter-Strike: Global Offensive (CS:GO) ===<br />
<br />
==== Game starts on the wrong screen ====<br />
<br />
[https://github.com/ValveSoftware/csgo-osx-linux/issues/60 csgo-osx-linux issue #60]<br />
<br />
If it happens, go into fullscreen windowed or windowed mode and drag the window to the correct monitor. Then go back into fullscreen, the game should now be on the correct monitor.<br />
<br />
==== Cannot reach bottom of the screen on menus ====<br />
<br />
[https://github.com/ValveSoftware/csgo-osx-linux/issues/594 csgo-osx-linux issue #594]<br />
<br />
If you have a secondary monitor you might have a part of your lower screen you cannot reach in menus.<br />
If on Gnome you can try to open the overview (Super key) and drag the game to the other monitor and back.<br />
<br />
If you are not on Gnome or dragging the window back and forth did not work you can try to [[install]] {{pkg|wmctrl}} and run this command, where X and Y is the offset of the window and H and W is the size.<br />
wmctrl -r "Counter-Strike: Global Offensive - OpenGL" -e 0,X,Y,H,W<br />
<br />
'''Example''': SecondaryMonitor: on the left 2560x1600, GamingMonitor: on the right 2560x1440).<br />
wmctrl -r "Counter-Strike: Global Offensive - OpenGL" -e 0,2560,0,1600,1200<br />
Here X and Y is 0,2560 to move the window to the monitor on the right and H and W 1600,1200 is set to match the in-game resolution.<br />
<br />
==== Sound is played slightly delayed ====<br />
<br />
[https://github.com/ValveSoftware/csgo-osx-linux/issues/45 csgo-osx-linux issue #45]<br />
<br />
See [[PulseAudio/Troubleshooting#Laggy sound]] for a possible solution.<br />
<br />
==== Mouse not working in-game ====<br />
<br />
If your mouse works in the main menu but not in-game, run the game with {{ic|1=SDL_VIDEO_X11_DGAMOUSE=0}}.<br />
[https://bbs.archlinux.org/viewtopic.php?id=184905]<br />
<br />
==== Brightness slider not working ====<br />
<br />
[[Install]] {{pkg|xorg-xrandr}} and run {{ic|xrandr}} to find out the name of your connected display output.<br />
<br />
Edit {{ic|''GAME''/csgo.sh}} and add the following lines (adapt ''output_name''):<br />
<br />
'''# gamma correction'''<br />
'''xrandr --output ''output_name'' --gamma 1.6:1.6:1.6 # play with values if required'''<br />
STATUS=42<br />
while [$STATUS -eq 42]; do<br />
...<br />
done<br />
'''# restore gamma'''<br />
'''xrandr --output ''output_name'' --gamma 1:1:1'''<br />
exit $STATUS<br />
<br />
==== Microphone not working ====<br />
<br />
[https://github.com/ValveSoftware/csgo-osx-linux/issues/573#issuecomment-174016722 csgo-osx-linux issue #573]<br />
<br />
CS:GO uses the default PulseAudio sound device ignoring what is configured in Steam settings.<br />
<br />
First find out the source name of your microphone (it should start with {{ic|alsa_input.}}):<br />
$ pacmd list-sources<br />
<br />
Then set the default device (change the name accordingly):<br />
$ pacmd set-default-source ''device_name''<br />
<br />
Also lower the microphone level to 60% otherwise you will get some nasty background noise and you will be difficult to understand (change the name accordingly):<br />
$ pacmd set-source-volume ''device_name'' 0x6000<br />
<br />
==== Mouse is unrensponsive or moves slowly ====<br />
<br />
Set launch options to:<br />
vblank_mode=0 %command%<br />
<br />
Works with almost any other game.<br />
<br />
==== Game crashes on startup with game controller plugged in ====<br />
<br />
[https://github.com/ValveSoftware/csgo-osx-linux/issues/1757 csgo-osx-linux issue #1757]<br />
<br />
The solution is to add {{ic|-nojoy}} to the launch options.<br />
<br />
=== Creeper World 3: Arc Eternal ===<br />
<br />
==== Game does not start ====<br />
Search for Player.log<br />
(might be in ~/.config/unity3d/Knuckle Cracker LLC/Creeper World 3/ )<br />
<br />
If it says somewhere in Player.log<br />
"FMOD failed to get number of drivers ... An error occured that wasn't supposed to. Contact support."<br />
Unity is probably having problem with some pulse audio libraries. <br />
<br />
Fix that worked for me:<br />
Remove or rename all instances of libpulse-simple* files.<br />
<br />
Places to look for them:<br />
/usr/lib<br />
/usr/lib32<br />
~/.steam/steam/ubuntu12_32/steam-runtime/i386/usr/lib/i386-linux-gnu/<br />
~/.steam/steam/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/<br />
<br />
=== Crusader Kings II ===<br />
<br />
==== No audio ====<br />
<br />
SDL uses [[PulseAudio]] by default, so to use it with [[ALSA]] you need to set:<br />
<br />
{{hc|~/.pam_environment|2=SDL_AUDIODRIVER=alsa}}<br />
<br />
==== Oddly sized starting window ====<br />
<br />
You can make full screen mode the default by setting {{ic|1=fullscreen=yes}} in {{ic|~/.paradoxinteractive/Crusader Kings II/settings.txt}}.<br />
<br />
==== DLCs not detected ====<br />
<br />
If the DLC tab in the launcher is not selectable, rename the {{ic|DLC}} directory in the game directory to {{ic|dlc}}.<br />
<br />
==== Game takes ages to start ====<br />
<br />
If you are using a nvidia graphics card, make sure you have enabled the [[NVIDIA#DRM kernel mode setting|DRM kernel mode setting]].<br />
<br />
==== Game doesn't start at all ====<br />
<br />
If the game stopped launching after Patch 3.3 (when the game became 64-bit only), install {{Pkg|intel-tbb}}.<br />
<br />
=== Crypt of the NecroDancer ===<br />
<br />
==== Crashes after splash screen ====<br />
<br />
The following error occurs if launching Steam from the terminal.<br />
<br />
FMOD ERROR: UpdateFMOD SystemUpdate: This command failed because System::init or System::setDriver was not called.<br />
<br />
This error is solved by installing {{pkg|pulseaudio-alsa}}.<br />
<br />
=== The Curious Expedition ===<br />
<br />
==== Game stuck on loading screen ====<br />
<br />
The Electron shipped with this game is too old for Arch Linux.<br />
<br />
Install {{pkg|electron}} and run the game with {{ic|electron resources/app.asar}}.<br />
<br />
=== Death Road To Canada ===<br />
<br />
==== No music ====<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
=== Dirt ===<br />
<br />
Follow [[#OpenSSL 1.0 setup]].<br />
<br />
=== Dirt Rally ===<br />
<br />
Prepend {{ic|lib/x86_64}} to your {{ic|LD_LIBRARY_PATH}}, otherwise the game will fail to start.<br />
<br />
{{Note|The order of the paths is important. {{ic|$LD_LIBRARY_PATH}} must be the last entry or it won't work.}}<br />
<br />
=== Divinity: Original Sin - Enhanced Edition ===<br />
<br />
==== Game does not start when using Bumblebee optirun or primusrun ====<br />
<br />
Edit {{ic|''GAME''/runner.sh}} to use primusrun:<br />
LD_LIBRARY_PATH="." primusrun ./EoCApp<br />
<br />
==== Game does not work with mesa ====<br />
<br />
It is a known bug and they have no intention of fixing it, see [https://bugs.freedesktop.org/show_bug.cgi?id=93551 the bug].<br />
<br />
Workaround[https://www.gamingonlinux.com/articles/divinity-original-sin-may-soon-work-with-mesa-drivers.8867/comment_id=81524] (see [https://bugs.freedesktop.org/show_bug.cgi?id=93551#c46 step by step guide])<br />
<br />
Get the following file:<br />
https://bugs.freedesktop.org/attachment.cgi?id=125302<br />
and rename it to {{ic|divos-hack.c}}<br />
<br />
Then execute <br />
$ gcc -s -O2 -shared -fPIC -o divos-hack.{so,c} -ldl<br />
<br />
Copy the {{ic|divos-hack.so}} to the ''game'' folder.<br />
<br />
For GOG version, go to the said game folder and run Divinity with the following command<br />
$ allow_glsl_extension_directive_midshader=true LD_PRELOAD="divos-hack.so" ./runner.sh<br />
<br />
For ''steam'', open a console, change to the divinity directory with <br />
$ cd ~/.steam/steam/steamapps/common/Divinity Original Sin Enhanced Edition<br />
<br />
Launch steam and got o the preferences of the game, and open the "Set Launch Options" dialogue. There, put the following<br />
allow_glsl_extension_directive_midshader=true LD_PRELOAD="divos-hack.so:$LD_PRELOAD" %command%<br />
<br />
Then just start the game.<br />
<br />
=== Doki Doki Literature Club ===<br />
<br />
Linux version is shipped with the Windows version, but can only be installed with Steam Play.<br />
<br />
Native version can be started with this launch option: {{ic|./DDLC.sh # %command%}}<br />
<br />
=== Dota 2 ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|libudev0}}<br />
* {{pkg|libpng12}}<br />
<br />
==== In-game font is unreadable ====<br />
<br />
Run the game with {{ic|1=MESA_GL_VERSION_OVERRIDE=2.1}}.<br />
<br />
==== Error with libpangoft2 ====<br />
<br />
# [[Install]] the {{pkg|pango}} package.<br />
# Remove {{ic|libpango-1.0.so}} and {{ic|libpangoft2-1.0.so}} in {{ic|''GAME''/game/bin/linuxsteamrt64}}.<br />
# If you are using Bumblebee add {{ic|1=LD_PRELOAD="libpthread.so.0 libGL.so.1" __GL_THREADED_OPTIMIZATIONS=1 optiru}} to your [[launch option]]s.<br />
<br />
==== The game does not start ====<br />
<br />
If you run the game from the terminal and, although no error is shown, try disabling: ''Steam > Settings > In-Game > Enable Steam Community In-Game''.<br />
<br />
Apparently the game [[#The Book of Unwritten Tales]] has the same problem. It also describes a workaround that is untested in Dota 2.<br />
<br />
==== Game runs on the wrong screen ====<br />
<br />
: [https://github.com/ValveSoftware/Dota-2/issues/11 GitHub Dota 2 issue #11]<br />
<br />
==== Game does not start with libxcb-dri3 error message ====<br />
<br />
After a recent Mesa update, Dota 2 stopped working. The error message is:<br />
<br />
SDL_GL_LoadLibrary(NULL) failed: Failed loading libGL.so.1: /usr/lib32/libxcb-dri3.so.0: undefined symbol: xcb_send_fd<br />
<br />
==== Game has no audio ====<br />
<br />
This might happen because Dota 2 is trying to output through ALSA, which has already been taken over by PulseAudio. Try installing {{pkg|pulseaudio-alsa}} and setting in-game audio output to 'Default'.<br />
<br />
==== Steam overlay ====<br />
<br />
Steam distributes a copy of libxcb which is incompatible with the latest xorg libxcb. See [https://github.com/ValveSoftware/steam-for-linux/issues/3199], [https://github.com/ValveSoftware/steam-for-linux/issues/3093].<br />
<br />
==== Chinese tips and player names not shown ====<br />
<br />
The Chinese characters in tips and player names are displayed as block characters.<br />
<br />
The problem is caused by the font packages: {{pkg|ttf-dejavu}}, {{pkg|ttf-liberation}} and {{aur|ttf-ms-fonts}}.<br />
<br />
: [https://github.com/ValveSoftware/Dota-2/issues/1688 GitHub Steam issue #1688]<br />
<br />
==== Chinese input method problem ====<br />
<br />
Dota2 is compatible with [[IBus]] .<br />
<br />
=== Devil Daggers ===<br />
<br />
Refer to [[#Missing libcurl.so.4 or version CURL_OPENSSL_3 not found]].<br />
<br />
=== Drox Operative ===<br />
<br />
If the game fails to start with "Couldn't find Database/database.dbl!", manually extract the assets. assets003.zip will overwrite some files from the previous files.<br />
<br />
$ cd "~/.steam/root/steamapps/common/Drox Operative/Assets"<br />
$ unzip assets00[123].zip<br />
<br />
=== Dungeon Souls ===<br />
<br />
For AMD cards this game crashes on launch, unless you start it like this:<br />
<br />
R600_DEBUG=mono %command%<br />
<br />
=== Dying Light ===<br />
<br />
==== Game crashes on startup ====<br />
<br />
The game runs with the Steam setting "Force the use of a specific Steam Play compatibility tool" > "Steam Linux Runtime"<br />
<br />
=== Dynamite Jack ===<br />
<br />
Requires {{Pkg|lib32-sdl}}.<br />
<br />
==== Sound Issues ====<br />
<br />
When running on 64-bit Arch Linux, there may be "pops and hisses" when running Dynamite Jack. This could be caused by not having {{ic|1=STEAM_RUNTIME=0}} set. (However, even with {{ic|1=STEAM_RUNTIME=0}} set, the game may still sometimes start with this issue. Exiting and restarting the game seems to make the problem go away.)<br />
<br />
==== Game does not start ====<br />
<br />
If running steam with the {{ic|1=STEAM_RUNTIME=0}}, Dynamite Jack may have a problem starting. Check the steam error messages for this message:<br />
<br />
/home/$USER/.steam/root/steamapps/common/Dynamite Jack/bin/main: error while loading shared libraries: libSDL-1.2.so.0: cannot open shared object file: No such file or directory<br />
<br />
Install {{pkg|lib32-sdl}} from [[multilib]] and Dynamite Jack should start up.<br />
<br />
=== Empire Total War ===<br />
<br />
==== Weird unreadable fonts ====<br />
<br />
Open {{ic|~/.local/share/feral-interactive/Empire/preferences}}, then find {{ic|UsePBOSurfaces}} and change it from 1 to 0.<br />
<br />
=== Euro Truck Simulator 2 ===<br />
<br />
==== Shows only a black screen ====<br />
<br />
Select safe mode when the game starts up.<br />
<br />
=== Firewatch ===<br />
<br />
If Firewatch starts but doesn't show anything try running Steam with<br />
<br />
`STEAM_RUNTIME_PREFER_HOST_LIBRARIES=0 steam`<br />
<br />
=== Football Manager 2014 ===<br />
<br />
This game will not run when installed on an [[XFS]] or reiserfs filesystem. Workaround is to install on an ext4 filesystem.<br />
<br />
=== FORCED ===<br />
<br />
Requires {{pkg|lib32-glu}}.<br />
<br />
This game has 32-bit and 64-bit binaries. For some reason, Steam will launch the 32-bit binary even on 64-bit Arch Linux.<br />
When manually launching the 64-bit binary, the game starts, but cannot connect to Steam account, so you cannot play.<br />
So install 32-bits dependencies, and launch the game from Steam.<br />
<br />
=== For the King ===<br />
<br />
For steam-native --<br />
<br />
Starts with black page. Requires to be told to use the libSDL2 shipping with Steam<br />
<br />
Add to Steam launch options for game. <br />
<br />
LD_PRELOAD=~/.local/share/Steam/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/libSDL2-2.0.so.0 %command%<br />
<br />
Note however, that this disables the Steam overlay as a side effect.<br />
<br />
For steam-runtime --<br />
<br />
It works out of the box.<br />
<br />
For the full experience, run FTK via steam-runtime instead of steam-native.<br />
<br />
=== FTL: Faster than Light ===<br />
<br />
==== Compatibility ====<br />
<br />
After installation, FTL may fail to run due to a 'Text file busy' error (characterised in Steam by your portrait border going green then blue again). The easiest way to mend this is to just reboot your system. Upon logging back in FTL should run.<br />
<br />
The Steam overlay in FTL does not function as it is not a 3D accelerated game. Because of this the desktop notifications will be visible. If playing in fullscreen, therefore, these notifications in some systems may steal focus and revert you back to windowed mode with no way of going back to fullscreen without relaunching. The binaries for FTL on Steam have no DRM and it is possible to run the game ''without'' Steam running, so in some cases that may be optimum - just ensure that you launch FTL via the launcher script in {{ic|''GAME''/data/}} rather than the FTL binary in the $arch directory.<br />
<br />
==== Problems with open-source video driver ====<br />
<br />
FTL may fail to run if you are using an opensource driver for your video card. There are two solutions: install a proprietary video driver or delete (rename if you are unsure) the library "libstdc++.so.6" inside {{ic|''GAME''/data/amd64/lib}}. This is if you are using a 64bit system. In case you are using a 32bit system you have to remove (rename) the same library located into {{ic|''GAME''/data/x86/lib}}.<br />
<br />
==== Artifacts when launching, Problems with openGL ====<br />
<br />
Using the open source drivers, ATI for radeon cards, the game can display artifacts on screen. Run the game with {{ic|1=MESA_GL_VERSION_OVERRIDE=3.0 %command%}}<br />
<br />
=== Game Dev Tycoon ===<br />
<br />
==== Game does not start ====<br />
<br />
You might get an error about missing {{ic|libudev.so.0}}.<br />
<br />
Run the game with {{ic|1=LD_PRELOAD=/usr/lib/libudev.so.1}}.<br />
<br />
=== Garry's Mod ===<br />
<br />
==== Game does not start ====<br />
<br />
When an error about a missing {{ic|client.so}} appears, try the following:<br />
<br />
$ cd ~/.steam/root/steamapps/common/GarrysMod/bin/<br />
$ ln -s libawesomium-1-7.so.0 libawesomium-1-7.so.2<br />
$ ln -s ../garrysmod/bin/client.so ./<br />
<br />
If the error mentions a missing library for {{ic|libgconf-2.so.4}}, install {{AUR|lib32-gconf}}.<br />
<br />
==== Opening some menus causes the game to crash ====<br />
<br />
Most menus work fine, but ones with checkboxes (LAN multiplayer, mounted games list) do not work at all. This is a bug in the menu code.<br />
<br />
If you prefer the default menu style and do not mind a hacky solution: [https://github.com/Facepunch/garrysmod-issues/issues/86#issuecomment-30935491 Simon311] has written code with instructions to fix it.<br />
<br />
If you do not care for the default menu style and want a more stable but feature-incomplete solution, Facepunch developer [https://github.com/robotboy655/gmod-lua-menu robotboy655] has written a new menu.<br />
<br />
==== Game crashes after attempting to join server ====<br />
<br />
While in the process of joining a server, downloading resources, etc, the game seems to hang and after a while, perhaps during the "sending client info" portion the game crashes, usually without any error messages. Error does not give much information, however, the process for Garry's mod is killed.<br />
<br />
This issue arises more often when joining servers with many addons like DarkRP servers specifically.<br />
<br />
The problem seems to correlate with a weak GPU and the game is timing out from the server, so if the GPU is the problem, lowering the graphics settings to the minimum should fix the problem.<br />
<br />
The problem seems to be related to RAM usage, once you hit around 2GB of RAM used, the game will crash. Servers with many addons have much more RAM usage, and lowering graphics settings to the minimum lowers RAM usage and mitigates crashes.<br />
<br />
Using the experimental x86-64 branch may help mitigate this issue, however keep in mind that some addons may return errors while using this branch.<br />
<br />
=== Gods will be watching ===<br />
<br />
Follow [[#OpenSSL 1.0 setup]].<br />
<br />
=== GRID Autosport ===<br />
<br />
Follow [[#OpenSSL 1.0 setup]].<br />
<br />
==== Black screen when trying to play ====<br />
<br />
Run the game with {{ic|1=LC_ALL=C}}.<br />
<br />
=== Hack 'n' Slash ===<br />
<br />
==== Crashes when trying to load a game ====<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
=== Hacker Evolution ===<br />
<br />
Requires {{Pkg|lib32-sdl2_mixer}}.<br />
<br />
=== Half-Life 2 and episodes ===<br />
<br />
==== Cyrillic fonts problem ====<br />
<br />
This problem can be solved by deleting "Helvetica" font.<br />
<br />
=== Hammerwatch ===<br />
<br />
==== The game does not start via Steam ====<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
==== No sound ====<br />
<br />
Hammerwatch opens with a popup: "Sound Error" -- "Could not initialize OpenAL, no sounds will be played. Try updating your OpenAL drivers."<br />
<br />
OpenAL, which Hammerwatch uses, defaults to PulseAudio. To change that, add the following line to {{ic|/etc/openal/alsoft.conf}}:<br />
<br />
drivers=alsa,pulse<br />
<br />
This way, Hammerwatch will use ALSA. This solution was found [https://stackoverflow.com/questions/9547396/what-does-al-lib-pulseaudio-c612-context-did-not-connect-access-denied-me here].<br />
<br />
=== Harvest: Massive Encounter ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|lib32-sfml}}<br />
* {{Pkg|lib32-libjpeg6-turbo}}<br />
* {{Pkg|lib32-nvidia-cg-toolkit}}<br />
* {{pkg|lib32-gtk2}}<br />
* {{pkg|lib32-libvorbis}}<br />
* {{pkg|lib32-openal}}<br />
<br />
==== Compatibility ====<br />
<br />
If the game refuses to launch and throws you into a library installer loop, run the {{ic|Harvest}} executable instead of the {{ic|run_harvest}} script.<br />
<br />
=== Hatoful Boyfriend ===<br />
<br />
==== Japanese text invisible ====<br />
<br />
Install {{pkg|wqy-microhei}} and {{pkg|wqy-microhei-lite}}.<br />
<br />
=== HEARTBEAT ===<br />
<br />
==== If FontConfig Errors on Start ====<br />
<br />
Follow the same process described in [[#CrossCode]].<br />
<br />
=== HuniePop ===<br />
<br />
==== Game crashes upon launch ====<br />
<br />
Install {{pkg|lsb-release}}.<br />
<br />
=== Hyper Light Drifter ===<br />
<br />
==== The controller does not work ====<br />
<br />
[[Install]] {{pkg|lib32-sdl2}} and run the game with {{ic|1=LD_PRELOAD=libSDL2.so}}.<br />
<br />
See the following Steam Community discussions:<br />
<br />
* [https://steamcommunity.com/app/257850/discussions/1/365163686036494421 Controller Issues]<br />
* [https://steamcommunity.com/app/257850/discussions/1/365163686045397160/ Common Bugs + Known Issues]<br />
<br />
It is suggested to run the ''next_update'' branch to get new fixes,<br />
there however currently is a libcurl segfault keeping it from starting without special workarounds.<br />
<br />
==== Missing libcurl.so.4 or version CURL_OPENSSL_3 not found ====<br />
<br />
[[Install]] {{pkg|lib32-libcurl-compat}} and run the game with {{ic|1=LD_PRELOAD=libcurl.so.3}}.<br />
<br />
=== Imperator: Rome ===<br />
<br />
Paradox Launcher freezes or crashes after start.<br />
Set your launch options to: <br />
LD_PRELOAD=/usr/lib/libc.so.6 %command%<br />
<br />
=== The Impossible Game ===<br />
<br />
Dependencies:<br />
<br />
* {{pkg|lib32-sdl2}}<br />
* {{pkg|lib32-sdl2_image}}<br />
<br />
=== The Inner World ===<br />
<br />
Requires {{AUR|java-commons-codec}} for sound support.<br />
<br />
==== Bringing up the inventory or main menu ====<br />
<br />
Hold the tab key.<br />
<br />
===== Cutscenes =====<br />
<br />
The game has cutscenes. It starts directly with a cutscene before you start the actual game in the backyard. To see these cutscenes you need to use Oracle's [[Java]] instead of the OpenJDK.<br />
<br />
Furthermore you need the package {{aur|ffmpeg-compat-55}}.<br />
<br />
There seem to be problems with the Steam overlay. Try to run the game directly with {{ic|''GAME''/TIW_start.sh}}.<br />
<br />
Note that cutscenes open in a new window. So pay attention to that and switch to the new window to enjoy the movies.<br />
<br />
See the [http://steamcommunity.com/app/251430/discussions/0/611701360817206606/#c611701360827509770 Steam Forums] for details.<br />
<br />
=== Insurgency ===<br />
====Game does not start ====<br />
Set the following launch option<br />
LD_PRELOAD='/usr/$LIB/libstdc++.so.6:/usr/$LIB/libgcc_s.so.1:/usr/$LIB/libxcb.so.1:/usr/$LIB/libgpg-error.so' %command%<br />
<br />
=== Interloper ===<br />
<br />
Requires {{pkg|alsa-lib}}.<br />
<br />
==== Game does not start ====<br />
<br />
The game can sometimes segfault due to an incompatibility with the Steam Runtime's {{ic|libasound.so.2}}.<br />
<br />
=== Invisible Apartment ===<br />
<br />
Requires {{pkg|qt5-multimedia}}.<br />
<br />
==== Game does not start ====<br />
<br />
If the game does not run when you launch it via Steam, try to directly run {{ic|./ia1}} in the game directory.<br />
<br />
=== Joe Danger 2: The Movie ===<br />
<br />
Requires {{pkg|lib32-libpulse}}.<br />
<br />
==== Compatibility ====<br />
<br />
Game only worked after obtaining from the [https://www.humblebundle.com/ Humble Bundle] directly and {{pkg|lib32-libpulse}} was installed.<br />
<br />
=== Kerbal Space Program ===<br />
<br />
See [[Kerbal Space Program]].<br />
<br />
=== Killing Floor ===<br />
<br />
==== Cannot change screen resolution ====<br />
<br />
If trying to modify the resolution in-game crashes your desktop environment, edit {{ic|~/.killingfloor/System/KillingFloor.ini}}:<br />
<br />
[WinDrv.WindowsClient]<br />
WindowedViewportX=''width''<br />
WindowedViewportY=''height''<br />
FullscreenViewportX=''width''<br />
FullscreenViewportY=''height''<br />
MenuViewportX=''width''<br />
MenuViewportY=''height''<br />
<br />
[SDLDrv.SDLClient]<br />
WindowedViewportX=''width''<br />
WindowedViewportY=''height''<br />
FullscreenViewportX=''width''<br />
FullscreenViewportY=''height''<br />
MenuViewportX=''width''<br />
MenuViewportY=''height''<br />
<br />
==== Windowed mode ====<br />
<br />
Uncheck fullscreen in the options menu, and press {{ic|Ctrl+g}} to stop mouse capturing.<br />
<br />
==== Stuttering sound ====<br />
<br />
KillingFloor comes with its own OpenAL library {{ic|''GAME''/System/openal.so}}.<br />
<br />
Back it up, [[install]] {{pkg|openal}} or {{pkg|lib32-openal}} (if using a 64bit system).<br />
<br />
Then symlink the installed system library ({{ic|/usr/lib32/libopenal.so.1}} or {{ic|/usr/lib/libopenal.so.1}}) to {{ic|openal.so}}.<br />
<br />
=== Left for Dead 2 ===<br />
<br />
==== Missing Chinese font ====<br />
<br />
L4D2 Requires {{Pkg|wqy-zenhei}}. Or add the following lines to {{ic|~/.config/fontconfig/fonts.conf}}<br />
<br />
<match target="pattern"><br />
<test qual="any" name="family"><br />
<string>WenQuanYi Zen Hei</string><br />
</test><br />
<edit name="family" mode="assign" binding="same"><br />
<string>Source Han Sans CN</string><br />
</edit><br />
</match><br />
<br />
=== Lethal League ===<br />
<br />
Requires {{Pkg|lib32-glew1.10}}.<br />
<br />
=== Life is Strange ===<br />
<br />
Requires {{Pkg|sdl2_image}} {{Pkg|librtmp0}} {{Pkg|libidn11}} {{AUR|gconf}}.<br />
<br />
=== Little Racers STREET ===<br />
<br />
Install {{Pkg|sdl2_mixer}}.<br />
<br />
Move/backup {{ic|''GAME''/lib64/libSDL2_mixer-2.0.so.0}}.<br />
<br />
Symlink {{ic|/usr/lib/libSDL2_mixer-2.0.so.0}} to {{ic|''GAME''/lib64/libSDL2_mixer-2.0.so.0}}.<br />
<br />
=== The Long Dark ===<br />
<br />
==== Game does not start ====<br />
<br />
The 64-bit version fails to start. Either use the 32-bit version {{ic|tld.x86}} in the game directory or start the 64-bit version like so:<br />
<br />
LD_PRELOAD=~/.steam/root/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/libSDL2-2.0.so.0 ./tld.x86_64<br />
<br />
==== Game starts, but some overlay text is missing and cutscenes shows black screen ====<br />
<br />
In addition to the command above, add the following to the Steam launch command:<br />
<br />
-screen-fullscreen 0 -screen-width WIDTH_PIXELS -screen-height HEIGHT_PIXELS<br />
<br />
For example, if you have a screen resolution of 1280x720 and are launching the x64 version from the terminal (within the directory which contains the binaries), the full command would be:<br />
<br />
LD_PRELOAD=~/.steam/root/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/libSDL2-2.0.so.0 ./tld.x86_64 -screen-fullscreen 0 -screen-width 1280 -screen-height 720<br />
<br />
and from Steam, the complete game [[launch option]]s would be:<br />
<br />
LD_PRELOAD=~/.steam/root/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/libSDL2-2.0.so.0 %command% -screen-fullscreen 0 -screen-width 1280 -screen-height 720<br />
<br />
==== Cutscenes are still black ====<br />
<br />
Turn off Vertical Sync in the Display options, and/or set POST FX to Low in the Quality options, and/or turn global Quality options down a notch.<br />
<br />
==== Cursor disappears ====<br />
<br />
Go to Options > Controls, and set mouse locking to unlocked.<br />
<br />
The options is visible only if you're navigating using your (invisible) mouse. It will not show up when navigating with a controller.<br />
One solution is to go to Options -> Controls with a controller before switching to the mouse and trying to blindly it the setting.<br />
<br />
=== Grand Theft Auto V ===<br />
<br />
==== Game crashes in Online ====<br />
<br />
If you experience crashes in GTA Online (e.g. when creating a new character), set these launch options:<br />
<br />
PROTON_NO_ESYNC=1 WINEDLLOVERRIDES=winedbg.exe=d %command%<br />
<br />
=== Graphical Issues using a NVIDIA GPU ===<br />
<br />
Try launch options: -force-glcore42 -force-clamped<br />
<br />
=== Magicka 2 ===<br />
<br />
==== Indefinitely stuck at start ====<br />
<br />
The game does not start if the output of the command "ip -s link" is longer than 4096 characters. That is because, in the function bitsquid::network_info(char*), where they query the networking information, they do not handle that case correctly.<br />
See [https://i.imgur.com/AOTLoTY.png this picture] for reference.<br />
It was reported to upstream (Pieces Interactive) but Magicka 2 does not seem to be maintained anymore.<br />
<br />
A dirty fix is to wrap your ip binary, as such:<br />
<br />
{{bc|<br />
#!/bin/bash<br />
<nowiki>if [[ $@ == "-s link" ]]; then</nowiki><br />
echo "<paste a smaller subset of the normal output>"<br />
else<br />
/path/to/your/real/ip "$@"<br />
fi<br />
}}<br />
<br />
=== Mark of the Ninja ===<br />
<br />
==== Bad sound ====<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
=== Metro: Last Light ===<br />
<br />
The game does not allow you to change its resolution on a multi-monitor setup on GNOME with the AMD Catalyst drivers. A temporary workaround is to disable the side monitors.<br />
Jason over at [http://unencumberedbyfacts.com/2013/11/20/multiple-monitor-gaming-on-linux/ unencumbered by facts] managed to get it working with his multi-monitor setup using a single display server, he however is using Nvidia.<br />
<br />
=== Metro: 2033 Redux ===<br />
<br />
==== No sound ====<br />
<br />
Install {{Pkg|pulseaudio-alsa}}<br />
<br />
==== No image ====<br />
<br />
Try setting {{ic|r_fullscreen off}} in {{ic|~/.local/share/Steam/steamapps/common/Metro 2033 Redux/user.cfg}}.<br />
<br />
=== Middle-earth: Shadow of Mordor ===<br />
<br />
==== Floating heads ====<br />
<br />
Run the game with {{ic|1=__GL_ShaderPortabilityWarnings=0}}.<br />
<br />
=== Mount & Blade: Warband ===<br />
<br />
==== Segmentation fault (core dumped) with wayland ====<br />
<br />
Use [[Xorg]] instead.<br />
<br />
==== DLC Chooser ====<br />
<br />
Requires {{aur|lib32-nas}}.<br />
<br />
==== Crash on startup ====<br />
<br />
Set launch options to: <br />
LD_LIBRARY_PATH="." %command%<br />
<br />
=== Move or Die ===<br />
<br />
==== No Sound ====<br />
<br />
Install {{pkg|lib32-pulse}}{{Broken package link|package not found}}.<br />
<br />
=== Multiwinia ===<br />
<br />
Requires {{pkg|lib32-openal}}.<br />
<br />
==== Crash on startup ====<br />
<br />
If Multiwinia crashes on startup on X64 systems, force launching the 32-bit executable by replacing {{ic|''GAME''/run_steam.sh}} with the following script:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
./multiwinia.bin.x86<br />
}}<br />
<br />
See [https://steamcommunity.com/app/1530/discussions/0/864969481950542663/#c558746995160431396].<br />
<br />
=== Natural Selection 2 ===<br />
<br />
{{Pkg|sndio}} is required, furthermore, you must also execute<br />
$ ln -s /usr/lib/libsndio.so x64/libsndio.so.6.1<br />
within the root of the NS2 directory.<br />
This is because NS2 uses an older outdated version of sndio, but it is still compatible with the new version, thankfully.<br />
<br />
For a more minimal solution, one can attempt to set the audio driver used through the environment variable {{ic|SDL_AUDIODRIVER}}. For example, {{ic|1=SDL_AUDIODRIVER=sndio}} or {{ic|1=SDL_AUDIODRIVER=alsa}}.<br />
<br />
The environment variable {{ic|SDL_VIDEODRIVER}} must not be set to {{ic|wayland}}.<br />
Try setting {{ic|SDL_VIDEODRIVER}} to {{ic|x11}} if it still does not work.<br />
<br />
=== No Man's Sky ===<br />
<br />
==== Black screen at start ====<br />
<br />
Edit {{ic|~/Steam/SteamApps/common/No Man's Sky/Binaries/SETTINGS/TKGRAPHICSSETTINGS.MXML}} and set {{ic|FullScreen}} to {{ic|false}} and {{ic|Borderless}} to {{ic|true}}.<br />
<br />
==== White screen at start ====<br />
<br />
If you get a white screen, it may seem like the game has froze, but it has not. Hold down {{ic|e}} to continue.<br />
<br />
=== Nuclear Throne ===<br />
<br />
==== Missing libcurl.so.4 or version CURL_OPENSSL_3 not found ====<br />
<br />
[[Install]] {{pkg|lib32-libcurl-compat}} and run the game with {{ic|1=LD_PRELOAD=libcurl.so.3}}.<br />
<br />
=== OneShot ===<br />
<br />
==== Game fails to start ====<br />
<br />
This problem occurs because the game use outdated libraries. Go to the game directory and remove libdrm.so.2, libGLdispatch.so.0, libstdc++.so.6 and librt.so.1. Those files usually have an equivalent already installed on the system.<br />
<br />
==== File _______ won't run ====<br />
The executable _______ may fail when run from the Documents folder. It also exists in the game directory and will run from there.<br />
<br />
=== Oxygen Not Included ===<br />
<br />
==== World generation hangs ====<br />
<br />
This problem occurs with locales that use comas instead of dots to separate decimals.<br />
<br />
Set launch options in steam to {{ic|1=LANG=C %command%}}.[http://steamcommunity.com/app/457140/discussions/3/1488866180617243731/#c1488866813753688864]<br />
<br />
=== Penumbra: Overture ===<br />
<br />
Dependencies:<br />
<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libvorbis}}<br />
* {{pkg|lib32-libxft}}<br />
* {{pkg|lib32-openal}}<br />
* {{pkg|lib32-sdl_image}}<br />
* {{pkg|lib32-sdl_ttf}}<br />
<br />
==== Windowed mode ====<br />
<br />
There is no in-game option to change to the windowed mode, you will have to edit {{ic|~/.frictionalgames/Penumbra/Overture/settings.cfg}} to activate it.<br />
<br />
Find {{ic|FullScreen&#61;"true"}} and change it to {{ic|FullScreen&#61;"false"}}, after this the game should start in windowed mode.<br />
<br />
=== Portal 2 ===<br />
<br />
==== Game does not start ====<br />
<br />
Several OpenGL-related errors (such as {{ic|PROBLEM: You appear to have OpenGL 1.4.0, but we need at least 2.0.0!}} or {{ic|libGL error: driver pointer missing}}) are caused by Portal&nbsp;2 bundling an old libstdc++ file. This error is especially common with open source Radeon drivers ({{ic|radeonsi}}).<br />
<br />
A problem with libstdc can be fixed by running the game with {{ic|1=LD_PRELOAD='/usr/$LIB/libstdc++.so.6'}}.<br />
<br />
==== Resolution too low ====<br />
<br />
When the game starts with a resolution so low that you cannot reach the game settings,<br />
run the game in windowed mode using the {{ic|-windowed}} flag.<br />
<br />
==== Missing non Latin font ====<br />
<br />
The phenomenon is no menu in Portal. Portal and Portal2 use Helvetica, add the following lines to {{ic|~/.config/fontconfig/fonts.conf}}:<br />
<br />
<match target="pattern"><br />
<test qual="any" name="family"><br />
<string>Helvetica</string><br />
</test><br />
<edit name="family" mode="assign" binding="same"><br />
<string>Source Han Sans CN</string><br />
</edit><br />
</match><br />
<br />
You can replace "Source Han Sans CN" by your favoriate and existing font.<br />
<br />
=== Prison Architect ===<br />
<br />
==== ALSA error when using PulseAudio ====<br />
<br />
The error:<br />
<br />
{{ic|ALSA lib pcm_dmix.c:1018:(snd_pcm_dmix_open) unable to open slave}}<br />
<br />
was resolved by installing:<br />
<br />
* {{pkg|pulseaudio-alsa}}<br />
* {{pkg|lib32-libpulse}}<br />
<br />
per [[PulseAudio#ALSA]].<br />
<br />
<br />
==== Game only starting in safe mode ====<br />
<br />
If the game does not start, but steam thinks it is running, probably the Paradox launcher has problems running properly.<br><br />
If this is the case, you'll find some processes running in background:<br />
<br />
<code> ps -ef|grep paradoxlauncher </code><br />
<br />
Kill them all, then modify the game startup options as follows:<br />
<br />
<code> LD_PRELOAD=/usr/lib64/libc.so %command% </code><br />
<br />
Eventually, if the above option hasn't worked, an option to skip it:<br />
<br />
<code>./PrisonArchitect %command% </code><br />
<br />
Note: even if we're using another executable to start the game, %command% has to be added at the end of the command to trick Steam.<br />
<br />
=== Project Zomboid ===<br />
<br />
Requires {{pkg|jre7-openjdk}}.<br />
<br />
==== No sound ====<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
In the game, go to the options and set all audio to the proper volume.<br />
<br />
=== Pyre ===<br />
<br />
==== Game does not start ====<br />
<br />
Remove {{ic|''GAME''/lib64/libSDL2-2.0.so.0}}.<br />
<br />
If this doesn't work, downgrade sdl2.<br />
<br />
$ pacman -U https://archive.archlinux.org/packages/s/sdl2/sdl2-2.0.6-2-x86_64.pkg.tar.xz<br />
<br />
Then add sdl2 to IgnorePkg in {{ic|/etc/pacman.conf}}.<br />
<br />
{{ic|1=IgnorePkg = sdl2}}<br />
<br />
=== Redshirt ===<br />
<br />
Requires {{pkg|lib32-libpulse}} if you use PulseAudio.<br />
<br />
=== Revenge of the Titans ===<br />
<br />
Requires {{pkg|libxtst}} and {{pkg|lib32-libxtst}}.<br />
<br />
=== Rise of the Tomb Raider ===<br />
<br />
Run in an X session.<br />
<br />
=== Risk of Rain ===<br />
<br />
Requires {{pkg|lib32-libcurl-compat}}.<br />
Refer to [[#Missing libcurl.so.4 or version CURL_OPENSSL_3 not found]].<br />
<br />
=== Rock Boshers DX: Directors Cut ===<br />
<br />
Requires {{Pkg|lib32-libcaca}}.<br />
<br />
<br />
=== Saints Row: The Third ===<br />
<br />
==== Impossible to save custom display settings ====<br />
<br />
Although game settings menu allows to choose custom display settings, the game may have problems saving them.<br />
<br />
In such case, adjust these settings manually in the game's {{ic|display.ini}} file at:<br />
<br />
"${HOME}/.local/share/Steam/steamapps/common/Saints Row the Third/display.ini"<br />
<br />
The comments in this file explain well all the settings and acceptable values.<br />
<br />
==== Incorrect screen resolution in game ====<br />
<br />
This can occur when game is launched in a multi-head environment, with some monitors rotated, etc., so the game detects available screen resolutions incorrectly.<br />
<br />
In such case, adjust {{ic|1=ResolutionWidth}} and {{ic|1=ResolutionHeight}} options in the {{ic|display.ini}} file. Also, one must set option {{ic|1=VerifyResolution = false}}.<br />
<br />
<br />
=== Saints Row IV ===<br />
<br />
==== Game fails to launch after update to new Nvidia drivers ====<br />
<br />
{{Accuracy|General settings not specific to this game}}<br />
<br />
Run the game with {{ic|/usr/lib32/libGLX_nvidia.so}} appended to the {{ic|LD_PRELOAD}}.<br />
<br />
==== Game causes GPU lockup with mesa drivers ====<br />
<br />
Saints Rows IV can cause a GPU lockup when trying to play on certain AMD<br />
hardware using open source drivers: [https://bugs.freedesktop.org/show_bug.cgi?id=93475 Bug 93475].<br />
<br />
A workaround is to run the game with {{ic|1=R600_DEBUG=nosb}}.<br />
<br />
=== Serious Sam 3: BFE ===<br />
<br />
==== No audio ====<br />
<br />
Try running:<br />
<br />
# mkdir -p /usr/lib/i386-linux-gnu/alsa-lib/<br />
# ln -s /usr/lib32/alsa-lib/libasound_module_pcm_pulse.so /usr/lib/i386-linux-gnu/alsa-lib/<br />
<br />
If that does not work, try tweaking {{ic|~/.alsoftrc}} as proposed by the [http://steamcommunity.com/app/221410/discussions/3/846940248238406974/ Steam community] (Serious Sam 3: BFE uses OpenAL to output sound). If you are not using Pulse Audio, you may want to write the following configuration:<br />
<br />
{{hc|~/.alsoftrc|<nowiki><br />
[general]<br />
drivers = alsa<br />
[alsa]<br />
device = default<br />
capture = default<br />
mmap = true<br />
</nowiki>}}<br />
<br />
=== Slay the Spire ===<br />
<br />
If the game does not start or crashes at startup, install {{pkg|xorg-xrandr}}.<br />
<br />
If the game does not move sink input, you can edit the following file to allow sink moves:<br />
<br />
{{hc|~/.alsoftrc|<nowiki><br />
[pulse]<br />
allow-moves=yes<br />
</nowiki>}}<br />
<br />
=== Songbringer ===<br />
<br />
==== Launch error with Wayland ====<br />
<br />
Install {{pkg|glfw-x11}} and run the game with {{ic|1=LD_PRELOAD=/usr/lib/libglfw.so.3}}.<br />
<br />
=== Space Pirates and Zombies ===<br />
<br />
Requires {{pkg|lib32-openal}}.<br />
<br />
==== No audio ====<br />
<br />
Try running:<br />
<br />
# mkdir -p /usr/lib/i386-linux-gnu/alsa-lib/<br />
# ln -s /usr/lib32/alsa-lib/libasound_module_pcm_pulse.so /usr/lib/i386-linux-gnu/alsa-lib/<br />
<br />
If that does not work, try tweaking {{ic|~/.alsoftrc}} as proposed by the Steam community (Serious Sam 3: BFE uses OpenAL to output sound). If you are not using Pulse Audio, you may want to write the following configuration:<br />
<br />
{{hc|~/.alsoftrc|<nowiki><br />
[general]<br />
drivers = alsa<br />
[alsa]<br />
device = default<br />
capture = default<br />
mmap = true<br />
</nowiki>}}<br />
<br />
=== Spacechem ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|lib32-sdl_mixer}}<br />
* {{pkg|lib32-sdl_image}}<br />
* {{pkg|lib32-sqlite}}<br />
<br />
==== Game crash ====<br />
<br />
The shipped x86 version of Spacechem does not work on x64 with the game's own libSDL* files, and crashes with some strange output.<br />
<br />
To solve this just remove the three files {{ic|libSDL-1.2.so.0}}, {{ic|libSDL_image-1.2.so.0}}, {{ic|libSDL_mixer-1.2.so.0}} from the game directory.<br />
<br />
=== Splice ===<br />
<br />
Requires {{pkg|glu}}.<br />
<br />
=== The Stanley Parable ===<br />
<br />
==== Game won't start ====<br />
<br />
As discussed in the Steam store page, remove {{ic|bin/libstdc++.so.6}} from the game folder.<br />
<br />
=== Shadow Tactics: Blades of the Shogun ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|lib32-libstdc++5}}<br />
* {{pkg|lib32-libxcursor}}<br />
* {{pkg|lib32-libxrandr}}<br />
<br />
=== Stardew Valley ===<br />
<br />
==== Unable to move ====<br />
<br />
When in game, you are stuck in your bed as you cannot move your character. This is a bug with the SDL2 lib bundled with the game.<br />
<br />
Install {{pkg|sdl2}}.<br />
<br />
Modify this config line:<br />
{{hc|~/.steam/steam/steamapps/common/Stardew\ Valley/MonoGame.Framework.dll.config|<nowiki><br />
<dllmap dll="SDL2.dll" os="linux" cpu="x86-64" target="./lib64/libSDL2-2.0.so.0"/><br />
</nowiki>}}<br />
<br />
To this (the period is removed at the beginning of target):<br />
{{hc|~/.steam/steam/steamapps/common/Stardew\ Valley/MonoGame.Framework.dll.config|<nowiki><br />
<dllmap dll="SDL2.dll" os="linux" cpu="x86-64" target="/lib64/libSDL2-2.0.so.0"/><br />
</nowiki>}}<br />
<br />
=== Steel Storm: Burning Retribution ===<br />
<br />
==== Start with black screen ====<br />
<br />
The game by default tries to launch in fullscreen mode with a resolution of 1024x768,<br />
which doesn't work on some devices (for example the Samsung Series9 laptop with Intel hd4000 video).<br />
<br />
Run the game in windowed mode by using the {{ic|-window}} flag. Then change the resolution in-game.<br />
<br />
=== Stellaris ===<br />
<br />
==== No window opening, only sound ====<br />
<br />
Happens with some AMD GPU and mesa combination, set multi_sampling=0 in ~/.local/share/Paradox\ Interactive/Stellaris/settings.txt.<br />
<br />
==== Immediate crash to desktop ====<br />
<br />
It seems that Stellaris requires a 32bit libnss_sss.so.2 to operate. You can confirm if this is your problem by running <br />
# strace ~/.local/share/Steam/steamapps/common/Stellaris/stellaris 2>&1 | grep sss <br />
and seeing if you get output like <br />
# openat(AT_FDCWD, "/usr/lib32/tls/i686/sse2/libnss_sss.so.2", O_RDONLY|O_LARGEFILE|O_CLOEXEC) = -1 ENOENT (No such file or directory)<br />
<br />
If this is indeed your problem, download the libnss-sss package from Ubuntu's repository [https://packages.ubuntu.com/bionic/i386/libnss-sss/download], extract the libnss_sss.so.2 from the downloaded package, and place it at ~/.local/share/Steam/steamapps/common/Stellaris. The game should now load properly.<br />
<br />
=== Stephen's Sausage Roll ===<br />
<br />
==== No sound ====<br />
<br />
If using [[Steam/Troubleshooting#Native runtime|native libraries]]{{Broken section link}} and {{pkg|libpulse}} is installed, Unity may try to use that library for sound and fail.<br />
To test if this is the problem, try removing {{pkg|libpulse}} or renaming the package files that are named {{ic|libpulse-simple*}}. To see which {{pkg|libpulse}} files are relevant, run:<br />
<br />
{{hc|$ pacman -Qql libpulse <nowiki>|</nowiki> grep /usr/lib/libpulse-simple|<br />
/usr/lib/libpulse-simple.so<br />
/usr/lib/libpulse-simple.so.0<br />
/usr/lib/libpulse-simple.so.0.1.0}}<br />
<br />
If renaming any of those files works for you, you can proceed with the following instructions (revert any renaming you just did). Browse to the game's directory:<br />
<br />
$ cd "$HOME/.steam/root/steamapps/common/Stephen's Sausage Roll"<br />
<br />
And create a sub-directory that we can use to hold 0-byte look-alike library files:<br />
<br />
$ mkdir noload/<br />
<br />
Use {{ic|touch}} to create 0-byte versions of the above files that we want the dynamic linker to skip, e.g.:<br />
<br />
$ touch noload/{libpulse-simple.so,libpulse-simple.so.0,libpulse-simple.so.0.1.0}<br />
<br />
{{Note|Only a 0-byte {{ic|libpulse-simple.so.0}} file may be required.}}<br />
<br />
After you have created these 0-byte files, you can now attempt to run the game binary directly, telling the dynamic linker to use our 0-byte files:<br />
<br />
$ LD_LIBRARY_PATH="noload/:$LD_LIBRARY_PATH" ./Sausage.x86_64<br />
<br />
If everything works up to this point, prepend {{ic|noload/}} to your {{ic|LD_LIBRARY_PATH}}.<br />
<br />
Again, this should work because Steam checks for a {{ic|noload/}} directory relative to the game's directory. The dynamic linker should respect the {{ic|$LD_LIBRARY_PATH}} variable and fail to load the necessary {{pkg|libpulse}} files. The game should then fallback to plain ALSA.<br />
<br />
=== Superbrothers: Sword & Sworcery EP ===<br />
<br />
Dependencies:<br />
<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libpulse}} if you use PulseAudio<br />
<br />
The game bundles an outdated version of libstdc++ which prevents the game from starting. [http://steamcommunity.com/app/204060/discussions/0/364039785161291413] The following can be observed when you run Steam and S&S from the terminal:<br />
<br />
libGL error: unable to load driver: i965_dri.so<br />
libGL error: driver pointer missing<br />
libGL error: failed to load driver: i965<br />
libGL error: unable to load driver: i965_dri.so<br />
libGL error: driver pointer missing<br />
libGL error: failed to load driver: i965<br />
libGL error: unable to load driver: swrast_dri.so<br />
libGL error: failed to load driver: swrast<br />
<br />
To solve this problem remove {{ic|''GAME''/lib/libstdc++.so.6*}}. After that the game will use the libstdc++ from Steam.<br />
<br />
=== System Shock 2 ===<br />
<br />
You get these errors when running it with the native client:<br />
<br />
C:\windows\system32\winedevice.exe: symbol lookup error: /usr/lib32/libX11.so.6: undefined symbol: xcb_wait_for_reply64<br />
C:\windows\system32\wineboot.exe: symbol lookup error: /usr/lib32/libX11.so.6: undefined symbol: xcb_wait_for_reply64<br />
<br />
Just delete or rename the libxcb library it got shipped with:<br />
<br />
mv /mnt/olhdd/steam/steamapps/common/SS2/lib/libxcb.so.1{,.old}<br />
mv /mnt/olhdd/steam/steamapps/common/SS2/lib/libxcb.so.1.1.0{,.old}<br />
<br />
==== Game won't launch ====<br />
<br />
If you encounter the game not launching do the following:<br />
<br />
Cut & Paste libsteam_api.so from the "SS2/Bin" folder within the main steam common folder and transfer it to "SS2" main game folder not the sub folder "SS2/bin"<br />
<br />
After Cut & Paste put LD_PRELOAD='/usr/$LIB/libxcb.so.1' %command% into the Launch options <br />
<br />
Once all of these have been implemented the game should work after hitting play on steam.<br />
<br />
==== Resolution fix ====<br />
<br />
You may encounter some resolution problems with this game on steam not working properly in full screen mode. Do the following:<br />
<br />
Open cam.cfg in the SS2 folder you may have to search for it via the search mode while in the game folder:<br />
<br />
Place game_screen_size 1024 768 or game_screen_size 1920 1080 depending on your resolution & put game_full_screen 1 into bottom of the cam.cfg file. <br />
<br />
Then go to cam_ext.cfg and next to the display setting place a simi-colon prefix next to the use_d3d_display option so it should be like this ;use_d3d_display it should then properly not go off-screen and should stay full screen within the active main screen.<br />
<br />
=== Tabletop Simulator ===<br />
<br />
==== CJK characters not showing in game ====<br />
<br />
Install {{pkg|wqy-microhei}} and {{pkg|wqy-microhei-lite}}.<br />
<br />
=== Team Fortress 2 ===<br />
<br />
Requires {{Pkg|lib32-libpng12}}.<br />
<br />
==== HRTF setup ====<br />
<br />
Assuming HRTF (head-related transfer function) has been properly set up in the operating system, HRTF won't be enabled unless you disable the original processing. To do so, use<br />
<br />
dsp_slow_cpu 1<br />
<br />
For best results, also change the following:<br />
<br />
snd_spatialize_roundrobin 1<br />
dsp_enhance_stereo 0<br />
snd_pitchquality 1<br />
<br />
==== Loading screen freeze ====<br />
<br />
If you are a non-English (speaking) user, you have to enable "en_US.UTF-8" in the locale.gen! Generate a new locale after that.<br />
<br />
==== No audio ====<br />
<br />
It happens if there is no PulseAudio in your system.<br />
If you want to use [[ALSA]], you need to launch Steam or the game directly with {{ic|1=SDL_AUDIODRIVER=alsa}}<br />
(From [http://steamcommunity.com/app/221410/discussions/0/882966056462819091/#c882966056470753683 SteamCommunity]).<br />
<br />
If it still does not work, you may also need to set the environment variable AUDIODEV. For instance {{ic|1=AUDIODEV=Live}}. Use {{ic|aplay -l}} to list the available sound cards.<br />
<br />
==== Slow loading textures ====<br />
<br />
If you are using Chris' FPS Configs or any other FPS config, you may have set {{ic|mat_picmip}} to {{ic|2}}. This spawns multiple threads for texture loading, which may cause more jittering and lag on Linux, especially on alternative kernels. Try setting it to {{ic|-1}}, the default.<br />
<br />
==== "Invalid color format" Error at loading screen on integrated Intel Atom/BayTrail HD Graphics ====<br />
<br />
Add the following to the game startup options:<br />
<code> -force_vendor_id 0x10DE -force_device_id 0x1180 </code><br />
<br />
These options deceive the game engine that we're having a Nvidia GPU, not Intel/AMD.<br />
<br />
=== Terraria ===<br />
<br />
See the KNOWN ISSUES & WORKAROUNDS section of the [http://forums.terraria.org/index.php?threads/terraria-1-3-0-8-can-mac-linux-come-out-play.30287/ release announcement].<br />
<br />
==== Input Issues ====<br />
<br />
The symptoms of this problem are: When moving after standing still, your character seems to vary their speed, if wearing running boots they don't activate. When jumping with an item for double jumping sometimes you double jump even if you just jumped once. Going up/down ropes seems slow/choppy.<br />
<br />
The solution is to preload the system SDL2 libraries: {{ic|1=LD_PRELOAD='/usr/$LIB/libSDL2-2.0.so:/usr/lib32/libSDL2-2.0.so' }} For more information: [https://forums.terraria.org/index.php?threads/keyboard-input-bug-involving-linux.56763/page-2#post-1533051 Terraria Forums]<br />
<br />
=== This War of Mine ===<br />
<br />
==== Game does not start ====<br />
<br />
This happens because of an incompatibility with the newer version of {{ic|lib32-curl}}. To fix the problem , set your [[launch option]]s to:<br />
LD_PRELOAD=./libcurl.so.4 %command%<br />
<br />
==== Sound glitches with Steam native ====<br />
<br />
The bundled {{ic|libOpenAL}} might not work correctly, try symlinking {{ic|/usr/lib32/libopenal.so}} to {{ic|''GAME''/libOpenAL.so}}.<br />
<br />
=== Ticket to Ride ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|lib32-gstreamer0.10-base}}<br />
* {{AUR|lib32-pangox-compat}}<br />
<br />
As lib32-gstreamer0.10-base is quite hard to build you can use [[Unofficial_user_repositories#alucryd-multilib|alucryd-multilib]] repo for this package<br />
<br />
=== The Tiny Bang Story ===<br />
<br />
==== Missing libGLEW.so.1.6 ====<br />
<br />
# ln -s /usr/lib32/libGLEW.so.1.10.0 /usr/lib32/libGLEW.so.1.6<br />
<br />
=== Tomb Raider ===<br />
<br />
==== Game immediately closes when running with steam-native ====<br />
<br />
Tomb Raider has a very heavy amount of dependency on the Steam runtime, the easiest solution is to just run it using the runtime.<br />
<br />
==== Steam Controller not working in-game====<br />
<br />
If your Steam Controller is correctly recognized and paired but still not working in-game try the following:<br />
<br />
* In Steam, non Big Screen, go to ''Settings > Account > Beta participation > Change...'' and in the dropdown select box select Steam Beta Update<br />
* Restart Steam<br />
* Go to Big Screen and start Tomb Raider<br />
<br />
Correctly recognized means you can control the desktop mouse and Steam in Big Picture mode and the controller is shown in the Big Picture settings.<br />
<br />
<br />
=== Torchlight 2 ===<br />
<br />
==== Libfreetype/libfontconfig Incompatibility ====<br />
<br />
If you are experiencing issues with launching games such as Torchlight 2 or Civilization IV, it could be due to using a newer libfontconfig than the game currently supports.<br />
<br />
Right click the game in Steam, and set the following as it's launch option:<br />
<br />
LD_PRELOAD=/usr/lib/libfreetype.so.6 %command%<br />
<br />
then attempt launching the game. <br />
<br />
Alternately, re-naming or deleting these 2 files will force it to use your system's libraries:<br />
<br />
Torchlight 2/game/lib/libfreetype.so.6<br />
Torchlight 2/game/lib64/libfreetype.so.6<br />
<br />
==== Locale incompatibility ====<br />
<br />
Some users report that Torchlight 2 does not work if you do not have en_US.UTF8 in your locale. <br />
<br />
Double check you have generated the locale needed in [[Steam#Installation|Steam Installation Requirements]].<br />
<br />
=== Tower Unite ===<br />
<br />
==== Graphical Glitches ====<br />
<br />
This is a known issue, and it occurs because the shaders had not been ported to Linux yet by the developers.<br />
To minimize glitches and make the game playable add {{ic|-opengl4}} to your [[launch option]]s,<br />
set Ocean Quality to "Potato" and Effects Quality to "Low" in the game settings.<br />
<br />
=== Towns / Towns Demo ===<br />
<br />
Requires [[Java]].<br />
<br />
=== Transistor ===<br />
<br />
==== Crash on launch / FMOD binding crash / audio issues ====<br />
<br />
Run the game with:<br />
<br />
LD_PRELOAD='/usr/lib/libstdc++.so.6:/usr/lib/libgcc_s.so.1:/usr/lib/libxcb.so.1:/usr/lib/libasound.so.2'<br />
<br />
Otherwise, run the game via shell and set up proper audio device for FMOD, as discussed in [https://steamcommunity.com/app/237930/discussions/2/620695877176333955/].<br />
<br />
Also, check out this thread [https://steamcommunity.com/app/237930/discussions/2/492378265893557247/].<br />
<br />
=== Transmissions: Element 120 ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|lib32-libgcrypt15}}<br />
* {{pkg|lib32-libpng12}}<br />
<br />
==== Troubleshooting ====<br />
<br />
Make sure you have all libraries installed. Above the standard set required by Steam runtime, the game requires few additional ones. The typical error message that indicates that is<br />
<br />
AppFramework : Unable to load module vguimatsurface.so!<br />
<br />
To find missing dependencies go into the game directory and run:<br />
<br />
LD_LIBRARY_PATH=bin ldd bin/vguimatsurface.so<br />
<br />
Look for entries that say ''not found''.<br />
<br />
=== Transport Fever 2 ===<br />
<br />
==== Game won't launch ====<br />
<br />
Rename or delete the following files in game directory (~/.steam/steam/steamapps/common/Transport Fever 2) as discussed in [https://steamcommunity.com/app/1066780/discussions/0/1740010344363244243/]<br />
<br />
* libstdc++.so.6<br />
* libstdc++.so.6.0.25<br />
<br />
=== Trine 2 ===<br />
<br />
Dependencies:<br />
<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libxxf86vm}}<br />
* {{pkg|lib32-openal}}<br />
* {{pkg|xorg-xwininfo}}<br />
* {{pkg|lib32-libdrm}}<br />
<br />
* {{pkg|lib32-libpng12}}<br />
* {{pkg|lib32-libwrap}}<br />
<br />
==== Fullscreen ====<br />
<br />
Game crashes if started in fullscreen mode, but starts in windowed mode. After start the window can be set to fullscreen (borderless window) if your window manager supports this.<br />
[https://steamcommunity.com/app/35720/discussions/0/1735463620079681092/ steam forum]<br />
==== Colors ====<br />
<br />
If colors are wrong with FOSS drivers (r600g at least), try to run the game in windowed mode, rendering will be corrected. ([https://bugs.freedesktop.org/show_bug.cgi?id=60553 bug report])<br />
<br />
==== Sound ====<br />
<br />
{{Accuracy|General settings not specific to this game}}<br />
<br />
If sound plays choppy, try:<br />
<br />
{{hc|/etc/openal/alsoft.conf|<nowiki><br />
drivers=pulse,alsa<br />
frequency=48000<br />
</nowiki>}}<br />
<br />
==== Resolution ====<br />
<br />
If the game resolution is wrong when using a dual monitor setup and you can't see the whole window edit {{ic|~/.frozenbyte/Trine2/options.txt}} and change the options {{ic|ForceFullscreenWidth}} and {{ic|ForceFullscreenHeight}} to the resolution of your monitor on which you want to play the game.<br />
<br />
==== Crash on start in libX11.so.6.3.0 ====<br />
<br />
gdb may report a crash in XGetICValues(), probably due to a bug in SDL1.3; fortunately SDL2.0 is compatible with trine 2, so just force it and see if it works by modifying the steam launch options (or by script/commandline if using the drm free version).<br />
<br />
{{bc|<nowiki><br />
LD_PRELOAD="/usr/lib32/libSDL2.so" %command%<br />
</nowiki>}}<br />
<br />
=== Tropico 5 ===<br />
<br />
==== Blank screen with sound only on startup ====<br />
<br />
Run the game with {{ic|1=MESA_GL_VERSION_OVERRIDE=4.0 MESA_GLSL_VERSION_OVERRIDE=400}}.<br />
<br />
=== Unity of Command ===<br />
<br />
Requires {{pkg|lib32-pango}}.<br />
<br />
==== Squares ====<br />
<br />
If squares are shown instead of text, try removing {{ic|''GAME''/bin/libpangoft2-1.0.so.0}}.<br />
<br />
==== No audio ====<br />
<br />
If you get this error:<br />
<br />
ALSA lib dlmisc.c:254:(snd1_dlobj_cache_get) Cannot open shared library /usr/lib/i386-linux-gnu/alsa-lib/libasound_module_pcm_pulse.so<br />
<br />
Try running:<br />
<br />
# mkdir -p /usr/lib/i386-linux-gnu/alsa-lib/<br />
# ln -s /usr/lib32/alsa-lib/libasound_module_pcm_pulse.so /usr/lib/i386-linux-gnu/alsa-lib/<br />
<br />
=== Unity3D ===<br />
<br />
Games based on the Unity3D engine, like ''War For The Overworld'' or ''Pixel Piracy'' may need the package {{pkg|lsb-release}} to understand that they run on Linux and work properly.<br />
<br />
==== Locale settings ====<br />
<br />
Games made in C# often have a problem with some locales (e.g. Russian, German) because developers don't specify locale-agnostic number formatting. This can result in some game screens loading only partially, problems with online features or other bugs.<br />
<br />
To work around this, run the game with {{ic|1=LC_ALL=C}}.<br />
<br />
Affected games: ''FORCED, Gone Home, Ichi, Nimble Quest, Syder Arcade''.<br />
<br />
==== Unity 5 sound problems ====<br />
<br />
The sound system in Unity 5 changed and to be able to play games created with it you must most likely install and run [[PulseAudio]].<br />
<br />
Another solution is to disable the Steam runtime: in the launch options for the game, write this: {{ic|1=LD_LIBRARY_PATH="" %command%}}<br />
<br />
Another solution is to prevent Unity from trying to use pulseaudio using {{AUR|pulsenomore}} package from the [[AUR]]. Once it is installed, use the following as launch options :{{ic|/usr/bin/pulsenomore %command%}}<br />
<br />
Affected games: ''Kerbal Space Program, SUPERHOT, ClusterTruck''<br />
<br />
==== Game launching on wrong monitor in fullscreen mode ====<br />
<br />
Unity games that do not support monitor selection will most likely launch the game on a wrong monitor.<br />
<br />
The problem is that Unity games write the default parameter {{ic|1=<pref name="UnitySelectMonitor" type="int">-1</pref>}} to the game config file.<br />
<br />
This will lead to the game launching on a non-primary monitor.<br />
<br />
When changing to value into {{ic|1=<pref name="UnitySelectMonitor" type="int">'''0'''</pref>}} for the according game, the game will start on the correct (primary) monitor.<br />
<br />
A Unity game config file usually resides in {{ic|~/.config/unity3d/''CompanyName''/''ProductName''/prefs}}.<br />
<br />
Affected games: ''Cities: Skylines, Tabletop Simulator, Assault Android Cactus, Wasteland 2, Tyranny, Beat Cop''.<br />
<br />
Be aware that some games do not support setting that parameter, it will simply be ignored. This is the case for ''Pillars of Eternity'', ''Kentucky Route Zero'', ''Sunless Sea''.<br />
<br />
==== Chinese/Japanese/Korean display bug ====<br />
<br />
Install {{pkg|wqy-microhei}} and {{pkg|wqy-microhei-lite}}. Then<br />
<br />
#fc-cache -fv<br />
<br />
==== Game does not respond ====<br />
<br />
Add the following line to your [[launch option]]s :<br />
<br />
SDL_DYNAMIC_API=/usr/lib/libSDL2-2.0.so %command%<br />
<br />
=== Unrest ===<br />
<br />
Requires {{pkg|fluidsynth}}.<br />
<br />
=== Volgarr the Viking ===<br />
<br />
Delete the {{ic|lib}} directory in the game directory to get rid of the libGL errors.<br />
<br />
=== War Thunder ===<br />
<br />
==== No audio ====<br />
<br />
If there is no audio after launching the game, install {{pkg|pulseaudio-alsa}}.<br />
<br />
==== Blank screen ====<br />
<br />
If having a green or blank screen on startup, run the game with {{ic|1=MESA_GL_VERSION_OVERRIDE=4.1COMPAT}}. [https://forum.warthunder.com/index.php?/topic/267809-linux-potential-workaround-for-mesa-drivers-black-screen/] [http://forum.warthunder.com/index.php?search_term=0030709&app=core&module=search&do=search&fromMainBar=1&search_app=forums%3Aforum%3A920&sort_field=&sort_order=&search_in=posts]{{Dead link|2020|04|03|status=404}}<br />
<br />
steam startup WarThunder need set startup options {{ic|<nowiki>XMODIFIERS="" %command%</nowiki>}}<br />
<br />
=== Warhammer 40,000: Dawn of War II ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|alsa-lib}}<br />
* {{Pkg|librtmp0}}<br />
<br />
The start script does not point to the right direction of {{ic|libasound.so.2}}.<br />
<br />
To fix it open {{ic|''GAME''/DawnOfWar2.sh}} and replace the following lines:<br />
<br />
{{bc|<nowiki>HAS_LSB_RELEASE=$(command -v lsb_release)<br />
if [ -n "${HAS_LSB_RELEASE}" ] && [ "$(lsb_release -c | cut -f2)" = "trusty" ]; then<br />
LD_PRELOAD_ADDITIONS="/usr/lib/x86_64-linux-gnu/libasound.so.2:${LD_PRELOAD_ADDITIONS}"<br />
fi </nowiki>}}<br />
<br />
with:<br />
<br />
{{bc|1=LD_PRELOAD_ADDITIONS="/usr/lib64/libasound.so.2:${LD_PRELOAD_ADDITIONS}"}}<br />
<br />
=== Wasteland 2 ===<br />
<br />
If Wasteland 2 immediately exits when you try to launch it there may not be enough system file descriptors available. To increase the descriptor limit edit '''/etc/security/limits.conf''' and add the line:<br />
<br />
<nowiki>* hard nofile 524288</nowiki><br />
<br />
Then reboot for the new limit to take effect, Wasteland 2 should now launch and this setting might also fix other games.<br />
<br />
=== We Were Here ===<br />
<br />
==== Stuck on black screen or logo on launch ====<br />
<br />
Add {{ic|-screen-fullscreen 0}} to launch options. [https://steamcommunity.com/app/582500/discussions/1/1470840994974091613/]<br />
<br />
=== Worms W.M.D ===<br />
<br />
The game includes several workarounds in the {{ic|Run.sh}} script, however these may not work and it is easy to get the game running without this script.<br />
<br />
First, try running the game directly from its game directory using {{ic|Worms W.M.Dx64}}. If you get a "No such file or directory" error about libcurl-gnutls, install {{pkg|libcurl-gnutls}}. If the game crashes after playing the intro movies, add the Steam Runtime dbus libraries to the game's library directory:<br />
<br />
$ ln -s ~/.steam/steam/ubuntu12_32/steam-runtime/amd64/lib/x86_64-linux-gnu/*dbus* ~/.steam/steam/steamapps/common/WormsWMD/lib<br />
<br />
Now the game should run using the default "Play Worms W.M.D" option. See also Steam community discussions [https://steamcommunity.com/app/327030/discussions/2/133257959065155871/] and [https://steamcommunity.com/app/327030/discussions/1/343785380902286766/].<br />
<br />
On some systems there are terrain bugs where holes in terrain are not rendered properly and worms can fall through terrain unexpectedly. These bugs can make the game unplayable in many situations and there is no known fix for them.<br />
<br />
=== Witcher 2: Assassin of Kings ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|lib32-gnutls}}<br />
* {{Pkg|lib32-libcurl-compat}}<br />
* {{Pkg|lib32-libcurl-gnutls}}<br />
* {{Pkg|lib32-sdl2_image}}<br />
* {{Pkg|lib32-sdl2}}<br />
<br />
==== Game does not start ====<br />
The game will not start with SDL set to use wayland. You can have only the game run in x11 by adding the following launch options in steam:<br />
<br />
$ SDL_VIDEODRIVER=x11 %command%<br />
<br />
<br />
If the game does not run, enable error messages:<br />
<br />
$ LIBGL_DEBUG=verbose ./witcher2<br />
<br />
=== Wizardry 6: Bane of the Cosmic Forge ===<br />
<br />
Requires [[DOSBox]].<br />
<br />
To fix the crash at start, open {{ic|''GAME''/dosbox_linux/launch_wizardry6.sh}} and:<br />
<br />
# comment the line {{ic|1=export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./libs}}<br />
# change the beginning of the line starting with {{ic|exec ./dosbox}} to {{ic|exec dosbox}}<br />
<br />
=== World of Goo ===<br />
<br />
==== Changing resolution ====<br />
To change the game resolution edit the ''Graphics display'' section in {{ic|''GAME''/properties/config.txt}}. For example:<br />
<br />
<nowiki><!-- Graphics display --></nowiki><br />
<param name="screen_width" value="1680" /><br />
<param name="screen_height" value="1050" /><br />
<param name="color_depth" value="0" /><br />
<param name="fullscreen" value="true" /><br />
<param name="ui_inset" value="10" /><br />
<br />
=== X3: Terran Conflict ===<br />
<br />
==== Game crashes on startup ==== <br />
<br />
The game may crash on startup because it's linked to libz version 1.2.9, while the latest version of this library in Arch Linux is higher. The following message in the terminals appears in this case:<br />
./X3TC_config: lib/libz.so.1: version 'ZLIB_1.2.9' not found (required by /usr/lib32/libpng16.so.16<br />
<br />
Renaming or removing lib/libz.so.1 may help.<br />
<br />
=== XCOM ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|librtmp0}}<br />
* {{Pkg|sdl2_image}} (required to enable keyboard functionality in-game)<br />
<br />
==== Hangs on startup ====<br />
<br />
If you are running a [[hybrid graphics]] system, try:<br />
<br />
__GL_THREADED_OPTIMIZATIONS=0 primusrun %command%<br />
<br />
==== Graphical glitches on Intel HD ====<br />
<br />
XCOM: Enemy Unknown may not recognize the SDL2 shared libraries shipped with the Steam runtime.<br />
Check if the binary finds all required files and install missing packages if necessary ({{Pkg|sdl2}} and {{Pkg|sdl2_image}}).<br />
<br />
{{bc|ldd binaries/linux/game.x86_64 | grep "not found"}}</div>Iaz3https://wiki.archlinux.org/index.php?title=Desktop_environment&diff=479853Desktop environment2017-06-15T19:07:26Z<p>Iaz3: Fixed the link to List of applications#Taskbars, which had the wrong named anchor.</p>
<hr />
<div>[[Category:Desktop environments]]<br />
[[es:Desktop environment]]<br />
[[fa:Desktop environment]]<br />
[[it:Desktop environment]]<br />
[[ja:デスクトップ環境]]<br />
[[ru:Desktop environment]]<br />
[[sv:Skrivbordsmiljö]]<br />
[[uk:Desktop environment]]<br />
[[zh-hans:Desktop environment]]<br />
{{Related articles start}}<br />
{{Related|Display manager}}<br />
{{Related|Window manager}}<br />
{{Related|Xorg}}<br />
{{Related|Wayland}}<br />
{{Related|Default applications}}<br />
{{Related articles end}}<br />
A [[Wikipedia:Desktop environment|desktop environment]] provides a ''complete'' graphical user interface (GUI) for a system by bundling together a variety of components written using a common widget toolkit and set of libraries.<br />
<br />
== Overview ==<br />
<br />
A desktop environment bundles together a variety of components to provide common graphical user interface elements such as icons, toolbars, wallpapers, and desktop widgets. Additionally, most desktop environments include a set of integrated applications and utilities. Most importantly, desktop environments provide their own [[window manager]], which can however usually be replaced with another compatible one.<br />
<br />
The user is free to configure their GUI environment in any number of ways. Desktop environments simply provide a complete and convenient means of accomplishing this task. Note that users are free to mix-and-match applications from multiple desktop environments. For example, a KDE user may install and run GNOME applications such as the Epiphany web browser, should he/she prefer it over KDE's Konqueror web browser. One drawback of this approach is that many applications provided by desktop environment projects rely heavily upon their DE's respective underlying libraries. As a result, installing applications from a range of desktop environments will require installation of a larger number of dependencies. Users seeking to conserve disk space often avoid such mixed environments, or chose alternatives which do depend on only few external libraries.<br />
<br />
Furthermore, DE-provided applications tend to integrate better with their native environments. Superficially, mixing environments with different widget toolkits will result in visual discrepancies (that is, interfaces will use different icons and widget styles). In terms of usability, mixed environments may not behave similarly (e.g. single-clicking versus double-clicking icons; drag-and-drop functionality) potentially causing confusion or unexpected behavior.<br />
<br />
Prior to installing a desktop environment, a functional X server installation is required. See [[Xorg]] for detailed information. Some desktop environments may also support [[Wayland]] as an alternative to X, but most of these are still experimental.<br />
<br />
== List of desktop environments ==<br />
<br />
=== Officially supported ===<br />
<br />
* {{App|[[Budgie Desktop|Budgie]]|Budgie is a desktop environment designed with the modern user in mind, it focuses on simplicity and elegance. |https://budgie-desktop.org/|{{Pkg|budgie-desktop}}}}<br />
<br />
* {{App|[[Cinnamon]]|Cinnamon strives to provide a traditional user experience. Cinnamon is a fork of GNOME 3.|http://cinnamon.linuxmint.com/|{{Pkg|cinnamon}}}}<br />
<br />
* {{App|[[Deepin]]|Deepin desktop interface and apps feature an intuitive and elegant design. Moving around, sharing and searching etc. has become simply a joyful experience. |https://www.deepin.org/|{{grp|deepin}}}}<br />
<br />
* {{App|[[Enlightenment]]|The Enlightenment desktop shell provides an efficient window manager based on the Enlightenment Foundation Libraries along with other essential desktop components like a file manager, desktop icons and widgets. It supports themes, while still being capable of performing on older hardware or embedded devices.|https://www.enlightenment.org/|{{Pkg|enlightenment}}}}<br />
<br />
* {{App|[[GNOME]]|The GNOME desktop environment is an attractive and intuitive desktop with both a modern (''GNOME'') and a classic (''GNOME Classic'') session.|https://www.gnome.org/gnome-3/|{{grp|gnome}}}}<br />
<br />
* {{App|[[GNOME Flashback]]| GNOME Flashback is a shell for GNOME 3 which was initially called GNOME fallback mode. The desktop layout and the underlying technology is similar to GNOME 2.|https://wiki.gnome.org/Projects/GnomeFlashback|{{Pkg|gnome-flashback}}}}<br />
<br />
* {{App|[[KDE Plasma]]|The KDE Plasma desktop environment is a familiar working environment. Plasma offers all the tools required for a modern desktop computing experience so you can be productive right from the start.|https://www.kde.org/plasma-desktop|{{grp|plasma}}}}<br />
<br />
* {{App|[[LXDE]]|The Lightweight X11 Desktop Environment is a fast and energy-saving desktop environment. It comes with a modern interface, multi-language support, standard keyboard short cuts and additional features like tabbed file browsing. Fundamentally designed to be lightweight, LXDE strives to be less CPU and RAM intensive than other environments.|http://lxde.org/|GTK+ 2: {{grp|lxde}}, GTK+ 3: {{grp|lxde-gtk3}}}}<br />
<br />
* {{App|[[LXQt]]|LXQt is the Qt port and the upcoming version of LXDE, the Lightweight Desktop Environment. It is the product of the merge between the LXDE-Qt and the Razor-qt projects: A lightweight, modular, blazing-fast and user-friendly desktop environment.|http://lxqt.org/|{{grp|lxqt}}}}<br />
<br />
* {{App|[[MATE]]|Mate provides an intuitive and attractive desktop to Linux users using traditional metaphors. MATE started as a fork of GNOME 2, but now uses GTK+ 3.|http://www.mate-desktop.org/|{{grp|mate}}}}<br />
<br />
* {{App|[[Sugar]]|The Sugar Learning Platform is a computer environment composed of Activities designed to help children from 5 to 12 years of age learn together through rich-media expression. Sugar is the core component of a worldwide effort to provide every child with the opportunity for a quality education — it is currently used by nearly one-million children worldwide speaking 25 languages in over 40 countries. Sugar provides the means to help people lead fulfilling lives through access to a quality education that is currently missed by so many.|https://sugarlabs.org/|{{Pkg|sugar}} + {{Grp|sugar-fructose}}}}<br />
<br />
* {{App|[[Xfce]]|Xfce embodies the traditional UNIX philosophy of modularity and re-usability. It consists of a number of components that provide the full functionality one can expect of a modern desktop environment, while remaining relatively light. They are packaged separately and you can pick among the available packages to create the optimal personal working environment.|http://www.xfce.org/|{{grp|xfce4}}}}<br />
<br />
=== Unofficially supported ===<br />
<br />
* {{App|[[CDE]]|The Common Desktop Environment (CDE) is a desktop environment for Unix and OpenVMS, based on the Motif widget toolkit. It was part of the UNIX98 Workstation Product Standard, and was long the "classic" Unix desktop associated with commercial Unix workstations. Highly experimental.|https://sourceforge.net/projects/cdesktopenv/|{{AUR|cdesktopenv}}}}<br />
<br />
* {{App|[[Equinox Desktop Environment|EDE]]|The "Equinox Desktop Environment" is a DE designed to be simple, extremely light-weight and fast.|http://equinox-project.org/|{{AUR|ede}}}}<br />
<br />
* {{App|[[Liri]]|Liri is a desktop environment with modern design and features. Liri is the merge between [http://hawaiios.org/ Hawaii], [http://papyros.io/ Papyros] and the [https://github.com/liri-project Liri Project]. Highly experimental.|https://liri.io/|{{AUR|liri-shell-git}}}}<br />
<br />
* {{App|[[Lumina]]|Lumina is a lightweight desktop environment written in Qt 5 for FreeBSD that uses Fluxbox for window management.|https://lumina-desktop.org/|{{AUR|lumina-desktop}}}}<br />
<br />
* {{App|[[Moksha]]|Fork of Enlightenment currently used as default desktop environment in Ubuntu-based Bodhi Linux.|http://www.bodhilinux.com/moksha-desktop/|{{AUR|moksha}}}}<br />
<br />
* {{App|[[Pantheon]]|Pantheon is the default desktop environment originally created for the elementary OS distribution. It is written from scratch using Vala and the GTK3 toolkit. With regards to usability and appearance, the desktop has some similarities with GNOME Shell and macOS.|https://elementary.io/|{{AUR|pantheon-session-bzr}}}}<br />
<br />
* {{App|theShell|theShell is a desktop environment that tries to be as transparent as possible. It uses Qt 5 as its widget toolkit and KWin as its window manager. It also incorporates a personal assistant.|https://vicr123.github.io/theshell|{{AUR|theshell}}}}<br />
<br />
* {{App|[[Trinity]]|The Trinity Desktop Environment (TDE) project is a computer desktop environment for Unix-like operating systems with a primary goal of retaining the overall KDE 3.5 computing style.|http://www.trinitydesktop.org/|See [[Trinity]]}}<br />
<br />
== Comparison of desktop environments ==<br />
<br />
''This section attempts to draw a comparison between popular desktop environments. Note that first-hand experience is the only effective way to truly evaluate whether a desktop environment best suits your needs.''<br />
<br />
See also [[Wikipedia:Comparison of X Window System desktop environments]].<br />
<br />
{| class="wikitable"<br />
|+ Overview of desktop environments <!-- PLEASE DO NOT OVER-CLUTTER THIS TABLE! --><br />
! Desktop environment !! Widget toolkit !! Window manager !! Taskbar !! Terminal emulator !! File manager !! Calculator !! Text editor !! Image viewer !! Media player !! Web browser !! Display manager<br />
|-<br />
| [[Budgie Desktop|Budgie]] || [[GTK+]] 3<br>{{pkg|gtk3}} || budgie-wm<br>{{Pkg|budgie-desktop}} || budgie-panel<br>{{Pkg|budgie-desktop}} || [[Wikipedia:GNOME Terminal|GNOME Terminal]]<br>{{pkg|gnome-terminal}} || [[GNOME Files]]<br>{{pkg|nautilus}} || [[Wikipedia:GNOME Calculator|GNOME Calculator]]<br>{{pkg|gnome-calculator}} || [[gedit]]<br>{{pkg|gedit}} || [[Wikipedia:Eye of GNOME|Eye of GNOME]]<br>{{pkg|eog}} || [[Wikipedia:GNOME Videos|GNOME Videos]]<br>{{pkg|totem}} || [[Epiphany]]<br>{{pkg|epiphany}} || [[GDM]]<br>{{pkg|gdm}}<br />
|-<br />
| [[Cinnamon]] || [[GTK+]] 3<br>{{pkg|gtk3}} || Muffin<br>{{pkg|muffin}} || Cinnamon<br>{{pkg|cinnamon}} || [[Wikipedia:GNOME Terminal|GNOME&nbsp;Terminal]]<br>{{pkg|gnome-terminal}} || [[Nemo]]<br>{{pkg|nemo}} || [[Wikipedia:GNOME Calculator|GNOME Calculator]]<br>{{pkg|gnome-calculator}} || [[gedit]]<br>{{pkg|gedit}} || [[Wikipedia:Eye of GNOME|Eye&nbsp;of&nbsp;GNOME]]<br>{{pkg|eog}} || [[Wikipedia:GNOME Videos|GNOME Videos]]<br>{{pkg|totem}} || [[Firefox]]<br>{{pkg|firefox}} || [[LightDM]] GTK+ Greeter<br>{{pkg|lightdm-gtk-greeter}}<br />
|-<br />
| [[Deepin]] || [[GTK+]] 2/3, [[Qt]]&nbsp;5<br>{{pkg|gtk2}} {{pkg|gtk3}} {{pkg|qt5-base}} || Deepin Window Manager<br>{{pkg|deepin-wm}} || Deepin Dock<br>{{pkg|deepin-dock}} || Deepin Terminal<br>{{pkg|deepin-terminal}} || Deepin File Manager<br>{{pkg|deepin-file-manager}} || [[Wikipedia:GNOME Calculator|GNOME Calculator]]<br>{{pkg|gnome-calculator}} || [[gedit]]<br>{{pkg|gedit}} || Deepin Image Viewer<br>{{pkg|deepin-image-viewer}} || Deepin Movie<br>{{pkg|deepin-movie}} || [[Chromium]]<br>{{pkg|chromium}} || [[LightDM]] Deepin Greeter<br>{{pkg|deepin-session-ui}}<br />
|-<br />
| [[Equinox Desktop Environment|EDE]] || [http://www.fltk.org/ FLTK]<br>{{pkg|fltk}} || [[PekWM]]<br>{{AUR|ede}} || EDE Panel<br>{{AUR|ede}} || [[Xterm|XTerm]]<br>{{Pkg|xterm}} || Fluff<br>{{AUR|fluff}} || Calculator<br>{{AUR|ede}} || Editor<br>{{AUR|fltk-editor}} || Image Viewer<br>{{AUR|ede}} || flmusic<br>{{AUR|flmusic}} || [[Dillo]]<br>{{Pkg|dillo}} || [[XDM]]<br>{{Pkg|xorg-xdm}}<br />
|-<br />
| [[Enlightenment]] || [https://www.enlightenment.org/about-efl EFL]<br>{{Pkg|efl}} || [https://www.enlightenment.org/about-enlightenment Enlightenment]<br>{{pkg|enlightenment}} || [https://www.enlightenment.org/about-enlightenment Enlightenment]<br>{{pkg|enlightenment}} || [https://www.enlightenment.org/about-terminology Terminology]<br>{{pkg|terminology}} || [https://www.enlightenment.org/about-enlightenment Enlightenment]<br>{{pkg|enlightenment}} || Equate<br>{{AUR|equate-git}} || Ecrire<br>{{AUR|ecrire-git}} || [https://www.enlightenment.org/about-ephoto Ephoto]<br>{{AUR|ephoto-git}} || [https://www.enlightenment.org/about-rage Rage]<br>{{AUR|rage}} || [[Wikipedia:Links (web browser)|Links]]<br>{{Pkg|links}} || [[XDM]]<br>{{Pkg|xorg-xdm}}<br />
|-<br />
| [[GNOME]] || [[GTK+]] 3<br>{{pkg|gtk3}} || [[Wikipedia:Mutter (window manager)|Mutter]]<br>{{pkg|mutter}} || [[Wikipedia:GNOME Shell|GNOME Shell]]<br>{{pkg|gnome-shell}} || [[Wikipedia:GNOME Terminal|GNOME Terminal]]<br>{{pkg|gnome-terminal}} || [[GNOME Files]]<br>{{pkg|nautilus}} || [[Wikipedia:GNOME Calculator|GNOME Calculator]]<br>{{pkg|gnome-calculator}} || [[gedit]]<br>{{pkg|gedit}} || [[Wikipedia:Eye of GNOME|Eye of GNOME]]<br>{{pkg|eog}} || [[Wikipedia:GNOME Videos|GNOME Videos]]<br>{{pkg|totem}} || [[Epiphany]]<br>{{pkg|epiphany}} || [[GDM]]<br>{{pkg|gdm}}<br />
|-<br />
| [[GNOME Flashback]] || [[GTK+]] 3<br>{{pkg|gtk3}} || [[Wikipedia:Metacity|Metacity]]<br>{{pkg|metacity}} || [[Wikipedia:GNOME Panel|GNOME Panel]]<br>{{pkg|gnome-panel}} || [[Wikipedia:GNOME Terminal|GNOME Terminal]]<br>{{pkg|gnome-terminal}} || [[GNOME Files]]<br>{{pkg|nautilus}} || [[Wikipedia:GNOME Calculator|GNOME Calculator]]<br>{{pkg|gnome-calculator}} || [[gedit]]<br>{{pkg|gedit}} || [[Wikipedia:Eye of GNOME|Eye of GNOME]]<br>{{pkg|eog}} || [[Wikipedia:GNOME Videos|GNOME Videos]]<br>{{pkg|totem}} || [[Epiphany]]<br>{{pkg|epiphany}} || [[GDM]]<br>{{pkg|gdm}}<br />
|-<br />
| [[KDE Plasma]] || [[Qt]] 5<br>{{pkg|qt5-base}} || [[Wikipedia:KWin|KWin]]<br>{{pkg|kwin}} || [[Wikipedia:KDE Plasma 5#Desktop|Plasma&nbsp;Desktop]]<br>{{pkg|plasma-desktop}} || [http://konsole.kde.org/ Konsole]<br>{{pkg|konsole}} || [http://dolphin.kde.org/ Dolphin]<br>{{pkg|dolphin}} || [http://www.kde.org/applications/utilities/kcalc/ KCalc]<br>{{pkg|kcalc}} || [http://kate-editor.org/ KWrite/Kate]<br>{{pkg|kwrite}} {{pkg|kate}} || [http://gwenview.sourceforge.net/ Gwenview]<br>{{pkg|gwenview}} || [http://www.kde.org/applications/multimedia/dragonplayer/ Dragon&nbsp;Player]<br>{{pkg|dragon}} || [http://www.konqueror.org/ Konqueror]<br>{{pkg|konqueror}} || [[SDDM]]<br>{{Pkg|sddm}}<br />
|-<br />
| [[Liri]] || [[Qt]] 5<br>{{Pkg|qt5-base}} || Green Island<br>{{AUR|greenisland}} || Liri Shell<br>{{AUR|liri-shell-git}} || Liri Terminal<br>{{AUR|liri-terminal-git}} || Liri Files<br>{{AUR|liri-files-git}} || Liri Calculator<br>{{AUR?|liri-calculator-git}} || Liri Text<br>{{AUR?|liri-text-git}} || EyeSight<br>{{AUR|eyesight}} || Liri Player<br>{{AUR|liri-player-git}} || Liri Browser<br>{{AUR|liri-browser-git}} || SDDM<br>{{Pkg|sddm}}<br />
|-<br />
| [[LXDE]] (GTK+ 2) || [[GTK+]] 2<br>{{pkg|gtk2}} || [[Openbox]]<br>{{pkg|openbox}} || [http://wiki.lxde.org/en/LXPanel LXPanel]<br>{{pkg|lxpanel}} || [http://wiki.lxde.org/en/LXTerminal LXTerminal]<br>{{pkg|lxterminal}} || [[PCManFM]]<br>{{pkg|pcmanfm}} || [http://galculator.sourceforge.net/ Galculator]<br>{{Pkg|galculator-gtk2}} || [http://tarot.freeshell.org/leafpad/ Leafpad]<br>{{pkg|leafpad}} || [http://wiki.lxde.org/en/GPicView GPicView]<br>{{pkg|gpicview}} || [http://wiki.lxde.org/en/LXMusic LXMusic]<br>{{pkg|lxmusic}} || [[Midori]]<br>{{pkg|midori}} || [[LXDM]]<br>{{pkg|lxdm}}<br />
|-<br />
| [[LXDE]] (GTK+ 3) || [[GTK+]] 3<br>{{Pkg|gtk3}} || [[Openbox]]<br>{{Pkg|openbox}} || [http://wiki.lxde.org/en/LXPanel LXPanel]<br>{{Pkg|lxpanel-gtk3}} || [http://wiki.lxde.org/en/LXTerminal LXTerminal]<br>{{Pkg|lxterminal-gtk3}} || [[PCManFM]]<br>{{Pkg|pcmanfm-gtk3}} || [http://galculator.sourceforge.net/ Galculator]<br>{{Pkg|galculator}} || L3afpad<br>{{Pkg|l3afpad}} || [http://wiki.lxde.org/en/GPicView GPicView]<br>{{Pkg|gpicview-gtk3}} || [http://wiki.lxde.org/en/LXMusic LXMusic]<br>{{Pkg|lxmusic-gtk3}} || [[Midori]]<br>{{pkg|midori}} || [[LXDM]]<br>{{Pkg|lxdm-gtk3}}<br />
|-<br />
| [[LXQt]] || [[Qt]] 5 <br>{{pkg|qt5-base}} || [[Openbox]]<br>{{pkg|openbox}} || LXQt Panel<br>{{pkg|lxqt-panel}} || QTerminal<br>{{Pkg|qterminal}} || PCManFM-Qt<br>{{pkg|pcmanfm-qt}} || [http://speedcrunch.org/ SpeedCrunch]<br>{{Pkg|speedcrunch}} || Notepadqq<br>{{Pkg|notepadqq}} || LxImage-Qt<br>{{Pkg|lximage-qt}} || SMPlayer<br>{{Pkg|smplayer}} || QupZilla<br>{{Pkg|qupzilla}} || SDDM<br>{{Pkg|sddm}}<br />
|-<br />
| [[MATE]] || [[GTK+]] 3<br>{{pkg|gtk3}} || Marco<br>{{pkg|marco}} || MATE Panel<br>{{pkg|mate-panel}} || MATE Terminal<br>{{pkg|mate-terminal}} || Caja<br>{{pkg|caja}} || MATE Calc<br>{{Pkg|mate-calc}} || pluma<br>{{pkg|pluma}} || Eye of MATE<br>{{pkg|eom}} || [http://docs.xfce.org/apps/parole/start Parole]<br>{{pkg|parole}} || [[Midori]]<br>{{pkg|midori}} || [[LightDM]] GTK+ Greeter<br>{{pkg|lightdm-gtk-greeter}}<br />
|-<br />
| [[Pantheon]] || [[GTK+]] 3<br>{{pkg|gtk3}} || [https://launchpad.net/gala Gala]<br>{{AUR|gala-git}} || [https://launchpad.net/plank Plank]/[https://launchpad.net/wingpanel Wingpanel]<br>{{Pkg|plank}} {{AUR|wingpanel}} || [https://launchpad.net/pantheon-terminal Pantheon&nbsp;Terminal]<br>{{Pkg|pantheon-terminal}} || [https://launchpad.net/pantheon-files Pantheon Files]<br>{{Pkg|pantheon-files}} || [https://launchpad.net/pantheon-calculator Pantheon Calculator]<br>{{AUR|pantheon-calculator}} || [https://launchpad.net/scratch Scratch]<br>{{Pkg|scratch-text-editor}} || [https://launchpad.net/pantheon-photos Pantheon Photos]<br>{{pkg|pantheon-photos}} || [https://launchpad.net/audience Audience]<br>{{pkg|audience}} || [[Epiphany]]<br>{{pkg|epiphany}} || [[LightDM]] Pantheon&nbsp;Greeter<br>{{AUR|lightdm-pantheon-greeter}}<br />
|-<br />
| [[Sugar]] || [[GTK+]] 3<br>{{pkg|gtk3}} || [[Wikipedia:Metacity|Metacity]]<br>{{pkg|metacity}} || Sugar<br>{{Pkg|sugar}} || Terminal<br>{{Pkg|sugar-activity-terminal}} || Sugar Journal<br>{{Pkg|sugar}} || Calculate<br>{{Pkg|sugar-activity-calculate}} || Write<br>{{Pkg|sugar-activity-write}} || ImageViewer<br>{{Pkg|sugar-activity-imageviewer}} || Jukebox<br>{{Pkg|sugar-activity-jukebox}} || Browse<br>{{Pkg|sugar-activity-browse}} || [[LightDM]] GTK+ Greeter<br>{{Pkg|lightdm-gtk-greeter}}<br />
|-<br />
| theShell || [[Qt]] 5<br>{{pkg|qt5-base}} || [[Wikipedia:KWin|KWin]]<br>{{pkg|kwin}} || theShell<br>{{AUR|theshell}} || theTerminal<br>{{AUR|theterminal}} || theFile<br>{{AUR|thefile}} || theCalculator<br>{{AUR|thecalculator}} || [http://kate-editor.org/ KWrite/Kate]<br>{{pkg|kwrite}} {{pkg|kate}} || [http://gwenview.sourceforge.net/ Gwenview]<br>{{pkg|gwenview}} || theMedia<br>{{AUR|themedia}} || theWeb<br>{{AUR|theweb}} || [[LightDM]] Contemporary Greeter<br>{{AUR|lightdm-webkit-theme-contemporary}}<br />
|-<br />
| [[Trinity]] || TQt || TWin || Kicker || Konsole || Konqueror || KCalc || Kwrite / Kate || Kuickshow || Kaffeine || Konqueror || TDM<br />
|-<br />
| [[Xfce]] || [[GTK+]] 2/3<br>{{pkg|gtk2}} {{pkg|gtk3}} || [http://docs.xfce.org/xfce/xfwm4/start Xfwm4]<br>{{pkg|xfwm4}} || [http://docs.xfce.org/xfce/xfce4-panel/start Xfce Panel]<br>{{pkg|xfce4-panel}} || [http://www.xfce.org/projects/terminal Terminal]<br>{{pkg|xfce4-terminal}} || [[Thunar]]<br>{{pkg|thunar}} || [http://galculator.sourceforge.net/ Galculator]<br>{{Pkg|galculator}} || Mousepad<br>{{pkg|mousepad}} || [http://goodies.xfce.org/projects/applications/ristretto Ristretto]<br>{{pkg|ristretto}} || [http://docs.xfce.org/apps/parole/start Parole]<br>{{pkg|parole}} || [[Midori]]<br>{{pkg|midori}} || [[LightDM]] GTK+ Greeter<br>{{pkg|lightdm-gtk-greeter}}<br />
|-<br />
|}<br />
<br />
=== Resource use ===<br />
<br />
In terms of system resources, GNOME and KDE are ''expensive'' desktop environments. Not only do complete installations consume more disk space than lightweight alternatives (LXDE, LXQt and Xfce) but also more CPU and memory resources while in use. This is because GNOME and KDE are relatively ''full-featured'': they provide the most complete and well-integrated environments.<br />
<br />
LXDE, LXQt and Xfce, on the other hand, are ''lightweight'' desktop environments. They are designed to work well on older or lower-power hardware and generally consume fewer system resources while in use. This is achieved by cutting back on ''extra'' features (which some would term ''bloat'').<br />
<br />
== Custom environments ==<br />
<br />
Desktop environments represent the simplest means of installing a ''complete'' graphical environment. However, users are free to build and customize their graphical environment in any number of ways if none of the popular desktop environments meet their requirements. Generally, building a custom environment involves selection of a suitable [[window manager]], a [[List of applications#Taskbars|taskbar]] and a number of applications (a minimalist selection usually includes a [[terminal emulator]], [[List of applications#File managers|file manager]], and [[text editor]]).<br />
<br />
Other applications that are usually provided by desktop environments are:<br />
<br />
* Application launcher: [[List of applications#Application launchers]]<br />
* Clipboard manager: [[Clipboard#List of clipboard managers]]<br />
* Desktop compositor: [[Xorg#Composite]]<br />
* Desktop wallpaper setter and desktop icon: [[List of applications#Wallpaper setters]] and [[Openbox#Icon programs]]<br />
* Display manager: [[Display manager#List of display managers]]<br />
* Display power saving settings: [[Display Power Management Signaling]]<br />
* Logout dialogue: [[Oblogout]]<br />
* Mount tool: [[List of applications#Mount tools]]<br />
* Notification daemon: [[Desktop notifications]]<br />
* Polkit authentication agent: [[Polkit#Authentication agents]]<br />
* Screen locker: [[List of applications#Screen lockers]]<br />
* Sound volume manager: [[List of applications#Volume managers]]<br />
<br />
=== Custom window manager ===<br />
<br />
In many desktop environments, it is possible to replace the supplied window manager. See below for instructions specific to your environment.<br />
<br />
;GNOME<br />
<br />
Alternative window managers cannot be used with GNOME Shell however [[GNOME Flashback]] provides sessions for Metacity and [[Compiz]]. Furthermore, it is possible to define your own [[GNOME/Tips and tricks#Custom GNOME sessions|custom GNOME sessions]] which use alternative components.<br />
<br />
;Cinnamon<br />
<br />
Alternative window managers cannot be used with [[Cinnamon]].<br />
<br />
;Other desktop environments<br />
<br />
* KDE - See [[KDE#Using an alternative window manager]].<br />
<br />
* MATE - See [[MATE#Use a different window manager with MATE]].<br />
<br />
* Xfce - See [[Xfce#Default window manager]].<br />
<br />
* LXDE - See [[LXDE#Replace Openbox]].<br />
<br />
* LXQt - See [[LXQt#Replace Openbox]].<br />
<br />
* Budgie - See [[Budgie Desktop#Replace Budgie WM]].<br />
<br />
* theShell - In theShell settings, under the "Danger" category, enter the command to start the window manager in "Window Manager Command"</div>Iaz3