Skip to content

apkg installation

apkg is going to provide native distro packages once mature.

For now you need to

and then choose howto install:


apkg needs Python.

apkg 0.5.0 has been tested to work on all Python versions between 3.6 and 3.12.

See apkg Python support for detailed information about supported Python versions.

To install apkg, you need pipx, pip, or other compatible Python package installer.

Further apkg requirements are handled automatically by the installer. They're listed and briefly explained in requirements.txt.

Python modules needed to build apkg docs are listed in doc-requirements.txt.

installer: pipx

pipx is a recommended tool for installing apkg into virtualenv and providing apkg command without disrupting host system.

Install pipx package using distro package manager:

apt install -y pipx
dnf install -y pipx
zypper install -y python-pipx
pacman -Sy python-pipx

If your distro doesn't provide pipx, consult pipx installation docs and/or consider installing pipx using pip:

pip3 install pipx

Ensure pipx scripts path is in your PATH environment variable:

pipx ensurepath

Or add ~/.local/bin to your $PATH manually.

installer: pip

PEP 668 makes it harder to disrupt Externally Managed Python Environments (such as those provided by linux distros) by requiring --break-system-packages flag on pip install.

Even --user installation now requires this flag on modern distros and users are advised to use isolated virtualenvs as not to break their Python environment.

pipx is a recommended tool for installing apkg into virtualenv and providing the apkg command without disrupting host system, see installer: pipx.

As a rule of thumb, if a distro is new enough to complain about PEP 668, it's new enough to run pipx. It's likely to be already packaged in distro repos.

Valid use cases for using pip instead of pipx:

  • installing apkg into virtualenv
  • installing apkg python module for other consumers
  • installing apkg on old/ancient distros without pipx support
  • installing apkg while reusing system python packages

Install pip package using distro package manager:

apt-get install -y python3-pip
dnf install -y python3-pip
zypper install -y python3-pip
pacman -Sy python-pip

install from PyPI

In order to support widest variety of distros and their releases while leveraging latest and greatest python modules, apkg is primarily distributed through Python Package Index (PyPI) using pipx, pip, or other similar tool of your choice.

Install apkg:

pipx install apkg
pip3 install apkg

Install specific apkg version:

pipx install apkg==0.4.2
pip3 install apkg==0.4.2

Upgrade apkg to latest version:

pipx upgrade apkg
pip3 install --upgrade apkg

install from source

Make sure requirements are met.

Install apkg from remote git repo:

pipx install git+
pip3 install git+


This installs the development version of apkg from master branch with unreleased features and fresh bugs.

Get apkg sources:

git clone
cd apkg

You can switch to a particular branch:

git checkout juicy-new-feature

Or checkout a specific version tag:

git checkout v0.4.2

Install apkg from sources:

pipx install .
pip3 install .
# don't use this unless you absolutely must
python3 install

Alternatively, add --editable option to enable editable installation convenient for apkg development:

pipx install --editable .
pip3 install --editable .
# if you were used to do this, use pipx install --editable
python3 develop --user

--editable mode allows to immediately test changes to apkg source code.

With apkg installed, check out packaging guide 📑