Pikman Guide

pikman v1.23.6.5.2 — One package manager to rule them all

Source: https://git.pika-os.com/general-packages/pikman

---

Table of Contents

• Overview
• Installation
• Usage
• Global Options
• Commands per Backend
• Container Management
• Backend Details
• FAQ

---

Overview

pikman is a unified CLI wrapper around apx containers, apt, and flatpak. It maps commands across five backends:

Backend	Flag	Default	Underlying tool
Debian Sid	(none / default)	Yes	sudo -S apt
Arch Linux	--arch / --aur		apx (subsystem: pikman-arch-linux)
Fedora	--fedora / --dnf		apx (subsystem: pikman-fedora-workstation)
Alpine	--alpine / --apk		apx (subsystem: pikman-alpine)
Flatpak	--flatpak / --fl		flatpak

Important: The default backend is Debian Sid (sudo -S apt), not auto-detected. pikman does NOT auto-detect your distribution — it defaults to Debian Sid unless you pass a backend flag.

pikman refuses to run as root. You must run it as a normal user.

---

Installation

pikman is pre-installed at /usr/bin/pikman. It's packaged as a .deb for PikaOS / Debian Sid-based systems.

---

Usage

pikman [global options] command [command options] [arguments...]

---

Global Options

Flag	Description
--arch, --aur	Use Arch Linux backend (apx subsystem)
--fedora, --dnf	Use Fedora backend (apx subsystem)
--alpine, --apk	Use Alpine backend (apx subsystem)
--flatpak, --fl	Use Flatpak backend
--name <value>	Target a specific managed container name
--help, -h	Show help
--version, -v	Show version

---

Commands per Backend

Not all commands are available on every backend.

Command	Alias	Debian Sid	Arch	Fedora	Alpine	Flatpak
install	i	✅	✅	✅	✅	✅
remove	r	✅	✅	✅	✅	✅
purge		✅	✅	✅	✅	❌
autoremove		✅	✅	✅	✅	❌
search	s	✅	✅	✅	✅	✅
show		✅	✅	✅	✅	✅
list	l	✅	✅	✅	✅	✅
update		✅	✅	✅	✅	✅
upgrade		✅	✅	✅	✅	❌
upgrades		✅*	❌	❌	❌	✅*
clean	cl	✅	✅	✅	✅	❌
log		❌	❌	❌	❌	✅
enter		❌	✅	✅	✅	✅
init		❌	✅	✅	✅	❌
export		❌	✅	✅	✅	❌
unexport		❌	✅	✅	✅	❌
run		❌	✅	✅	✅	✅

* upgrades is handled via a separate code path (updates/updates.go) — runs apt list --upgradable on Debian Sid and flatpak remote-ls --updates on Flatpak.

---

Container Management

Container isolation (via apx subsystems) is available for Arch, Fedora, and Alpine backends. Debian Sid and Flatpak do not use containers.

The default container subsystem names are:

Backend	Container name	Apx subsystem
Arch	pikman-arch-linux	arch-linux
Fedora	pikman-fedora-workstation	fedora-workstation
Alpine	pikman-alpine	alpine

Auto-init

When you run any non-init command on Arch, Fedora, or Alpine, pikman automatically checks if the container subsystem exists. If not, it creates it using:

apx subsystems new -n <name> -s <subsystem>

init

Initialize a managed container subsystem explicitly.

pikman --arch init

(Internally: apx subsystems new -n pikman-arch-linux -s arch-linux)

enter

Open an interactive shell inside a container.

pikman --arch enter

run

Run a command inside a container without entering interactively.

pikman --arch run -- neofetch

export

Export or recreate a desktop entry from a containerized application.

pikman --arch export firefox

unexport

Remove a previously exported desktop entry.

pikman --arch unexport firefox

---

Backend Details

Debian Sid (default)

Uses sudo -S apt under the hood. The password prompt is handled via sudo -S (reads from stdin).

pikman install firefox
pikman update
pikman upgrade            # runs: apt update && sudo -S apt dist-upgrade
pikman upgrades           # runs: apt list --upgradable
pikman upgrades --json    # JSON output: {Name, Version, Architecture}

No container support. enter, init, export, unexport, run, log are unavailable.

---

Arch Linux (--arch / --aur)

Uses apx pikman-arch-linux which internally runs pacman (and yay/paru for AUR).

pikman --aur install yay-bin
pikman --arch install neovim
pikman --arch update
pikman --arch upgrades    # NOT available — only Debian Sid and Flatpak support upgrades

---

Fedora (--fedora / --dnf)

Uses apx pikman-fedora-workstation which internally runs dnf.

pikman --fedora install httpd

---

Alpine (--alpine / --apk)

Uses apx pikman-alpine which internally runs apk.

pikman --alpine install nginx

---

Flatpak (--flatpak / --fl)

Uses flatpak directly. No container, no sudo.

pikman --flatpak install org.gimp.GIMP
pikman --flatpak update
pikman --flatpak upgrades           # runs: flatpak remote-ls --updates
pikman --flatpak upgrades --json    # JSON output: {Name, ApplicationID, Branch, Arch}
pikman --flatpak log                # runs: flatpak history