How to mask a Gentoo package

A local Gentoo package mask keeps Portage from selecting a package when that package should not be installed or upgraded on one system. Use it to block a broken release, prevent an unwanted provider from satisfying dependencies, or hold back a package family while a safer replacement is tested.

/etc/portage/package.mask accepts one package atom per line, either in a single file or in files under a directory of the same name. A plain category/package atom masks every matching version, while an operator such as >=category/package-version limits the mask to a version range.

Use the narrowest atom that matches the policy you mean to enforce. A local mask does not remove an installed package by itself, and package.accept_keywords does not override package.mask, so confirm the result with a pretend merge before relying on the entry during a world update.

1. Preview the package before adding a local mask.

   $ emerge --pretend --verbose app-misc/tmux
   These are the packages that would be merged, in order:
    
   Calculating dependencies  ... done!
   Dependency resolution took 0.56 s (backtrack: 0/20).
    
   [ebuild  N     ] dev-libs/libevent-2.1.12-r1:0/2.1-7::gentoo  USE="clock-gettime ssl -debug -malloc-replacement -static-libs -test -verbose-debug -verify-sig" 1076 KiB
   [ebuild  N     ] app-misc/tmux-3.5a::gentoo  USE="-debug -jemalloc (-selinux) -sixel -systemd -utempter -vim-syntax" 699 KiB
    
   Total: 2 packages (2 new), Size of downloads: 1774 KiB

   Replace app-misc/tmux with the package atom you need to block. The preview shows whether Portage can currently select the package and which version would be affected.

2. Choose the narrowest mask atom for the local policy.

   Goal	Example atom
   Mask every version of one package	app-misc/tmux
   Mask one exact version	=app-misc/tmux-3.5a
   Mask that version and newer	>=app-misc/tmux-3.5a

   Do not use a broad category or wildcard atom unless the system policy really needs it. A broad local mask can block dependency resolution for unrelated packages during future updates.

3. Create the local package.mask directory if it is missing.

   $ sudo install -d /etc/portage/package.mask

4. Open a package-specific mask file.

   $ sudoedit /etc/portage/package.mask/tmux

   The filename is for organization. Portage reads the package atoms inside /etc/portage/package.mask and does not require the filename to match the package name.

5. Add the mask entry.

   # Keep tmux off this system while testing a local replacement.
   app-misc/tmux

   Keep comments on separate lines and put one package atom on each policy line. Use a versioned atom such as >=app-misc/tmux-3.5a when only a release range should be blocked.

6. Confirm the saved entry.

   $ cat /etc/portage/package.mask/tmux
   # Keep tmux off this system while testing a local replacement.
   app-misc/tmux

7. Preview the package again and confirm Portage reports package.mask.

   $ emerge --pretend --verbose app-misc/tmux
   These are the packages that would be merged, in order:
    
   Calculating dependencies  ... done!
   Dependency resolution took 0.36 s (backtrack: 0/20).
    
    
   !!! All ebuilds that could satisfy "app-misc/tmux" have been masked.
   !!! One of the following masked packages is required to complete your request:
   - app-misc/tmux-9999::gentoo (masked by: package.mask, missing keyword)
   - app-misc/tmux-3.6a::gentoo (masked by: package.mask, ~arm64 keyword)
   - app-misc/tmux-3.5a::gentoo (masked by: package.mask)
   - app-misc/tmux-3.4-r1::gentoo (masked by: package.mask)
    
   For more information, see the MASKED PACKAGES section in the emerge
   man page or refer to the Gentoo Handbook.

   The package is masked when every matching version in the pretend output includes masked by: package.mask. Other mask reasons can appear on the same line, but package.mask must be present for the local mask to be the reason this page configured.

8. Leave a clear reason for the mask or remove it when the package should be allowed again.

   $ sudoedit /etc/portage/package.mask/tmux

   Remove the local line instead of adding a matching package.unmask entry when you are undoing your own local mask. Use package.unmask for an intentional override of a repository or profile mask, and review that as a separate policy decision.