Alpine Linux - User contributions [en]

Alpine Package Keeper

2025-01-20T10:21:50Z

Somercet: added a section on downgrading from edge

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. For a quickstart, refer [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK]. Package management in [[Installation#Diskless_Mode|Diskless]] mode requires additional steps involving [[Alpine_local_backup|Alpine Local Backup Utility ('''lbu''') ]].

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:

{|
| [[#Add a Package|add]]
| Add new packages or upgrade packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| [[#World|fix ]]
| Repair packages or system
|-
| [[#Update Package list|update]]
| Update the index of available packages
|-
| [[#Information on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Cache maintenance|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|-
| [[#apk dot|dot]]
| Create a [https://graphviz.org/ graphviz] graph description for a given package
|-
| [[#apk_policy|policy]]
| Display the repository that updates a given package, plus repositories that also offer the package
|-
| stats
| Display statistics, including number of packages installed and available, number of directories and files, etc.
|-
| manifest
| Display checksums for files contained in a given package
|}

== Packages and Repositories ==

Software packages for Alpine Linux are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata. They have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into three official [[Repositories|'''repositories''']]. Technically, any directory with a collection of *.apk files with a special index file, named {{Path|APKINDEX.tar.gz}} can be considered a repository, albeit a personal repository. [[Repositories#Repository_pinning|Pinned Repositories]] can be used to [[#Holding_a_specific_package_back|holdback]] a specific version of a package.

== World ==

At {{Path|/etc/apk/world}}, apk maintains the world, that is, a list of constraints the package selection needs to fulfill. World describes the desired system state. The commands <code>apk add foo</code> and <code>apk del bar</code> manipulate the desired state by adding foo or bar as a dependency constraint in {{Path|/etc/apk/world}}.

{{Path|/etc/apk/world}} is a plaintext file with one constraint using dependency notation per line. Each line has the format:
<code>name{@tag}{[<>~=]version}</code>

Every constraint listed here must be solvable in order for the system to be considered correct, and no transaction may be committed that is incorrect. If it cannot verify the correctness of the requested change, it will back out adding the constraint before attempting to change what packages are actually installed on the system. Thus apk will never [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

If {{Path|/etc/apk/world}} is edited manually, run <code>apk fix</code> to synchronize the installed packages with the desired system state. Package installation or removal is done as a side effect of modifying this system state.
{{cmd|apk fix}}

== Update Package list ==

Alpine Linux [[Repositories|'''repositories''']] change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. The command downloads the {{Path|APKINDEX.tar.gz}} from each repository and stores it in the local cache, typically {{Path|/var/cache/apk/}}, {{Path|/var/lib/apk/}} or {{Path|/etc/apk/cache/}}.

{{Cmd|apk update}}

Adding the <code>--update-cache</code>, or for short <code>-U</code> switch to another apk command, as in <code>apk --update-cache upgrade</code> or <code>apk -U add ...</code>, the command has the same effect as first running <code>apk update</code> before the other apk command.

It is a good idea to always do an '''update''' right '''before''' doing an '''upgrade or add''' command. That way the command will install the latest available packages from the [[Repositories|'''repositories''']].

== Add a Package ==

Use '''add''' to install packages from a [[Repositories|'''repository''']]. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package.

{{Cmd|apk add openssh
apk add openssh openntp vim}}

Packages from [[Repositories#Repository_pinning|pinned repositories]] can be installed by adding tags to them.
{{cmd| apk add wireguard-go@testing}}.

== Add a local Package ==

To install a locally available apk package, for example if this device has no internet access but you can upload apk packages directly to it, use the '''--allow-untrusted''' flag:

{{cmd|apk add --allow-untrusted /path/to/file.apk}}

Note that multiple packages can be given. When installing a local package, all dependencies should also be specified. For example:

{{cmd|apk add --allow-untrusted /var/tig-2.2-r0.apk /var/git-2.11.1-20.apk}}

== Remove a Package ==

Use '''del''' to remove a package (and dependencies that are no longer needed.)

{{cmd|apk del openssh
apk del openssh openntp vim}}

== Upgrade a Running System ==
To get the latest security upgrades and bugfixes available for the currently installed [[Repositories#Release_Branches|release branch]] of a running system, there are two steps:
* '''update''' the list of available packages
* '''upgrade''' the installed packages:

{{cmd|apk update
apk upgrade
}}

Or, combining the same into one single command:

{{cmd|apk -U upgrade
}}

Here is an example, showing the procedure on a system that has [[#Repository_pinning|repositories pinned]]:
<Pre>
# apk update
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz</nowiki>
v3.6.2-191-gf98d79930f <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/main]</nowiki>
v3.6.2-190-ga5d68c47df <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/community]</nowiki>
v3.6.0-4624-g11f1b9c8ab <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/testing]</nowiki>
OK: 20118 distinct packages available

# apk upgrade
(1/2) Upgrading extra-cmake-modules@testing (5.38.0-r0 -> 5.39.0-r0)
(2/2) Upgrading extra-cmake-modules-doc@testing (5.38.0-r0 -> 5.39.0-r0)
Executing mdocml-apropos-1.14.1-r0.trigger
OK: 2635 MiB in 803 packages
</Pre>
To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them:

{{cmd|apk update
apk upgrade busybox
}}

To enable unattended, automatic upgrades of packages, see the {{pkg|apk-autoupdate}} package. Refer [[Upgrading_Alpine|Upgrading Alpine]] to upgrade Alpine Linux to a newer [[Repositories#Release_Branches|release branch]].

== Upgrading "diskless" and "data" disk mode installs ==
{{Main|Diskless Mode}}

For upgrading [[Diskless Mode|diskless]] and [[Installation#Data Disk|Data disk]] mode installs, Upgrading a running system requires [[Diskless Mode#Upgrading a Running System|few extra steps]].

== Search for Packages ==
The '''search''' command searches the repository Index files for installable packages.

The return format is '''Package'''-'''Version'''. Omit '''Version''' for ''apk add '''Package'''''

Examples:
* To list all packages available, along with their descriptions: {{cmd|apk search -v}}
* To list all packages are part of the ACF system: {{cmd|apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description, use the ''-d'' or ''--description'' option: {{cmd|apk search -v --description 'NTP' }}
* To list all packages that provide the <code>git</code> command: {{cmd|apk search -v 'cmd:git'}}

== Information on Packages ==

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information), or all information displayed with the ''-a'' command.

Example: {{cmd|apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>https://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package (''-d'' or ''--description'')
* The '''webpage''' where the application is hosted (''-w'' or ''--webpage'')
* The '''size''' the package will require once installed (in bytes) (''-s'' or ''--size'')
* What packages are required to use this one ('''depends''') (''-R'' or ''--depends'')
* What packages require this one to be installed ('''required by''') (''-r'' or ''--rdepends'')
* The '''contents''' of the package, that is, which files it installs (''-L'' or ''--contents'')
* Any '''triggers''' this package sets. (''-t'' or ''--triggers'') Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

=== Check file ownership ===

The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|apk info --who-owns /sbin/lbu}}
will display
<pre>
/sbin/lbu is owned by alpine-conf-x.x-rx
</pre>

=== Check Dependencies ===

The '''info''' command specific to check package dependency and reverse dependency is explained below:

The option '''-R''' or '''--depends''' lists the dependencies of the package.
{{Cmd| apk info --depends pipewire}}
<pre>
pipewire-1.0.6-r1 depends on:
/bin/sh
so:libc.musl-x86_64.so.1
so:libpipewire-0.3.so.0
</pre>

The option '''-r''' or '''--rdepends''' lists the reverse dependencies of the package (all other packages which depend on the package).

{{Cmd|apk info --rdepends pipewire}}
<pre>
pipewire-1.0.6-r1 is required by:
xdg-desktop-portal-wlr-0.7.1-r0
pipewire-pulse-1.0.6-r1
</pre>

=== Listing installed packages ===

To list all installed packages, use:

{{Cmd|apk info}}

To list all installed packages in alphabetical order, with a description of each, do:

{{Cmd|apk -vv info|sort}}

The apk tool does not have a subcommand to list manually-installed packages that do not have reverse dependencies. To get this information on a traditional system that is not using [[Alpine local backup|lbu]], try this script. Note that this approach will also list core packages like alpine-base that should not be removed.

<pre>
#!/bin/sh
apk info | grep -ve '-doc$' | sort | while read pkg
do
rdep=`apk info -qr "$pkg"`
[ -z "$rdep" ] && echo $pkg
done
</pre>

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs. Steps to use the dot option is documented below:

Save the output of apk dot option to a dot file.
<pre>
$ apk dot seatd > seatd_dependencies.dot
</pre>
Use Graphviz to convert the <code>dot</code> file into a graphical format such as PNG, PDF, or SVG.
<pre>
$ dot -Tpng seatd_dependencies.dot -o seatd_dependencies.png
</pre>
[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]]

== apk policy ==

To display the repository a package was installed from and will be updated from, plus any [[#Repository_pinning|tagged]] or enabled repositories where it is also offered, if any, for this architecture - its '''policy''':

{{Cmd|apk policy ''package''}}

For example:
<pre>
$ apk policy vlc
vlc policy:
2.2.6-r1:
lib/apk/db/installed
https://dl-3.alpinelinux.org/alpine/v3.7/community
3.0.0_rc2-r1:
@edgecommunity https://dl-3.alpinelinux.org/alpine/edge/community
</pre>

== Local Cache ==

{{:Local_APK_cache}}

== Advanced APK Usage ==

=== Commandline repository options ===

By default, the '''apk''' utility will use the system repositories for all operations. This behavior can be overridden by the following options:

{|
| --repositories-file REPOFILE
| Override the system repositories by specifying a repositories file.
|-
| <nowiki>-X|--repository REPO</nowiki>
| Specify a supplemental repository that will be used in addition to the system repositories. This option can be provided multiple times.
|}

{{cmd|apk add cherokee --update-cache --repository https://dl-cdn.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}

=== Holding a specific package back ===

In certain cases, you may want to upgrade a system, but keep a specific package at a back level. It is possible to add "sticky" or versioned dependencies. For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:
{{cmd|1=apk add asterisk=1.6.0.21-r0}}
or
{{cmd|apk add 'asterisk<1.6.1'}}

after which a {{cmd|apk upgrade}}

will upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level

To later upgrade to the current version,

{{cmd|apk add 'asterisk>1.6.1'}}

will ensure that 1.6.1 is the minimum version used.

You can also use "fuzzy" version matching to pin the version to a major/minor release. For example:

{{cmd|1=apk add 'asterisk=~1.6'}}

will match any version of asterisk that starts with 1.6 (such as 1.6.0.21-r0 or 1.6.9.31-r9).

If you desire deterministic, repeatable package installation (such as with containerized environments) via package pinning, it is important to understand your package repo's version retention rules. Always pin to a package version that is intended for your [[Repositories#Release_Branches|release branch]]. Pinning to a version on the [[Repositories#Edge|edge]] branch may stop working after the package version is revoked from the repo.

=== Commit hooks ===

If you'd like to trigger an action or run a certain script on every commit made by apk, there's a built-in method for that. On every commit apk looks for executables located in the "/etc/apk/commit_hooks.d/" directory, and executes them both before and after the commit. To provide some way to selectively run hooks either before or after a change is commited by apk, the scripts are called with "pre-commit" or "post-commit" as argument 1.
This is an example of a hook to do different things before and after commit:

{{cmd|1=#!/bin/sh

if [ "$1" = "pre-commit" ]; then
do_something

elif [ "$1" = "post-commit" ]; then
do_something_else
fi}}

Commit hooks are $PATH-aware, so for the sake of security it's recommended to specify absolute paths to executables.
<br>

== Rosetta Stone ==

[[Comparison with other distros#Comparison chart/Rosetta Stone|Rosetta Stone]] or a Comparison chart shows how standard things related to package management are done in Alpine Linux compared to other popular distributions.
<br>

== Downgrading from edge to a numbered release ==

Once you modify <code>/etc/apk/repositories</code>, run

<pre>
# apk fix
# apk update
# apk upgrade
# apk upgrade -a
# apk upgrade -al
</pre>

This will usually downgrade all packages automatically, but do not be surprised if you need to manually remove and reinstall a package to complete these commands.

== Troubleshooting ==

=== ERROR: unable to select packages ===

This error typically indicates that the package manager cannot find a suitable package to install. On issuing a command to add a package for eg: {{Codeline|apk add labwc}}, you may receive below error message:
<Pre>
ERROR: unable to select packages:
labwc (no such package):
required by: world[labwc]
</Pre>

The above error indicates {{pkg|labwc}} does not exist in the [[Repositories|repositories]] currently configured in {{Path|/etc/apk/repositories}}. Ensure that <code>community</code> repository is [[Repositories#Managing_repositories|enabled]], as by default only <code>main</code> repository is enabled. You may also want to check [https://pkgs.alpinelinux.org/packages packages database] to identify the correct package name and the [[Repositories|repository]] in which the package is available.

=== ERROR: unsatisfiable constraints ===

This error signifies a dependency conflict. It means that the package you're trying to install has dependencies that cannot be simultaneously satisfied within the current package repository.

You may want to check [https://pkgs.alpinelinux.org/packages packages database] to identify the correct package name and version and the [[Repositories|repository]] in which the package is available.

=== WARNING: This apk-tools is OLD! ===

'''apk update''', '''apk upgrade''' or '''apk add''' may report the following:
WARNING: This apk-tools is OLD! Some packages might not function properly

This may happen if you are running Alpine Linux stable version with a certain edge/main, edge/community or testing package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge is already [https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management#Repository_pinning tagged] in your repositories, then try:

{{Cmd|apk add --upgrade apk-tools@edge}}

=== ERROR: UNTRUSTED signature ===

This happens when the release version changes. You need to update the local apk keys.

If you have already updated your repositories, allow them to update without the trusted key:
{{Cmd|apk update --allow-untrusted}}

Then install the keys upgrade:
{{Cmd|apk fix --upgrade --allow-untrusted alpine-keys}}

Now updates and upgrades should proceed normally.

Alternative, the updated alpine-keys package may be obtained, verified, installed directly, as covered earlier, prior to a repository update.

=== World updated but the following packages are not removed ===

On issuing a command to remove a package for eg: {{Codeline|apk del btrfs-progs}}, you may receive below error message:
<Pre>
World updated, but the following packages are not removed due to:
btrfs-progs: btrbk
</Pre>

Here, the removal of package {{Pkg|btrfs-progs}} affects another package {{Pkg|btrbk}} in the constraints file [[#World|/etc/apk/world]]. So the package {{Pkg|btrfs-progs}} will be removed from the constraints file, but not removed from the system. The {{Pkg|btrfs-progs}} will remain in the system, until the constraint i.e {{Pkg|btrbk}} which depends on {{Pkg|btrfs-progs}} is removed.

If {{Codeline|apk del btrbk}} is issued, the package {{Pkg|btrfs-progs}} will be automatically removed from system as the constraint {{Pkg|btrfs-progs}} does not exist in {{Path|/etc/apk/world}}.

== See Also ==
* [[Comparison with other distros]]
* [[Upgrading_Alpine|Upgrading Alpine Linux to newer Release Branch]]
* [[Repositories|Understand Repositories in Alpine Linux]]

== External Links ==
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
* [https://man.archlinux.org/man/apk-world.5.en man 5 apk-world]
* [https://ariadne.space/2021/04/25/why-apk-tools-is-different-than-other-package-managers/ Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/31/spelunking-through-the-apk-tools-dependency-solver/ spelunking through the apk-tools dependency solver]
* [https://whynothugo.nl/journal/2023/02/18/in-praise-of-alpine-and-apk/ in praise of alpine and apk]

[[Category:Package Manager]]
[[Category:System_Administration]]

Sway

2023-03-14T03:45:51Z

Somercet: new name for ttf-dejavu

[http://swaywm.org Sway] is a tiling [[Wayland]] compositor. It's a drop-in replacement for the i3 window manager.

== Installation ==

eudev:

<pre>
# apk add eudev
# setup-devd udev
</pre>

Graphics drivers:

* [[Intel Video]]
* [[Radeon Video]]
* [[Nvidia Video]]
Add user to the input and video groups:

<pre>
# adduser $USER input
# adduser $USER video
</pre>

Install some TTF fonts:

<pre>
# apk add font-dejavu
</pre>

seatd daemon:

<pre>
# apk add seatd
# rc-update add seatd
# rc-service seatd start
# adduser $USER seat
</pre>

Install sway:

<pre>
# apk add sway sway-doc
# apk add \ # Install optional dependencies:
xwayland \ # recommended for compatibility reasons
foot \ # default terminal emulator. Modify $term in config for a different one.
bemenu \ # wayland menu
swaylock swaylockd \ # lockscreen tool
swaybg \ # wallpaper daemon
swayidle # idle management (DPMS) daemon
</pre>

Configure [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].

== Usage ==

For inter-program communication and functionality such as screensharing, install and enable dbus and PipeWire, see [[PipeWire]] and set <code>SWAYSOCK</code> environmental variable to the value exported by <code>sway</code>. In order to ensure that Pipewire and related services inherit the right environment variables, it is recommended to start these services via a process that is a direct descendant of sway itself.

Launch Sway with a D-Bus server available, use:

<pre>
dbus-run-session -- sway #prepend with exec in your login shell init script
</pre>

== Configuration ==

An example config is provided at <code>/etc/sway/config</code>. Copy it to <code>~/.config/sway/config</code> and read through it to learn the default keybindings.
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].

=== Firefox screensharing ===

For some programs, additional configuration is needed to launch them natively under Wayland and to support special features such as screen sharing.

To launch Firefox natively under Wayland and to enable support for screensharing, you need:

* Install and configure [[PipeWire]]
* Install xdg-desktop-portal and xdg-desktop-portal-wlr package
* Install wofi for screen selection
* Launch pipewire on sway startup:
<pre>
exec /usr/libexec/pipewire-launcher
</pre>
* xdg-desktop-portal will start xdg-desktop-portal-wlr when needed, but needs a few environment variables. Add to the sway config:
<pre>
exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
</pre>
* Export the following variables:

<pre>
export MOZ_ENABLE_WAYLAND="1"
export XDG_CURRENT_DESKTOP=sway
export QT_QPA_PLATFORM="wayland-egl"
</pre>

=== Flatpaks ===

Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>

This is only needed if they are not started automatically via other means.

=== Scaling for high resolution screens ===

Without further configuration, program interfaces might be too small to use on high resolution screens.

==== Via sway ====

Sway supports the per-display configuration of

* fractional (e.g., 1.5x), and
* integer scaling (e.g., 2x)

However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended. See below.

To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add

<pre>
output <name> scale <factor>
</pre>

to ~/.config/sway/config.

==== Via GTK/Qt ====

<pre>
# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE=2

# for QT-based programs
export QT_WAYLAND_FORCE_DPI="physical"
# or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI=192 # 2x scaling
export QT_QPA_PLATFORM="wayland-egl"
</pre>

=== Make clipboard content persistent ===
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.

Install clipman from test repo and add the following to sway config:

<pre>
exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"
</pre>

=== Firefox picture-in-picture mode/floating windows ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Screenshots ===
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.

=== Start with NumLock enabled ===
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>

=== Change cursor theme and size ===
Add to your sway config:
<pre>
seat seat0 xcursor_theme my_cursor_theme my_cursor_size
</pre>
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.
{{Note|Wayland uses client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Start as a service ===
Although this is not necessary, you may write an init script like the following:
<pre>
{{/etc/init.d/sway|
#!/sbin/openrc-run

description="Sway Compositor"

command="/usr/bin/sway"
command_args=""

pidfile="/run/sway.pid"

start_stop_daemon_args="--background --pidfile ${pidfile}"

depend() {
need localmount
after elogind
use seatd dbus
}
</pre>
Then as a root run <code>chmod +x /etc/init.d/seat</code> and <code>rc-update add sway default</code>. Make sure you have elogind installed or specify another service, like your display/login manager after which the sway service will run.

=== Custom keyboard layout ===

Since wayland does not support setxkbmap, you will also need to add similar content to your ''/usr/share/X11/xkb/rules/evdev.xml'', after <code></modelList></code> and after <code><layoutList></code>:
<pre>
<layout>
<configItem>
<name>[the name of your layout, same as the name of the file in /usr/share/X11/xkb/symbols]</name>
<shortDescription>[usually just two letters]</shortDescription>
<description>[description of your layout]</description>
<countryList>
<iso3166Id>US</iso3166Id>
<iso3166Id>NO</iso3166Id>
</countryList>
<languageList>
<iso639Id>eng</iso639Id>
</languageList>
</configItem>
</layout>

</pre>
Then, to enable for all keyboards, navigate to the input section of ''~/.config/sway/config'' and modify it to
<pre>
input * {
xkb_layout "my_layout"
}
</pre>
If you have enabled <code>xkb_numlock</code>, include this setting inside those braces as well.

== Troubleshooting ==

If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).

=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').

=== Sway socket not detected ===

See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[Tmux terminal multiplexer|tmux]]

=== Steam games launched via Proton crash before creating a window ===

Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.
[[Category:Desktop]]