What is Pactool?

Pactool is a versatile, simple, and powerful package management helper designed for Arch Linux and Debian-based distributions. It provides a clear and modern overview of all installed packages, their sizes, and dependencies, and offers various tools to optimize and maintain your system efficiently.

---

Features

• Cross-distro support for Arch Linux, Manjaro, Debian, Ubuntu, and other derivatives.
• Advanced package listing with pagination, sorting (name, size, type), and filtering (user/system packages).
• Full search, install, uninstall, update, and upgrade commands.
• Mirror management with support for automatic backups and restores:
  • Show current mirrors with latency checks and timestamps.
  • Auto-update mirrors to the fastest available servers.
  • Backup and revert mirrors using timestamped snapshots.
• Dependency & reverse dependency tree analysis via --why PACKAGE.
• File ownership: list all files installed by a package with --files PACKAGE.
• Cache cleaning with safe prompts.
• Kernel utilities:
  • --cleanup-kernels for removing outdated kernels safely.
  • --backup-kernel to backup the current kernel and initramfs.
• Color-coded, human-friendly output for better readability.
• Detailed statistics with --stats to understand package count, disk usage, and outdated software.
• Interactive confirmations for critical actions like upgrades, removals, or mirror changes.

---

Installation & Setup

Run Directly

python3 pactool.py --help

Add Pactool to PATH (Global Install)

sudo cp pactool.py /usr/local/bin/pactool
sudo chmod +x /usr/local/bin/pactool

Requirements

• Python 3.8+
• reflector (Arch Linux) or netselect-apt (Debian/Ubuntu) for mirror management.
• Core package manager tools (dpkg, apt, or pacman) depending on your distro.
• sudo permissions for kernel or mirror-related operations.

---

Basic Usage

python3 pactool.py [COMMANDS] [OPTIONS]

Examples

# Show all installed packages
python3 pactool.py --list

# Show only 20 packages
python3 pactool.py --list -n 20

# Search for 'firefox'
python3 pactool.py --search firefox

# Install VLC
python3 pactool.py --install vlc

# Uninstall VLC
python3 pactool.py --uninstall vlc

# Update all packages
python3 pactool.py --update

# Upgrade system
python3 pactool.py --upgrade

---

Package Management

List Packages

Display installed packages with pagination and sorting:

python3 pactool.py --list -n 30

Sort by name:

python3 pactool.py --list --sort name

Reverse sort by size:

python3 pactool.py --list --rsort size

Search Packages

python3 pactool.py --search vlc

Show Package Info

python3 pactool.py --info vlc

Check for Outdated Packages

python3 pactool.py --outdated

---

Mirror Management

Show Current Mirrors

Displays active mirrors with response time and last updated:

python3 pactool.py --show-mirrors

Sample Output:

[✔]  https://mirror.osbeck.com/archlinux/$repo/os/$arch         124.42 ms    (Last Updated: Fri, 18 Jul 2025 14:38:24 GMT)
[✔]  https://mirror.cyberbits.eu/archlinux/$repo/os/$arch       738.60 ms    (Last Updated: Fri, 18 Jul 2025 13:30:26 GMT)
[✔]  https://mirror.ubrco.de/archlinux/$repo/os/$arch           949.06 ms    (Last Updated: N/A)

Update to Fastest Mirrors

python3 pactool.py --update-mirrors

Backup Mirrors

python3 pactool.py --backup-mirrors

Backups stored in:

~/.cache/pactool/mirrors/

Revert Mirrors

python3 pactool.py --revert-mirrors

Example:

Available backups:
(1) Friday, 18 July 2025 at 05:42:54
(2) Friday, 18 July 2025 at 05:44:15

Which backup would you like? (ID) > 2
Reverted mirrors to 2025-07-18_05-44-15

---

Kernel Management

Pactool simplifies kernel management on Arch and Debian systems.

Cleanup Old Kernels

python3 pactool.py --cleanup-kernels

This removes outdated kernels while keeping the current version intact.

Backup Current Kernel

python3 pactool.py --backup-kernel

Backs up vmlinuz, initramfs, and optionally System.map to:

/boot/pactool/backup/

---

Advanced Commands

Reverse Dependency Tree

python3 pactool.py --why firefox

Output:

Reverse dependency tree for 'firefox':

firefox
  └─ gnome-browser
    └─ gnome-desktop

