Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
145 lines (88 sloc) 3.98 KB


The piw-remove script is used to manually remove a version of a package from the system. All builds for the specified version will be forgotten, all files generated by such builds will be deleted, and all logged downloads will be deleted too.

By default, the version removed will not be marked to skip. Hence, after a short while the master is likely to attempt to re-build it. What happens at this point depends on several factors:

  • If the version is still available on PyPI, and the build dependencies on the chosen slave are sufficient, it will (potentially) build successfully and re-appear on the system.
  • If the version has been removed from PyPI (which is a reason to remove it from piwheels), the build will fail. The failed build will be logged in the system and will not be attempted again.


usage: piw-remove [-h] [--version] [-c FILE] [-q] [-v] [-l FILE] [-y] [-s]
                  [--import-queue ADDR]
                  package version


.. program:: piw-remove

.. option:: package

    the name of the package to remove

.. option:: version

    the version of the package to remove

.. option:: -h, --help

    show this help message and exit

.. option:: --version

    show program's version number and exit

.. option:: -c FILE, --configuration FILE

    specify a configuration file to load

.. option:: -q, --quiet

    produce less console output

.. option:: -v, --verbose

    produce more console output

.. option:: -l FILE, --log-file FILE

    log messages to the specified file

.. option:: -y, --yes

    run non-interactively; never prompt during operation

.. option:: -s, --skip

    mark the version to prevent future build attempts

.. option:: --import-queue ADDR

    the address of the queue used by piw-remove (default:
    (ipc:///tmp/piw-import); this should always be an ipc address


The following section documents the protocol used between the importer and the tasks that it talks to in the :doc:`master`. Each protocol operates over a separate queue. All protocols in the piwheels system follow a similar structure:

  1. Each message is a list of Python objects.
  2. The first element in the list is a string indicating the type of message.
  3. Additional elements depend on the type of the message.
  4. A given message type always contains the same number of elements (there are no variable length messages).

Mr Chase

The queue that talks to :ref:`mr-chase` is a ZeroMQ REQ socket, hence the protocol follows a strict request-reply sequence which is illustrated below (see :doc:`importer` for documentation of the IMPORT path):


  1. The utility sends ["REMOVE", package, version, skip]:
    • package is the name of the package to remove.
    • version is the version of the package to remove.
    • skip is True if the version should never be built again, and False otherwise.
  2. If the removal fails (e.g. if the package or version does not exist), the master will send ["ERROR", args, ...].
  3. If the removal is successful, the master replies with ["DONE"].


This utility is typically used in response to a request from a package maintainer to remove a specific build from the system. Either because it has been withdrawn from PyPI itself, or because the presence of a piwheels build is causing issues in and of itself (both circumstances have occurred).

The utility can be run in a batch mode with :option:`--yes` but still requires invoking once per deletion required (you cannot remove multiple versions in a single invocation).

The return code will be 0 if the version was successfully removed. If anything fails, the return code will be non-zero and no files should be deleted (but this cannot be guaranteed in all circumstances).

The utility should only ever be run directly on the master node (opening the import queue to other machines is a potential security risk).