Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

SCUBA Build Status PyPI Gitter

Simple Container-Utilizing Build Apparatus

SCUBA is a simple tool that makes it easier to use Docker containers in everyday development. It is intended to be used by developers in 'make' or 'scons' based build environments, where the entire build environment is encapsulated in a Docker container.

Its purpose is to lower the barrier to using Docker for everyday builds. SCUBA keeps you from having to remember a complex docker run command line, and turns this

$ docker run -it --rm -v $(pwd):/build:z -w /build -u $(id -u):$(id -g) gcc:5.1 make myprogram

into this:

$ scuba make myprogram


Install via pip

Scuba is hosted at PyPI.

To install:

$ sudo pip install scuba

To install with argcomplete (for bash completion support):

$ sudo pip install scuba[argcomplete]

To uninstall:

$ sudo pip uninstall scuba

Install from source

Scuba can be built from source on Linux only (due to the fact that scubainit must be compiled):

  1. Run make to build scubainit
  2. Run ./ to run the unit tests
  3. Run sudo python install to install scuba
  4. Run ./ to test the installed version of scuba

If musl-libc is installed, it can be used to reduce the size of scubainit, by overriding the CC environment variable in step 1:

CC=/usr/local/musl/bin/musl-gcc make

Note that installing from source in this manner can lead to an installation with increased startup times for Scbua. See #71 for more details. This can be remedied by forcing a wheel to be installed, as such:

$ export CC=/usr/local/musl/bin/musl-gcc    # (optional)
$ sudo pip install wheel
$ python bdist_wheel
$ sudo pip install dist/scuba-<version>-py3-none-any.whl


Configuration is done using a YAML file named .scuba.yml in the root directory of your project. It is expected that .scuba.yml be checked in to version control. Full documentation on .scuba.yml can be found in doc/, and specific examples can be found in the example directory.

An example .scuba.yml file might look like this:

image: gcc:5.1

  build: make -j4

In this example, scuba build foo would execute make -j4 foo in a gcc:5.1 container.


Scuba defines the following environment variables in the container:

  • SCUBA_ROOT the root of the scuba working directory mount; the directory where .scuba.yml was found.

Bash Completion

Scuba supports command-line completion using the argcomplete package. Per the argcomplete README, command-line completion can be activated by:

  • Running eval "$(register-python-argcomplete scuba)" manually to enable completion in the current shell instance
  • Adding eval "$(register-python-argcomplete scuba)" to ~/.bash_completion
  • Running activate-global-python-argcomplete --user to install the script ~/.bash_completion.d/python-argcomplete.
    • NOTE: The generated file must be sourced, which is not the default behavior. Adding the following code block to ~/.bash_completion is one possible solution.
      for bcfile in ~/.bash_completion.d/*; do
          [ -f "$bcfile" ] && . "$bcfile"
  • Running activate-global-python-argcomplete as root (or sudo) to use argcomplete for all users


This software is released under the MIT License.

You can’t perform that action at this time.