List Files Installed by a Package

python3 pactool.py --files vlc

Example:

Files installed by 'vlc':
    /usr/bin/vlc
    /usr/share/applications/vlc.desktop
    /usr/share/icons/hicolor/48x48/apps/vlc.png

Clean Cache

python3 pactool.py --clean

Cleans package cache and prompts before deleting.

Security Management

Pactool offers built-in tools to manage and check for security vulnerabilities.

View Security Packages

Check for installed security-related packages on Debian/Ubuntu or run a security audit on Arch Linux:

python3 pactool.py --view-security-packages

Debian/Ubuntu Example Output:

Security Packages Installed (Debian/Ubuntu):
libssl1.1
libgnutls30

Arch Linux Example Output:

grub        [High Risk]    Affected by multiple issues.
libxml2     [High Risk]    Affected by denial of service.

Packages are color-coded:

• Blue: System packages.
• Magenta: User-installed packages.

Upgrade Security Packages

On Debian/Ubuntu systems, upgrade only security-related packages:

python3 pactool.py --upgrade-security

This ensures only security-related updates are applied.

Check Security Vulnerabilities

You can run a vulnerability check for any package using:

python3 pactool.py --vuln-check PACKAGE

Example:

python3 pactool.py --vuln-check openssl

This will list all known CVEs, paginate results, and allow keyword searching within CVEs.

You can also perform a deep search on a package

python3 pactool.py --vuln-check feh --deep-search

Deep‑Dive Commands: --history & --versions

These two commands for very useful for tracking package vulnerabilities on your Linux system.
They are optional, safe‑to‑run, read‑only operations – nothing is modified on disk.

---

--history PACKAGE — Time‑Travel Through Install & Upgrade Events

What it does	Why it matters
Parses native logs (/var/log/pacman.log on Arch/Manjaro, apt history on Debian/Ubuntu).	No additional services or daemons required.
Groups each event → Installed / Upgraded	Instantly see when & why a package changed.
Extracts the exact command that triggered the change.	Answers “Which script or user action installed this?”
Builds a tree of version transitions (3.10.3‑1 → 3.11.0‑2).	Visual diff of how you arrived at the current release.
Colour‑codes user vs system packages.	Glance‑level ownership info.
Respects Ctrl +C — quits instantly, no messy tracebacks.	Friendly CLI UX.

Example

pactool --history bash

Package Version History for 'bash':

    Installed bash (5.2.037‑1)              on 15 Feb 2025, 06:43 AM UTC
     Upgraded bash (5.2.037‑1 → 5.2.037‑2)  on 14 Mar 2025, 10:49 AM UTC+03:00
     Upgraded bash (5.2.037‑2 → 5.2.037‑3)  on 07 May 2025, 09:53 AM UTC+03:00
     Upgraded bash (5.2.037‑3 → 5.2.037‑5)  on 10 May 2025, 02:33 AM UTC+03:00
     Upgraded bash (5.2.037‑5 → 5.3.0‑1)    on 14 Jul 2025, 12:47 AM UTC+03:00

    Command used:
        pacman -Syu bash

    Version Tree:
        ├─ 5.2.037‑1
        ├─ 5.2.037‑1 → 5.2.037‑2
        ├─ 5.2.037‑2 → 5.2.037‑3
        ├─ 5.2.037‑3 → 5.2.037‑5
        └─ 5.2.037‑5 → 5.3.0‑1 (current)

Tips

• Pipe to less -R to keep colours while scrolling.
• Combine with grep to find a specific date:
  pactool --history openssl | grep 2025‑04

---

--versions PACKAGE — Repo‑Wide Version Explorer

Quick glance

Mode	Purpose
Plain (--versions pkg)	Fast list – shows every build string available in enabled repositories.
Risk mode (--versions pkg --assess-risk)	Queries the NVD API live, counts CVEs per version, colour‑codes severity, shows a spinner while fetching.

Why you’ll love it

• Upgrade forecasting – see what you’ll get before hitting pacman -Syu.
• Rollback clarity – pick an earlier safe build if the latest has many CVEs.
• Security snapshot – Low/Medium/High risk label + exact CVE count.

Example – quick scan

pactool --versions python

    ├─ 3.12.6‑2
    ├─ 3.12.6‑3
    └─ 3.13.0‑1  (current)

Example – full risk audit

