{"id":13537373,"url":"https://github.com/bpkg/bpkg","last_synced_at":"2025-10-19T13:56:03.037Z","repository":{"id":17304248,"uuid":"20074785","full_name":"bpkg/bpkg","owner":"bpkg","description":"Lightweight bash package manager","archived":false,"fork":false,"pushed_at":"2024-06-18T23:26:56.000Z","size":289,"stargazers_count":1927,"open_issues_count":38,"forks_count":100,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-05-15T09:05:21.632Z","etag":null,"topics":["bash","bash-script","bash-scripting","bpkg","installer","installer-script","package-management","package-manager","shell","shell-script","shell-scripts"],"latest_commit_sha":null,"homepage":"http://www.bpkg.sh","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bpkg.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2014-05-22T19:52:27.000Z","updated_at":"2025-05-13T11:32:58.000Z","dependencies_parsed_at":"2023-12-25T21:43:02.716Z","dependency_job_id":"7cd256bc-17b0-479d-825d-c7b6583727ce","html_url":"https://github.com/bpkg/bpkg","commit_stats":null,"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpkg%2Fbpkg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpkg%2Fbpkg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpkg%2Fbpkg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpkg%2Fbpkg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bpkg","download_url":"https://codeload.github.com/bpkg/bpkg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310513,"owners_count":22049468,"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","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":["bash","bash-script","bash-scripting","bpkg","installer","installer-script","package-management","package-manager","shell","shell-script","shell-scripts"],"created_at":"2024-08-01T09:00:58.242Z","updated_at":"2025-10-19T13:56:02.977Z","avatar_url":"https://github.com/bpkg.png","language":"Shell","readme":"# bpkg [![Build Status](https://travis-ci.org/bpkg/bpkg.svg?branch=master)](https://travis-ci.org/bpkg/bpkg) [![Backers on Open Collective](https://opencollective.com/bpkg/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/bpkg/sponsors/badge.svg)](#sponsors) \n\n_JavaScript has npm, Ruby has Gems, Python has pip and now Shell has bpkg!_\n\n`bpkg` is a lightweight bash package manager. It takes care of fetching the shell scripts, installing them appropriately, setting the execution permission and more.\n\nYou can install shell scripts globally (on `${PREFIX:-/usr/local/bin}`) or use them on a _per-project basis_ (on `${BPKG_DEPS:-./deps/}`), as a lazy-man \"copy and paste\".\n\n\u003c!-- BEGIN-MARKDOWN-TOC --\u003e\n* [Install](#install)\n    * [0. Dependencies](#0-dependencies)\n    * [1. Install script](#1-install-script)\n    * [2. clib](#2-clib)\n    * [3. Source Code](#3-source-code)\n* [Usage](#usage)\n    * [Installing packages](#installing-packages)\n    * [Packages With Dependencies](#packages-with-dependencies)\n    * [Running packages with `bpkg`](#running-packages-with-bpkg)\n    * [Retrieving package info](#retrieving-package-info)\n* [Package details](#package-details)\n* [bpkg.json](#bpkgjson)\n    * [name](#name)\n    * [version (optional)](#version-optional)\n    * [description](#description)\n    * [global](#global)\n    * [install](#install-1)\n    * [scripts](#scripts)\n    * [files (optional)](#files-optional)\n    * [dependencies (optional)](#dependencies-optional)\n    * [dependencies-dev (optional)](#dependencies-dev-optional)\n    * [commands (optional)](#commands-optional)\n    * [commands-description (optional)](#commands-description-optional)\n* [Packaging best practices](#packaging-best-practices)\n    * [Package exports](#package-exports)\n* [Sponsors](#sponsors)\n    * [Contributors](#contributors)\n    * [Backers](#backers)\n* [License](#license)\n\u003c!-- END-MARKDOWN-TOC --\u003e\n\n## Install\n\nYou can install `bpkg` from three distinct ways:\n\n### 0. Dependencies\n\n* [curl](http://curl.haxx.se/)\n* [coreutils](https://www.gnu.org/software/coreutils/)\n\n### 1. Install script\n\nOur install script is the simplest way. It takes care of everything for you, placing `bpkg` and related scripts on `/usr/local/bin`.\n\nYou can install `bpkg` with the [`get.bpkg.sh`](https://get.bpkg.sh) endpoint:\n\n```sh\ncurl -Lo - get.bpkg.sh | bash\n```\n\nOr optionally paste the following on your shell and you're good to go:\n\n```sh\ncurl -Lo- \"https://raw.githubusercontent.com/bpkg/bpkg/master/setup.sh\" | bash\n```\n\nor by tag/version\n\n```sh\ncurl -Lo- \"https://raw.githubusercontent.com/bpkg/bpkg/1.0.15/setup.sh\" | bash\n```\n\n### 2. clib\n\n[clib][clib] is a package manager for C projects. If you already have it, installing `bpkg` is a simple matter of:\n\n```sh\nclib install bpkg/bpkg\n```\n\n### 3. Source Code\n\nTo directly install `bpkg` from its source code you have to clone its repository and run the `setup.sh` script:\n\n```sh\ngit clone https://github.com/bpkg/bpkg.git\ncd bpkg\n./setup.sh                             # Will install bpkg in $HOME/.local/bin\nsudo ./setup.sh                        # Will install bpkg in /usr/local/bin.\nPREFIX=/my/custom/directory ./setup.sh # Will install bpkg in a custom directory.\n```\n\n## Usage\n\nYou use `bpkg` by simply sending commands, pretty much like `npm` or `pip`.\n\n### Installing packages\n\nPackages can either be global (on `${PREFIX:-/usr/local/bin}` if installed as root or\n `${PREFIX:-$HOME/.local/bin}` otherwize) or local (under `${BPKG_DEPS:-./deps}`).\n\nFor example, here's a **global install for the current user** of the [term package][term]:\n\n```sh\nbpkg install term -g\nterm\n```\n\nAnd the same package as a **local install**:\n\n```sh\nbpkg install term\n./deps/term/term.sh\n```\n\nAfter a local install the `term.sh` script is copied as `term` to the `deps/bin` directory, you can add this directory to the `PATH` with\n\n```sh\nexport PATH=$PATH:/path_to_bkpg/deps/bin\n```\n\nAs a bonus, you can specify a **specific version**:\n\n```sh\nbpkg install jwerle/suggest.sh@0.0.1 -g\n```\n\n**Note:** to do that the packages **must be tagged releases** on the repository.\n\nYou can also *install packages without a `bpkg.json` (or `package.json`)*.\nAs long as there is a `Makefile` in the repository it will try to invoke `make install` as long as the `-g` or `--global` flags are set when invoking `bpkg install`.\n\nFor example you could install [git-standup](https://github.com/stephenmathieson/git-standup) with an omitted `bpkg.json` (or `package.json`) because of the `Makefile` and the `install` target found in it.\n\n```sh\nbpkg install stephenmathieson/git-standup -g\n\n    warn: bpkg.json doesn`t exist\n    warn: package.json doesn`t exist\n    warn: Trying `make install'...\n    info: install: `make install'\ncp -f git-standup /usr/local/bin\n```\n\n### Packages With Dependencies\n\nYou can install a packages dependencies with the `bpkg getdeps` command. These will recursively install in `deps/` sub-folders to resolve all dependencies.\n\n_Note: There is no protection against circular dependencies, so be careful!_\n\n### Running packages with `bpkg`\n\nYou can run a package script with `bpkg run` which will install your\npackage globally and execute it as a command\n\n### Retrieving package info\n\nAfter installing a package, you can obtain info from it using `bpkg`.\n\nSupposing you're on the root of a package directory, the following commands show that package metadata:\n\n```sh\n# Asking for single information\nbpkg package name\n \"bpkg\"\nbpkg package version\n \"0.0.5\"\n# Dumping all the metadata\nbpkg package\n[\"name\"]        \"bpkg\"\n[\"version\"]     \"0.0.5\"\n[\"description\"] \"Lightweight bash package manager\"\n[\"global\"]      true\n[\"install\"]     \"make install\"\n```\n\n## Package details\n\nHere we lay down some info on the structure of a package.\n\n## bpkg.json\n\nEvery package must have a file called `bpkg.json` (for backward-compatibility\n`package.json` can also be used); it specifies package metadata on the [JSON format][json].\n\nHere's an example of a well-formed `bpkg.json`:\n\n```json\n{\n  \"name\": \"term\",\n  \"version\": \"0.0.1\",\n  \"description\": \"Terminal utility functions\",\n  \"scripts\": [ \"term.sh\" ],\n  \"install\": \"make install\"\n}\n```\n\nAll fields are mandatory except when noted.\nHere's a detailed explanation on all fields:\n\n### name\n\nThe `name` attribute is required as it is used to tell `bpkg` where to put it in the `deps/` directory in you project.\n\n```json\n  \"name\": \"my-script\"\n```\n\n### version (optional)\n\nThe `version` attribute is not required but can be useful. It should correspond to the version that is associated with the installed package.\n\n```json\n  \"version\": \"0.0.1\"\n```\n\n### description\n\nA human readable description of what the package offers for functionality.\n\n```json\n  \"description\": \"This script makes monkeys jump out of your keyboard\"\n```\n\n### global\n\nIndicates that the package is only intended to be install as a script. This allows the omission of the `-g` or `--global` flag during installation.\n\n```json\n  \"global\": \"true\"\n```\n\n### install\n\nShell script used to invoke in the install script. This is required if the `global` attribute is set to `true` or if the `-g` or `--global` flags are provided.\n\n```json\n  \"install\": \"make install\"\n```\n\n### scripts\n\nThis is an array of scripts that will be installed into a project.\n\n```json\n  \"scripts\": [\"script.sh\"]\n```\n\n### files (optional)\n\nThis is an array of non-script files that will be installed into a project.\n\n```json\n  \"files\": [\"bar.txt\", \"foo.txt\"]\n```\n\n### dependencies (optional)\n\nThis is a hash of dependencies. The keys are the package names, and the values are the version specifiers. If you want the latest code use `'master'` in the version specifier. Otherwise, use a tagged release identifier. This works the same as `bpkg install`'s package/version specifiers.\n\n```json\n  \"dependencies\": {\n    \"term\": \"0.0.1\"\n  }\n```\n\n### dependencies-dev (optional)\n\nThis is a hash of dependencies only needed during development.  Like the `dependencies` array, the keys are the package names, and the values are the version specifiers; `'master'` or a tagged release can be used as the identifier. These development dependencies are installed by adding the `-d` or `--dev` flags to the `bpkg install` command.\n\n```json\n  \"dependencies-dev\": {\n    \"term\": \"0.0.1\"\n  }\n```\n\n### commands (optional)\n\nThis is a hash of commands. The keys are the names of the commands and the values are the commands to execute in a shell.  The commands can be called from the command line with `bpkg run` followed by the command name.\n\n```json\n  \"commands\": {\n    \"say-hello\": \"echo \\\"Hello $1\\\"\"\n  }\n```\n\nThe commands are run with `eval`, which runs the command as if on the command line. Commands can contain environment variables, and supports [shell features] (including *[special parameters]* and *[shell expansions]*). Passed parameters (on the command line after the command name) can be accessed in the command by using `$@` or `$1`.\n\n```bash\n$ bpkg run say-hello \"Bash Package Manager\"\nHello Bash Package Manager\n```\n\n### commands-description (optional)\n\nThis is a hash of descriptions for configured commands.  The keys are the names of the commands and the values are the descriptions for the specified commands.  The command descriptions can be listed on the command line by providing the `-l` or `--list` flags after the `bpkg run` command.\n\n```json\n  \"commands-description\": {\n    \"say-hello\": \"Output hello to provided name (ex: bpkg run say-hello John)\"\n  }\n```\n\n## Packaging best practices\n\nThese are guidelines that we strongly encourage developers to follow.\n\n### Package exports\n\nIt's nice to have a bash package that can be used in the terminal and also be invoked as a command line function. To achieve this the exporting of your functionality *should* follow this pattern:\n\n```sh\nif [[ ${BASH_SOURCE[0]} != \"$0\" ]]; then\n  export -f my_script\nelse\n  my_script \"${@}\"\n  exit $?\nfi\n```\n\nThis allows a user to `source` your script or invoke as a script.\n\n```sh\n# Running as a script\n./my_script.sh some args --blah\n# Sourcing the script\nsource my_script.sh\nmy_script some more args --blah\n```\n\n## Sponsors\n\n**bpkg** wouldn't be where it is today without the help of its authors, contributors, and sponsors:\n\n* [@socketsupply](https://github.com/socketsupply) ([socketsupply.co](https://socketsupply.co))\n* [@little-core-labs](https://github.com/little-core-labs)\n* [@littlstar](https://github.com/littlstar) ([littlstar.com](https://littlstar.com))\n* [@spotify](https://github.com/spotify) ([spotify.com](https://spotify.com))\n\nSupport this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/bpkg#sponsor)]\n\n\u003ca href=\"https://opencollective.com/bpkg/sponsor/0/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/sponsor/0/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/bpkg/sponsor/1/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/sponsor/1/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/bpkg/sponsor/2/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/sponsor/2/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/bpkg/sponsor/3/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/sponsor/3/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/bpkg/sponsor/4/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/sponsor/4/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/bpkg/sponsor/5/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/sponsor/5/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/bpkg/sponsor/6/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/sponsor/6/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/bpkg/sponsor/7/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/sponsor/7/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/bpkg/sponsor/8/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/sponsor/8/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/bpkg/sponsor/9/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/sponsor/9/avatar.svg\"\u003e\u003c/a\u003e\n\n### Contributors\n\nThis project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].\n\u003ca href=\"graphs/contributors\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/contributors.svg?width=890\u0026button=false\" /\u003e\u003c/a\u003e\n\n### Backers\n\nThank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/bpkg#backer)]\n\n\u003ca href=\"https://opencollective.com/bpkg#backers\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/bpkg/backers.svg?width=890\"\u003e\u003c/a\u003e\n\n## License\n\n`bpkg` is released under the **MIT license**.\n\nSee file `LICENSE` for a more detailed description of its terms.\n\n[clib]: https://github.com/clibs/clib\n[term]: https://github.com/bpkg/term\n[json]: http://json.org/example\n[shell features]: https://www.gnu.org/software/bash/manual/html_node/Basic-Shell-Features.html\n[special parameters]: https://www.gnu.org/software/bash/manual/html_node/Special-Parameters.html\n[shell expansions]: https://www.gnu.org/software/bash/manual/html_node/Shell-Expansions.html\n","funding_links":["https://opencollective.com/bpkg"],"categories":["Shell","bash","Shell Package Management","Package Managers and Tools"],"sub_categories":["Reusable Things"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpkg%2Fbpkg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbpkg%2Fbpkg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpkg%2Fbpkg/lists"}