equery Command: Tutorial & Examples

Query installed Gentoo packages, files, dependencies, and USE flags

The equery command is a powerful utility designed for Gentoo Linux systems that use the Portage package management system. Provided by the app-portage/gentoolkit package, equery facilitates querying detailed information about installed packages, their files, dependencies, and USE flags. It helps system administrators and users efficiently manage and troubleshoot packages via the command line.

What equery Does And Why It Is Important

equery is primarily used to retrieve comprehensive information about Gentoo packages. It can:

  • List installed versions of packages.
  • Show all files installed by a package.
  • Identify which package owns a specific file.
  • Display the dependency graph of a package.
  • Present USE flags and their current states.
  • Provide metadata such as package descriptions and homepage URLs.

This functionality is crucial for managing Gentoo systems, especially when diagnosing package conflicts, resolving high load caused by problematic software, or auditing installed software components. By offering detailed insights, equery reduces the complexity of package management in Gentoo's source-based system.

How equery Works

equery interacts with the Portage package database and the Portage tree located in /usr/portage or its mirrors. It reads metadata and installation information stored by Portage about installed packages, including files, dependencies, and USE flags.

When executed, equery parses this data and outputs it in a human-readable format. It leverages Portage's internal tools and data structures, making it a reliable extension to the package management workflow without modifying packages or the system state.

Command History And Evolution

equery was introduced as part of the gentoolkit package, which aggregates useful tools to extend Portage's capabilities. Over time, it has evolved to support multiple subcommands, making it a versatile query tool in Gentoo's package management ecosystem. Unlike direct Portage commands like emerge, equery focuses solely on querying rather than installing or removing packages.

Installing equery

Since equery is not included by default in Gentoo installations, it must be installed explicitly by installing gentoolkit. Use the following command:

emerge app-portage/gentoolkit

This will provide equery along with other useful Portage utilities.

Common equery Subcommands And Parameters

The equery command uses subcommands to specify the type of information requested. Some of the most useful subcommands include:

  • list: Lists all installed versions of a package.

    equery list

  • files: Lists all files installed by the package.

    equery files

  • belongs: Finds the package that owns a given file path.

    equery belongs

  • depgraph: Displays the dependency graph for a package.

    equery depgraph

  • uses: Shows the USE flags for a package, indicating which are enabled or disabled.

    equery uses

  • meta: Displays package metadata including description, license, and homepage.

    equery meta

  • check: Checks for missing or broken dependencies in installed packages.

    equery check

Many subcommands accept additional options. For detailed usage of each subcommand, consult the manual page with:

man equery

Practical Examples Using equery

Below are several examples illustrating common equery uses, including typical output and explanations.

Listing Installed Versions of a Package

equery list vim

Typical output:

* Searching for vim ...
[IP-] [  ] app-editors/vim-8.2.2434:0

Explanation:

  • The flags in brackets indicate package status (I = Installed, P = Present in tree).
  • The package category, name, version, and slot are shown.

Listing Files Installed By A Package

equery files vim

Typical output:

* Contents of app-editors/vim-8.2.2434:

/usr
/usr/bin
/usr/bin/vim
/usr/share
/usr/share/vim
/usr/share/vim/vim82
/usr/share/vim/vim82/syntax
...

This lists all files and directories installed by the vim package, useful for auditing and troubleshooting.

Finding Which Package Owns A File

equery belongs /usr/bin/vim

Typical output:

* Searching for /usr/bin/vim ...
app-editors/vim-8.2.2434 (/usr/bin/vim)

This command helps identify the package responsible for a specific file, which is useful when cleaning up or diagnosing file conflicts.

Displaying Dependency Graph

equery depgraph vim

Sample output:

app-editors/vim-8.2.2434
├─ dev-libs/libacl-2.2.53
├─ sys-libs/glibc-2.35
└─ x11-libs/libX11-1.7.2

This graphical representation shows packages that vim depends on, aiding in understanding package relationships.

Showing USE Flags For A Package

equery uses vim

Sample output:

* USE flags for app-editors/vim-8.2.2434:
+acl -gtk -gnome -perl -python -ruby -selinux -X -X11

The plus (+) indicates enabled flags; minus (-) indicates disabled flags. USE flags control optional features and dependencies.

Displaying Package Metadata

equery meta vim

Sample output:

* Package metadata for app-editors/vim-8.2.2434:
Description : Vi IMproved, a highly configurable text editor
Homepage    : https://www.vim.org/
License     : Vim
Maintainer  : gentoo-dev@gentoo.org

Common Errors And Troubleshooting

While using equery, you may encounter issues such as:

  • Permission Denied Errors: Running equery without sufficient permissions can prevent access to package databases or files. Run with sudo if necessary:

    sudo equery files vim

  • Command Not Found: If equery is missing, verify that gentoolkit is installed.

  • Outdated Portage Tree: Results may be inaccurate if the Portage tree is not synced. Run:

    emerge --sync

  • File Not Owned By Any Package: When using equery belongs, a file may not belong to any installed package, indicating it was manually installed or created.

  • Large Output Delays: Querying large packages or full dependency graphs may take time; consider limiting scope or using filters.

Advanced Usage

equery can be integrated into scripts and automation to gather package information for batch processing or monitoring. For example, to check which packages depend on a given package:

equery depgraph --reverse <package>

Or to list all packages with a specific USE flag enabled:

equery uses '*' | grep '+<use_flag>'

Combining output with other tools like grep, awk, or xargs allows powerful custom queries.

Security Considerations

Since equery accesses system package data, running it with elevated privileges (e.g., via sudo) may be necessary. Be cautious running scripts with equery as root to avoid unintended system changes. equery itself is read-only and safe but improper use of output in automation could introduce risk.

Performance Considerations

On systems with many installed packages or large Portage trees, some equery queries (especially dependency graphs) can be slow. Limiting queries to specific packages or using caching mechanisms can improve performance.

Possible Alternatives Or Related Commands

  • qfile: Another Portage utility to find which package owns a file.
  • qdepends: Lists dependencies of a package.
  • equery vs emerge: emerge manages package installation, removal, and updates, while equery only queries package information.

Tips And Best Practices

  • Use equery regularly to audit installed packages and their files.
  • Combine with other Portage tools to troubleshoot issues quickly.
  • Keep your Portage tree synced to ensure accurate results.
  • Use equery uses to understand and optimize USE flags for your system needs.

See Also

Further Reading

As an Amazon Associate, I earn from qualifying purchases.

The text above is licensed under CC BY-SA 4.0 CC BY SA