pactool --versions python --assess-risk

Assessing risk for 'python' [\]
Available Versions for 'python':

    ├─ 3.12.6‑2  [LOW RISK]     0 CVEs
    ├─ 3.12.6‑3  [MEDIUM RISK]  4 CVEs
    └─ 3.13.0‑1  [HIGH RISK]    7 CVEs  (current)

How the risk score works

CVE Count	Label	Typical action
0	LOW RISK	Safe to use / keep.
1 – 5	MEDIUM RISK	Read CVE details; upgrade soon.
> 5	HIGH RISK	Patch or pin a safer version ASAP (or get exploited, idc either way).

NVD API is rate‑limited (5 req / 30 s). Pactool caches results per session to avoid throttling.

---

Some really useful combinations

Goal	Command
Audit all install events and fetch CVEs for each version	pactool --history openssl && pactool --versions openssl --assess-risk
Show only available versions newer than installed	pactool --versions vim | awk '$1 > "9.0.0"'
Continuous monitoring (cron)	pactool --versions kernel --assess-risk >> /var/log/kernel-risk.log

---

Command Overview

GENERAL COMMANDS:
  --version                   Show Pactool version and exit
  --about                     Display detailed information about Pactool

PACKAGE COMMANDS:
  --list                      List installed packages (paged by default)
  -n N                        Number of packages to show (0 = all)
  --stats                     Show statistics about packages
  --files PACKAGE             List all files installed by a package
  --search SEARCH             Search for a package by name
  --why PACKAGE               Show reverse dependencies of a package
  --uninstall PACKAGE         Uninstall a package by name
  --install PACKAGE           Install a package by name
  --update                    Update all installed packages
  --upgrade                   Upgrade all installed packages
  --clean                     Clean cached or unused package files
  --sort CRITERIA             name/size/install-date/update-date/type
  --rsort CRITERIA            Reverse sort by the same criteria
  --user                      Show only user-installed packages
  --system                    Show only system packages
  --info PACKAGE              Show detailed information about a package
  --bloat                     Find unused optional dependencies (bloat)
  --unused                    Find unused or orphaned packages
  --outdated                  List all outdated packages
  --history PACKAGE           Show version history and updates of a package
  --versions PACKAGE          Show all available versions of a package with risk levels

SERVICE COMMANDS:
  --services                  Show status of services related to packages
  --service-info SERVICE      Show detailed info about a service
  --service-logs SERVICE      Show logs of a service

MIRROR COMMANDS:
  --show-mirrors              Show current mirrors with ping & last update
  --update-mirrors            Update to fastest mirrors
  --revert-mirrors            Revert mirrors to previous backup
  --backup-mirrors            Create a manual backup of the current mirror list

KERNEL COMMANDS:
  --cleanup-kernels           Automatically remove old kernels
  --backup-kernel             Backup the current running kernel to /boot/pactool/backup

SECURITY COMMANDS:
  --upgrade-security          Upgrade only security-related packages (Debian/Ubuntu)
  --vuln-check PACKAGE        Check known CVEs (vulnerabilities) for a package
  --deep-search               Use with --vuln-check for detailed exploit tree and history
  --view-security-packages    View all installed security packages with details

---

Tips and Tricks

• Use --user to list only user-installed packages.
• Combine --list with --sort for quick overviews of package size and type.
• Backup mirrors before performing major upgrades.
• Use --why to track down unnecessary package dependencies.
• Create a shell alias:

alias pt='python3 /path/to/pactool.py'

---

Troubleshooting

Q: Pactool says reflector is missing.
A: Install it with:

sudo pacman -S reflector

For Debian-based systems, use:

sudo apt install netselect-apt

Q: Permission errors on mirror updates?
A: Run with sudo or sudo -E.

Q: Kernel backup fails with missing vmlinuz?
A: Ensure the kernel image path matches /boot/vmlinuz-*. Adjust kernals.py if needed.

---

Contributing

We welcome contributions from developers, testers, and Linux enthusiasts. Steps:

1. Fork this repository.
2. Create a feature branch.
3. Commit your changes.
4. Submit a Pull Request.

Ideas for contributions:

• Add support for other package managers (e.g., zypper, dnf).
• Improve mirror ranking algorithms.
• Write tests for advanced features.

---

License

Copyright 2025 LinuxUtils

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

View License