Gentoo Package Operations Manual
On this page
This guide is specific to Portage. Separate repository metadata, desired configuration, installed packages and the world selection set to understand rebuilds and depclean. Use an authorized maintenance shell; profile changes and empty-tree rebuilds are not routine fixes.
| Task | Start here |
|---|---|
| Review updates and conflicts | Inspect the plan |
| Change USE or keywords | Scoped policy |
| Remove unused packages | World and dependencies |
| Build failures and config merges | Maintenance evidence |
Sync metadata, then preview changes
Record environment, sync repositories, read migration news
# Record profile, toolchain, and global build settings
Keep the full output for diagnosis, reviewing host-specific details before sharing. Maintenance requires appropriate privileges.
# Update configured repository metadata
This does not upgrade installed packages. Resolve synchronization failures before interpreting the update plan.
# List maintenance news after synchronization
# Read the relevant item from the list
Replace 1 with the actual item. Complete prerequisites for profile, Python, or toolchain migrations first.
Review resolution before updating the same scope
# Preview world updates and USE-triggered rebuilds
-p previews, -v adds detail, -u updates, -D includes deep dependencies, and -N checks new USE. Review blockers, slots, downgrades, and rebuild reasons before acting.
# Confirm and execute the reviewed update scope
-a replaces -p; review the resulting plan again, especially after config/repository changes. Merge configuration and verify services before considering depclean.
Choose a package query for the question
# List installed packages
equery is provided by app-portage/gentoolkit. The following queries are independent lookups.
# Inspect USE flags for the target package
# Find packages that depend on this package
This reports reverse dependencies, not everything neovim itself requires.
# Inspect files installed by the package
equery comes from gentoolkit; eix and qlist are optional. Review additions, upgrades, downgrades, reinstalls, slots and blockers. Read relevant news before applying the reviewed emerge -avuDN @world plan. Align build-dependency retention with source/binary maintenance policy.
USE, keywords and masks have different roles
| Configuration | Purpose | Boundary |
|---|---|---|
| package.use | Build features | Check supported flags; arbitrary gtk/qt examples may be invalid |
| package.accept_keywords | Accept testing keywords for selected packages | Scope to package/version, avoid global ** |
| package.mask / package.unmask | Restrict candidates / unmask selected atoms | Unmask does not fix keywords or dependency conflicts |
These are two separate file fragments. Merge according to the existing directory/file layout; do not concatenate them into one file. Check flag support with the queries below first.
/etc/portage/package.use/editor
app-editors/vim python
/etc/portage/package.accept_keywords/editor
app-editors/neovim ~amd64
~amd64 accepts testing keywords for that architecture only. Apply only when needed, not as a universal default.
Inspect before and after package-scoped changes
# Check supported flags and current state
python is a Vim feature example; verify current ebuild support before merging the file fragment above.
# Preview the selected version and USE after editing
If unexpected, inspect more specific package.use, profile, and mask settings before changing global USE.
Choose the USE rebuild policy
# Preview updates triggered by changed enabled USE states
Focuses on changed states; this is an alternative to the --newuse policy below.
# Preview updates including added or removed flags
Choose the policy used for this system; execute with -a instead of -p while retaining the resolution options.
The --newuse and --changed-use previews are not identical: newuse can rebuild for added or removed disabled flags; changed-use focuses on effective changes. A temporary USE assignment is not persisted in package.use. Review and merge autounmask-write output.
Absent from world does not mean removable
Deselecting does not uninstall. depclean considers dependency reachability from protected sets; shared libraries still required by another package remain.
Inspect explicit selections before deselecting a target
# Inspect explicitly selected packages
This is the user package list, not the full @world dependency closure; selected sets and system/profile also matter.
# Preview current cleanup candidates before deselection
# Deselect only when the package is no longer wanted
This changes selection without uninstalling. Skip it for inspection only; an accidental deselection can be reversed with emerge --ask --noreplace app-edititors/neovim.
Resolve again before cleanup
# Recompute cleanup against the new selection
Review services, temporary tools, and build dependencies. A still-required package remains despite deselection.
# Confirm the complete list before removing unreachable packages
Complete updates and resolve dependency issues first; do not force the expected list with --unmerge.
# Rebuild consumers of preserved libraries when indicated
Follow emerge’s guidance, then verify key programs/services. This is not a generic repair for every build or runtime failure.
Complete updates and review the entire cleanup plan first. Deselect removes explicit selection; dependencies can still retain the package. -1 installs without adding to world. Unmerge can bypass dependency protection. preserved-rebuild rebuilds consumers of preserved libraries, not every possible failure.
Config merges, repositories and build failures
Configuration updates: find and merge differences
# Find configuration files awaiting merge
Permission errors do not prove there are no pending updates.
# Review and merge configuration interactively
Review diffs and preserve local changes. Validate affected services before reload/restart; do not blindly accept every new file.
Inspect repositories and toolchains
# List repositories and enabled state
Requires the repository eselect module; enabled does not mean synchronized.
# Use the alternative all-repository synchronization entry
Choose according to auto-sync policy rather than repeating emerge --sync; use -r NAME for one enabled repository.
# Read the current profile without switching
# Inspect installed compiler profiles and selection
Failure recovery: retain the first error and plan
# Identify the failed package and maintenance stage by time
Press q to exit. Detailed errors are in the package temp/build.log under PORTAGE_TMPDIR; preserve it before cleanup.
# Preview the interrupted merge list after fixing the cause
Confirm it is the intended task before emerge --resume --ask. Do not hide required failures with skipfirst; re-resolve if the configuration goal changed.
| Problem | Evidence to keep | Next action |
|---|---|---|
| Build failure | emerge --info; build.log | Keep that package’s temp/build.log and first real error |
| Protected config update | ._cfg* | Review with dispatch-conf or etc-update; neither means blindly accept |
| Profile / Python / GCC migration | eselect news; emerge --info | Follow migration instructions; changing a command does not migrate dependencies |
Review overlay provenance and package overrides before enabling and syncing it. MAKEOPTS parallelism and simultaneous emerge jobs multiply memory pressure; size them using workload evidence. Retain a verified bootable fallback when cleaning kernels; see the kernel manual.