Skip to main content

Opinionated wrapper around docker

Project description

An opinionated wrapper around the docker-py API that lets you use YAML to define images and run tasks.

See for the full documentation.


Just use pip:

$ pip install docker-harpoon


Before Harpoon can be used, it must be configured. Configuration is obtained from the following locations in the following order of precedence:

  • Provided –harpoon-config value

  • HARPOON_CONFIG environment variable

  • ./harpoon.yml

Further, you can also define user-wide settings in your home directory at ~/.harpoonrc.yml. For example if you want the “dark” theme for the logging:


term_colors: dark

The contents of the harpoon config has only one mandatory option, images. This must be a dictionary of image_alias to image_options:


      - FROM ubuntu:14.04
      - RUN apt-get update && apt-get -y install caca-utils
      - CMD cacafire

A rough overview of all the options available can be found at


Once harpoon is installed, there will be a new program called harpoon.

When you call harpoon without any arguments it will print out the tasks you have available.

Unless you don’t have a config file, in which case it’ll complain you have no configuration file.

Once you have a valid configuration file and have chosen a task you wish to invoke, you may use the --task cli option to invoke that task:

$ harpoon --task <task>

Most tasks will also require you to specify an image to work with:

$ harpoon --task <task> --image <image_alias>

Simpler Usage

To save typing --task and --image too much, the first positional argument is treated as task (unless it is prefixed with a dash) and the second positional argument (if also not prefixed with a dash) is taken as the image.


$ harpoon --task run --image my_amazing_image

Is equivalent to:

$ harpoon run my_amazing_image



Install testing deps and run the helpful script:

$ pip install -e .
$ pip install -e ".[tests]"
$ ./
$ ./

Or use tox:

$ pip install tox
$ tox

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

docker-harpoon-0.17.0.tar.gz (66.0 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page