{"id":13425113,"url":"https://github.com/whalebrew/whalebrew","last_synced_at":"2025-12-15T22:50:43.093Z","repository":{"id":37493344,"uuid":"79717956","full_name":"whalebrew/whalebrew","owner":"whalebrew","description":"Homebrew, but with Docker images","archived":false,"fork":false,"pushed_at":"2025-02-05T21:07:30.000Z","size":541,"stargazers_count":4222,"open_issues_count":32,"forks_count":109,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-12-02T07:55:07.983Z","etag":null,"topics":["docker","homebrew","package-manager","whalebrew"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whalebrew.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-22T13:00:22.000Z","updated_at":"2025-11-24T08:16:09.000Z","dependencies_parsed_at":"2023-10-03T03:16:16.049Z","dependency_job_id":"cd8361ba-1221-4328-9404-76440eeff9ad","html_url":"https://github.com/whalebrew/whalebrew","commit_stats":{"total_commits":217,"total_committers":25,"mean_commits":8.68,"dds":0.6543778801843319,"last_synced_commit":"e65bf47e714c341e7879ea310383089b17615683"},"previous_names":["bfirsh/whalebrew"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/whalebrew/whalebrew","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whalebrew%2Fwhalebrew","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whalebrew%2Fwhalebrew/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whalebrew%2Fwhalebrew/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whalebrew%2Fwhalebrew/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whalebrew","download_url":"https://codeload.github.com/whalebrew/whalebrew/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whalebrew%2Fwhalebrew/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27629559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-10T02:00:12.818Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","homebrew","package-manager","whalebrew"],"created_at":"2024-07-31T00:01:05.171Z","updated_at":"2025-12-15T22:50:43.055Z","avatar_url":"https://github.com/whalebrew.png","language":"Go","funding_links":[],"categories":["Go","package-manager","Command Line and Tooling"],"sub_categories":["Observability"],"readme":"# Whalebrew\n\nWhalebrew creates aliases for Docker images so you can run them as if they were native commands. It's like Homebrew, but with Docker images.\n\nDocker works well for packaging up development environments, but there are lots of tools that aren't tied to a particular project: `awscli` for managing your AWS account, `ffmpeg` for converting video, `wget` for downloading files, and so on. Whalebrew makes those things work with Docker, too.\n\n    $ whalebrew install whalebrew/whalesay\n    Unable to find image 'whalebrew/whalesay' locally\n    Using default tag: latest\n    latest: Pulling from whalebrew/whalesay\n    c60055a51d74: Pull complete\n    755da0cdb7d2: Pull complete\n    969d017f67e6: Pull complete\n    Digest: sha256:5f3a2782b400b2b23774709e0685d65b4493c6cbdb62fff6bbbd2a6bd393845b\n    Status: Downloaded newer image for whalebrew/whalesay:latest\n    🐳  Installed whalebrew/whalesay to /usr/local/bin/whalesay\n    $ whalesay cool\n     ______\n    \u003c cool \u003e\n     ------\n       \\\n        \\\n         \\\n                       ##        .\n                 ## ## ##       ==\n              ## ## ## ##      ===\n          /\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"___/ ===\n     ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ /  ===- ~~~\n          \\______ o          __/\n           \\    \\        __/\n             \\____\\______/\n\n\nWhalebrew can run almost any CLI tool, but it isn't for everything (e.g. where commands must start instantly). It works particularly well for:\n\n* **Complex dependencies.** For example, a Python app that requires C libraries, specific package versions, and other CLI tools that you don't want to clutter up your machine with.\n* **Cross-platform portability.** Package managers tend to be very closely tied to the system they are running on. Whalebrew packages work on any modern version of macOS, Linux, and Windows (coming soon).\n\n## Install\n\nFirst, [install Docker](https://docs.docker.com/engine/installation/). The easiest way to do this on macOS is by installing [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac). You can install Docker Desktop for Mac via Homebrew:\n\n    brew install --cask docker\n\nNext, you can install whalebrew via Homebrew on macOS and Linux:\n\n    brew install whalebrew\n\nIf you're not using Homebrew, you can download a binary and use that:\n\n    curl -L \"https://github.com/whalebrew/whalebrew/releases/download/0.5.0/whalebrew-$(uname -s)-$(uname -m)\" -o /usr/local/bin/whalebrew; chmod +x /usr/local/bin/whalebrew\n\nWindows support is theoretically possible, but not implemented yet.\n\n## Usage\n\n### Install packages\n\n    $ whalebrew install whalebrew/wget\n\nThis will install the image `whalebrew/wget` as `/usr/local/bin/wget`.\n\nThe images in the `whalebrew` organization are a set of images that are known to work well with Whalebrew. You can also install any other images on Docker Hub too, but they may not work well:\n\n    $ whalebrew install bfirsh/ffmpeg\n\n### Find packages\n\n    $ whalebrew search\n    whalebrew/ack\n    whalebrew/awscli\n    whalebrew/docker-cloud\n    whalebrew/ffmpeg\n    whalebrew/gnupg\n    ...\n\n    $ whalebrew search wget\n    whalebrew/wget\n\n### List installed packages\n\n    $ whalebrew list\n    COMMAND     IMAGE\n    ffmpeg      bfirsh/ffmpeg\n    wget        whalebrew/wget\n    whalebrew   whalebrew/whalebrew\n    whalesay    whalebrew/whalesay\n\n### Uninstall packages\n\n    $ whalebrew uninstall wget\n\n### Upgrade packages\n\nTo upgrade a single package, just pull its image:\n\n    $ docker pull whalebrew/wget\n\n## Configuration\n\nWhalebrew reads configuration from either configuration files or environment variables.\n\nThe configuration file location can be specified using the `WHALEBREW_CONFIG_DIR` environment variable and defaults to `~/.whalebrew`.\nThe configuration file must be named `config.yaml`.\n\n|Description|Default (if not specified anywhere)|Format in config files|Format in environment variables|\n|-|-|-|-|\n|The folder containing `config.yaml`|`~/.whalebrew`|N/A|`WHALEBREW_CONFIG_DIR=$HOME/my-config`|\n|The directory to install packages in.|`/usr/local/bin`|`install_path: $HOME/.whalebrew/bin`|`WHALEBREW_INSTALL_PATH=$HOME/.whalebrew/bin`|\n\nOn a general basis, any configuration configured through environment variable will be prioritary compared to values from config files.\n\nFor example, if you have a whalebrew config of `install_path: $HOME/.whalebrew/bin` and an environment variable of `WHALEBREW_INSTALL_PATH=$HOME/.local/bin`, all whalebrew programs will be installed in `$HOME/.local/bin`.\n\n### Configuration path lookup\n\nEnvironment variables have precedence on any other value.\nAs soon as the `WHALEBREW_CONFIG_DIR` it defines the whalebrew installation directory.\nWhen not set, whalebrew considers the first existing file between `~/.whalebrew/config.yaml`, `$XDG_CONFIG_HOME/whalebrew/config.yaml`, and for each `path` in `$XDG_DATA_DIRS`, whether `$path/whalebrew/config.yaml` exists\n\n### Using custom registries\n\n:warning: This feature is currently under development. Any feedback or comments are welcome!\n\nWhalebrew now supports using several registries when searching for packages.\n\nEach repository will be searched sequentially and matches on whalebrew packages will be shown, one per line.\n\nTo enable this feature, ensure you have a configuration file configured as defined [above](#configuration).\n\nYou can make one by running:\n\n```\nmkdir -p ${WHALEBREW_CONFIG_DIR:-~/.whalebrew}\ncat \u003e ${WHALEBREW_CONFIG_DIR:-~/.whalebrew}/config.yaml \u003c\u003cEOF\nregistries:\n- dockerHub:\n    owner: whalebrew\n- dockerHub:\n    owner: my-org\nEOF\n```\n\n:warning: _Note_ that if you provide a single docker hub owner, only this owner will be searched for registries, replacing the default `whalebrew` docker hub organisation.\n\n## How it works\n\nWhalebrew is simple, and leans as much as possible on native Docker features:\n\n* Packages are installed as files in `/usr/local/bin` (or a directory that you configure) with a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) to make them executable. The content of the file is YAML that describes the options to pass to `docker run`, similar to a Compose service. For example:\n\n        #!/usr/bin/env whalebrew\n        image: whalebrew/whalesay\n\n* When a package is executed, Whalebrew will run the specified image with Docker, mount the current working directory in `/workdir`, and pass through all of the arguments.\n\n  To understand what it is doing, you can imagine it as a shell script that looks something like this:\n\n      docker run -it -v \"$(pwd)\":/workdir -w /workdir $IMAGE \"$@\"\n\n## Creating packages\n\nPackages are Docker images published on Docker Hub. The requirements to make them work are:\n\n* They must have the command to be run set as the entrypoint.\n* They must only work with files in `/workdir`.\n\nThat's it. So long as your image is set up to work that way, it'll work with Whalebrew.\n\n### Configuration\n\nThere are some labels you can use to configure how Whalebrew installs your image:\n\n* `io.whalebrew.name`: The name to give the command. Defaults to the name of the image.\n* `io.whalebrew.config.environment`: A list of environment variables to pass into the image from the current environment when the command is run. For example, putting this in your `Dockerfile` will pass through the values of `TERM` and `FOOBAR_NAME` in your shell when the command is run:\n\n        LABEL io.whalebrew.config.environment '[\"TERM\", \"FOOBAR_NAME\"]'\n\n* `io.whalebrew.config.volumes`: A list of volumes to mount when the command is run. For example, putting this in your image's `Dockerfile` will mount `~/.docker` as `/root/.docker` in read-only mode:\n\n        LABEL io.whalebrew.config.volumes '[\"~/.docker:/root/.docker:ro\"]'\n\n* `io.whalebrew.config.ports`: A list of host port to container port mappings to create when the command is run. For example, putting this in your image's `Dockerfile` will map container port 8100 to host port 8000:\n\n        LABEL io.whalebrew.config.ports '[\"8100:8000\"]'\n\n* `io.whalebrew.config.networks`: A list of networks to connect the container to.\n\n        LABEL io.whalebrew.config.networks '[\"host\"]'\n\n* `io.whalebrew.config.working_dir`: The path the working directory should be bound to in the container. For example putting this in your image's `Dockerfile` will ensure the working directory is available in /working_directory in the container\n\n        LABEL io.whalebrew.config.working_dir '/working_directory'\n\n* `io.whalebrew.config.keep_container_user`: Set this variable to true to keep the default container user. When set to true, whalebrew will not run the command as the current user using the docker `-u` flag\n\n        LABEL io.whalebrew.config.keep_container_user 'true'\n\n* `io.whalebrew.config.missing_volumes`: The behaviour to handle missing files or volumes into the container.\n\n        LABEL io.whalebrew.config.missing_volumes 'skip'\n\n  Possible values are\n    * `error` to raise an error when trying to mount a non existing volume *this is the default behaviour*\n    * `skip` to prevent binding the volume\n    * `mount` to mount the volume anyway. This will result in docker [creating a host directory](https://docs.docker.com/engine/reference/commandline/run/#mount-volume--v---read-only)\n\n* `io.whalebrew.required_version`: Specifies the minimum whalebrew version that is required to run the package. Examples: `\u003c1.0.0`, `\u003e0.1.0`, `\u003e0.1.0 \u003c1.0.0`\n\n* `io.whalebrew.config.volumes_from_args`: A list of command line arguments of the program passed at runtime that must be considered and mounted as volumes:\n\n        LABEL io.whalebrew.config.volumes_from_args '[\"-C\", \"--exec-path\"]'\n\n#### Using user environment variables\n\nThe labels `io.whalebrew.config.working_dir`, `io.whalebrew.config.volumes` and `io.whalebrew.config.environment` are expanded with user environment variables when the container is launched.\n\nFor example, if your image has this line in your `Dockerfile`:\n\n        LABEL io.whalebrew.config.working_dir '$PWD'\n\nAt runtime, it will bind your working directory into the container at the same path and set it as the working directory.\n\n#### Using hooks\n\nIn some cases, you might want to execute custom actions, like checking the integrity of the image or adding the whalebrew scripts to your whalebrew repository.\nTo do so, whalebrew will call git-like hooks when handling installation/uninstallation of a package.\nThose hooks must be executable files located in `${WHALEBREW_CONFIG_DIR}/hooks`.\n\nWhalebrew supports the following hooks:\n\n|command \u0026 arguments|description|\n|-|-|\n|`pre-install ${DOCKER_IMAGE} ${EXECUTABLE_NAME}`|This hook is called before installing a package. If it fails, the whole installation process fails|\n|`post-install ${EXECUTABLE_NAME}`|This hook is called after a package is installed. If it fails, the installation process fails, but the package is not uninstalled|\n|`pre-uninstall ${EXECUTABLE_NAME}`|This hook is called before uninstalling a package. If it fails, the whole uninstallation process fails|\n|`post-uninstall ${EXECUTABLE_NAME}`|This hook is called after a package is uninstalled. If it fails, the uninstallation process fails, but the package is not uninstalled|\n\n### Whalebrew images\n\nWe maintain a set of packages which are known to follow these requirements under the `whalebrew` organization on [GitHub](https://github.com/whalebrew) and [Docker Hub](https://hub.docker.com/u/whalebrew/). If you want to add a package to this, open a pull request against [whalebrew-packages](https://github.com/whalebrew/whalebrew-packages).\n\n## Thanks\n\n* Justin Cormack for [the original idea](https://github.com/justincormack/dockercommand-cli) and generally just being very clever.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhalebrew%2Fwhalebrew","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhalebrew%2Fwhalebrew","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhalebrew%2Fwhalebrew/lists"}