opkg (Open PacKaGe management) is the package manager used by OpenWrt. It is a lightweight IPK-format package manager derived from the original ipkg, designed for resource-constrained embedded Linux systems.
Configuration Files
| File | Purpose |
|---|
/etc/opkg.conf | Main configuration (architecture, signature checking, options) |
/etc/opkg/distfeeds.conf | Official OpenWrt package repositories |
/etc/opkg/customfeeds.conf | User-defined additional repositories |
/etc/opkg/keys/ | Trusted signing keys for signature verification |
Example /etc/opkg/distfeeds.conf
src/gz openwrt_core https://downloads.openwrt.org/releases/23.05.3/targets/ath79/generic/packages
src/gz openwrt_base https://downloads.openwrt.org/releases/23.05.3/packages/mips_24kc/base
src/gz openwrt_luci https://downloads.openwrt.org/releases/23.05.3/packages/mips_24kc/luci
src/gz openwrt_packages https://downloads.openwrt.org/releases/23.05.3/packages/mips_24kc/packages
Full Command Reference
Update and Info
# Refresh the package list from all configured feeds
opkg update
# Show information about a package
opkg info curl
# List all available packages
opkg list
# List installed packages
opkg list-installed
# List packages with available upgrades
opkg list-upgradable
# List files owned by an installed package
opkg files curl
# Find which package owns a file
opkg search /usr/bin/curl
Install and Remove
# Install a package
opkg install curl
# Install a local .ipk file
opkg install /tmp/mypackage_1.0-1_mips_24kc.ipk
# Remove a package
opkg remove curl
# Remove a package and its automatically installed dependencies
opkg remove --autoremove curl
# Download a package without installing it
opkg download curl
Upgrade
# Upgrade a specific package
opkg upgrade curl
# Upgrade all installed packages with available updates
opkg upgrade
opkg upgrade without arguments will attempt to upgrade all packages, which can destabilize a running system. It is generally safer to upgrade individual packages.
Flags and Options
| Flag | Description |
|---|
--nodeps | Skip dependency resolution |
--force-reinstall | Reinstall even if already installed at same version |
--force-overwrite | Overwrite files from other packages |
--force-depends | Install even if dependencies are not met |
--dest <dest> | Install to an alternate destination (e.g., a USB drive) |
--tmp-dir <dir> | Use alternate temp directory |
Cached Package Lists
After opkg update, package lists are cached in:
These are stored in RAM (tmpfs) and are lost on reboot, which is why opkg update must be run again after each reboot before installing packages.
Overlay Filesystem
OpenWrt’s root filesystem uses an OverlayFS layered over a read-only SquashFS base. Packages installed with opkg go to the writable overlay layer at /overlay/upper/.
/rom/ # Read-only SquashFS base (original firmware)
/overlay/ # Writable JFFS2/F2FS overlay
/ # Merged view (OverlayFS)
The amount of space available for opkg packages is limited by the writable overlay partition size, which is typically the remaining flash after the SquashFS image. Check with df -h /overlay.
Adding a Custom Repository
Add a line to /etc/opkg/customfeeds.conf:
src/gz my_feed https://example.com/packages/mips_24kc
opkg update
opkg install mypackage
/etc/opkg.conf:
Disabling signature checking removes a security protection. Only use this for trusted private feeds.
Installing to External Storage
To install packages to a USB drive or SD card instead of the internal overlay:
# Add destination to /etc/opkg.conf:
# dest usb /mnt/usb
opkg install --dest usb curl
LD_LIBRARY_PATH and PATH adjustments, or use of the extroot mechanism.