pkgx
is a 4 MiB, standalone binary that can run anything.
[!INFO] You just want your shit to work and we want that too. We pride ourselves on packaging things as well as possible because we want you to change the world with what you build upon the best base we can give you.
brew install pkgx || curl https://pkgx.sh | sh
# Windows 10+
irm https://pkgx.sh | iex
# ^^ we only have limited packages so far
$ deno
command not found: deno
$ pkgx deno
Deno 2.1.4
> ^D
$ deno
command not found: deno
# ^^ nothing was installed; your wider system is untouched
$ pkgx node@14 --version
Node.js v14.21.3
$ pkgx python@2 --version
Python 2.7.18
macOS
- macOS >= 11
- 64 bit Intel & Apple Silicon
Linux
- glibc >=2.28 repology
x86_64
&arm64
[!TIP]
We have gone to good lengths to make
pkgx
(and the packages it installs) work with almost nothing else installed, making it ideal for tiny containers.
Windows
- Experimental Windows native support (limited packages)
- WSL2 (everything Linux supports)
Docker
We provide an image with pkgx
in it:
$ pkgx docker run -it pkgxdev/pkgx
(docker) $ pkgx node@16
Welcome to Node.js v16.20.1.
Type ".help" for more information.
>
You can use this image to try out (pretty much) any version of any program:
$ docker run pkgxdev/pkgx [email protected] --version
v21.1.0
Or in a Dockerfile
:
FROM pkgxdev/pkgx
RUN pkgx [email protected] task start
Or in any image:
FROM ubuntu
RUN curl https://pkgx.sh | sh
RUN pkgx [email protected] -m http.server 8000
CI/CD
- uses: pkgxdev/setup@v3
- run: pkgx shellcheck
Or in other CI/CD providers:
curl https://pkgx.sh | sh
pkgx shellcheck
Scripts
#!/usr/bin/env -S pkgx +git [email protected]
# python 3.12 runs the script and `git` is available during its execution
Editors
Use dev
; a separate tool that uses the pkgx primitives to
automatically determine and utilize your dependencies based on your project’s
keyfiles.
$ cd myproj
myproj $ dev
+cargo +rust
myproj $ code .
pkgx
is not just a package runner, it’s a composable primitive that can be
used to build a whole ecosystem of tools.
dev
uses pkgx
and shellcode to create “virtual environments” consisting of
the specific versions of tools and their dependencies you need for your
projects.
$ cd my-rust-proj && ls
Cargo.toml src/
my-rust-proj $ cargo build
command not found: cargo
my-rust-proj $ dev
+rust +cargo
my-rust-proj $ cargo build
Compiling my-rust-proj v0.1.0
#…
pkgm
installs pkgx
packages to /usr/local
. It installs alongside pkgx
.
A powerful use of pkgx
is scripting, eg. here’s a script to release new
versions to GitHub:
#!/usr/bin/env -S pkgx +gum +gh +npx +git bash>=4 -eo pipefail
gum format "# determining new version"
versions="$(git tag | grep '^v[0-9]\+\.[0-9]\+\.[0-9]\+')"
v_latest="$(npx -- semver --include-prerelease $versions | tail -n1)"
v_new=$(npx -- semver bump $v_latest --increment $1)
gum format "# releasing v$v_new"
gh release create \
$v_new \
--title "$v_new Released 🎉" \
--generate-notes \
--notes-start-tag=v$v_latest
Above you can see how we “loaded” the shebang with +pkg
syntax to bring in all
the tools we needed.
We have pretty advanced versions of the above script, eg teaBASE
There’s tools for just about every language ecosystem so you can import
dependencies. For example, here we use uv
to run a python script with pypi
dependencies, and pkgx to load both uv
and a specific python version:
#!/usr/bin/env -S pkgx [email protected] uv run
# /// script
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests
from rich.pretty import pprint
resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
Tip
We love scripting with pkgx
so much that we made a whole package manager for
scripts to show the world what is possible when the whole open source
ecosystem is available to your scripts Check it out mash
.
Note
Notably, packages used during your script aren’t installed and don’t pollute
your system and anyone else’s systems either. Don’t be confused— they are
downloaded to ~/.pkgx
but the wider system is not touched.
Some Open Source resists packaging and instead includes long installation
instructions that can be… tedious. pkgo
makes using amazing tools like
“Stable Diffusion WebUI” as easy as typing pkgo
(thanks to pkgx
).
Easily run tools from other language ecosystems:
pkgx uvx cowsay "Run Python (PyPi) programs with `uvx`" # or pipx
pkgx bunx cowsay "Run JavaScript (NPM) programs tools with `bunx`" # or `npx`
docs.pkgx.sh is a comprehensive manual and user guide for the pkgx
suite.
The pkgx
suite has had its scopes tightened. There is no shellcode in pkgx
anymore. Instead dev
is its own separate tool that has its own shellcode.
Migrate your shell configuration with:
pkgx pkgx^1 deintegrate
pkgx dev integrate
If you used this, let us know, we can make a mash script to provide this
functionality again. You can achieve the same result as eg. env +git
with:
eval "$(pkgx +git)"
Surround the eval
with set -a
and set +a
if you need the environment
exported.
We now provide pkgm
which fully installs pkgx
packages to
/usr/local/
.
If you miss the leanness of pkgx^1 “shims then use pkgm shim
.
$ pkgm shim git
created shim: ~/.local/bin/git
$ cat ~/.local/bin/git
#!/usr/bin/env -S pkgx -q! git
We recommend using dev
to make rust available.
- To add packages see the pantry README
- To hack on
pkgx
itself; clone it andcargo build
hydrate.rs
is where optimization efforts will bear most fruit
cargo fmt --all --check
cargo clippy --all-features
pkgx npx markdownlint --config .github/markdownlint.yml --fix .
We love a good chinwag.