How to Install and Manage Software with HaikuDepot and pkgman

HaikuDepot and pkgman are two clients of Haiku’s package-management infrastructure. They resolve dependencies, download HPKG files, and ask the package daemon to activate a new package set through packagefs. They share installed state, but their strengths differ: HaikuDepot is better for discovery and metadata, while pkgman exposes reproducible terminal operations and diagnostics.

Inventory the system before changing it

Record Haiku revision and architecture, configured repositories, and installed packages:

uname -a
getarch
pkgman list-repos
pkgman search -a -i -D

In current pkgman, search -a lists all packages, -i limits to installed packages, and -D includes dependency-only packages. This replaces the nonexistent pkgman list shown in some generic tutorials.

Save the output before a large update or repository change. Also inspect /boot/system/non-packaged and ~/config/non-packaged; software placed there is intentionally outside package activation and will not appear in the package inventory.

Keep a data backup. Packagefs preserves administrative states for recovery from package activation problems, but those states are on the same disk and do not back up documents or settings.

Discover packages with HaikuDepot

Open HaikuDepot from Deskbar’s Applications menu. Filter by category, package name, or description, and select the relevant repository. Its status column distinguishes installed, available, and pending packages; the info area shows description, version, publisher/contact data, ratings, changelog, and—after download—package contents.

Treat community ratings as experience reports, not security review. Verify the upstream project, maintainer, license, repository, architecture, version, and requested dependencies before installation. Development, source, and debug packages are hidden by default because most users do not need them; enable those views only for a concrete development/debugging purpose.

Click Install, review the dependency transaction, and wait for downloads and activation. Package activation can be fast, but total installation time still depends on package size, network, repository responsiveness, verification, and dependency count. Do not claim it is independent of package size.

Search and inspect from Terminal

Use a specific term, then inspect candidates:

pkgman search texteditor
pkgman info PACKAGE_NAME

Names can be similar across repositories or represent libraries rather than applications. Read version, architecture, provides/requires, repository, and description. When a command or library is needed rather than a known package name, pkgman search --help documents requirement-oriented and search-scope options on the installed release.

Install the intended package and read the solver’s proposed changes:

pkgman install PACKAGE_NAME

Do not automate an unconditional “yes” until the exact repository set and transaction have been tested. A solver can legitimately replace/conflict packages; that deserves review in repeatable provisioning.

After installation, launch the real application or command and verify its version and core operation. An HPKG being active does not prove the program works on the current hardware or that its settings migrated.

Refresh metadata and update packages correctly

Refreshing repository metadata and updating installed packages are different operations:

pkgman refresh
pkgman update

refresh retrieves current repository information. update computes and activates newer versions of installed packages; it can also accept package arguments. The graphical SoftwareUpdater is the supported interactive update interface and is available from HaikuDepot’s menu.

Close important applications, save work, ensure adequate disk space and power, and preserve the complete transaction output. Reboot after system components are updated when the official guide requires it, then confirm revision, repositories, applications, networking, and settings.

Do not run pkgman full-sync as a casual synonym for update. Its own help calls it more aggressive: it can also downgrade packages and remove installed packages that repositories no longer provide. Use it when an official upgrade/downgrade/repository-switch procedure specifically calls for full synchronization, after reviewing backup and recovery paths.

Remove software without deleting user data blindly

Uninstall from HaikuDepot’s selected package or use:

pkgman uninstall PACKAGE_NAME

Review dependent removals before accepting. The package-owned files disappear from packagefs, while user settings and documents in writable home directories generally remain. Decide separately whether to archive or remove those files; do not use a recursive deletion command copied from another application’s layout.

Verify the program no longer launches from Deskbar, its package is absent from the installed inventory, and other applications still resolve. Removing a library package can affect several clients even when it has no visible icon.

Manage repositories as trust boundaries

Inspect repository names, URLs, identifiers, and enabled state:

pkgman list-repos

The Repositories preference panel can enable, disable, add, and remove repositories. Current pkgman source documents the terminal form as:

pkgman add-repo REPOSITORY_URL

It accepts URLs, not the invented pkgman add-repo <name> <url> syntax from the old article. Run pkgman add-repo --help on the installed build before scripting because aliases and options can evolve.

Add only a repository whose operator, signing/transport, architecture, release compatibility, and update policy you trust. Repository priority and overlapping package names can change which build the solver selects. Save the pre-change list, add one repository at a time, refresh, inspect candidate origins, then install.

To remove a repository, use the documented Repositories panel workflow or current pkgman drop-repo help. First determine which installed packages came only from it and what replacements the remaining repositories provide.

Diagnose dependency and transaction failures

Capture the exact command and first error. Verify network, system clock, free space, repository status, architecture, and whether all configured repositories belong to the same intended Haiku release family. Refresh metadata and repeat the non-destructive search/info checks.

Do not use pkgman resolve-dependencies as a universal “repair installed system” button. Current source defines it for resolving dependencies of specified package files against specified repository directories; it requires arguments and serves a different packaging workflow.

Likewise, never drag HPKG files in and out of /boot/system/packages while the package daemon is processing a transaction. Use the package manager and preserve /boot/system/packages/administrative for documented recovery.

HaikuDepot can emit diagnostic logs when started from Terminal with an appropriate verbosity such as HaikuDepot -v debug. Review logs for tokens, user names, URLs, or local paths before attaching them publicly.

Recover from a problematic update

There is no current pkgman rollback command. Haiku keeps old package states under the package administrative directory, and the official update/downgrade guide documents booting an earlier working state from the boot loader’s troubleshooting menu.

If a system update prevents normal boot, select a known-good prior package state, boot it, save logs and inventory, and identify the regression. For a permanent downgrade, follow the official guide’s repository/revision and full-sync procedure exactly; not every historical revision remains available.

Do not delete administrative state directories while troubleshooting. Once the system is stable and backups exist, pkgman cleanup is the current package-manager command intended to remove obsolete downloaded/package state according to its help. Review what it proposes instead of manually deleting arbitrary administrative directories.

Verify and document the final state

Repeat the initial inventory and diff it. Confirm repositories are intentional, installed versions are expected, no needed package disappeared, real application paths work, and reboot-sensitive services recovered. Record any package intentionally pinned or repository intentionally disabled.

The safest operating model is simple: discover in HaikuDepot, inspect origin and dependencies, perform explicit transactions, reserve full-sync for documented reconciliation, recover through real administrative states rather than fictional commands, and keep non-packaged software visible in the audit.

Related:

Sources: