pkgx 2.2.0

Run anything
pkgx-2.2.0 is not a library.

pkgx.dev

pkgx is a 4 MiB, standalone binary that can run anything.

coverage teaRank

 

Quickstart

brew install pkgx || curl https://pkgx.sh | sh

docs.pkgx.sh/installing-w/out-brew

 

Run Anything

$ 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

Run Any Version of Anything

$ pkgx node@14 --version
Node.js v14.21.3

$ pkgx python@2 --version
Python 2.7.18

Run Anywhere

  • macOS >= 11
  • 64 bit Intel & Apple Silicon

WSL2; x86-64. Native windows is planned.

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 node@21.1 --version
v21.1.0

Or in a Dockerfile:

FROM pkgxdev/pkgx
RUN pkgx deno@1.35 task start

Or in any image:

FROM ubuntu
RUN curl https://pkgx.sh | sh
RUN pkgx python@3.10 -m http.server 8000

- uses: pkgxdev/setup@v3
- run: pkgx shellcheck

Or in other CI/CD providers:

curl https://pkgx.sh | sh
pkgx shellcheck

#!/usr/bin/env -S pkgx +git python@3.12

# python 3.12 runs the script and `git` is available during its execution

docs.pkgx.sh/scripts

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 .

 

The pkgx Ecosystem

pkgx is not just a package runner, it’s a composable primitive that can be used to build a whole ecosystem of tools.

dev

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
#…

github.com/pkgxdev/dev

pkgm

pkgm installs pkgx packages to /usr/local. It installs alongside pkgx.

github.com/pkgxdev/pkgm

Scripting

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 +python@3.11 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]

Mash

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.

Recursive Run

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`

Magic

It can be fun to add magic to your shell:

# add to ~/.zshrc
command_not_found_handler() {
  pkgx -- "$@"
}

Thus if you type gh and it’s not installed pkgx will magically run it as though it was installed all along.

[!NOTE] Bash is the same function but drop the r from the end of the name.

 

Further Reading

docs.pkgx.sh is a comprehensive manual and user guide for the pkgx suite.

 

Migrating from pkgx^1

Shellcode

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

env +foo

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.

pkgx install

We now provide pkgm but if you miss the leanness of “stubs” we provide a mash script to create stubs in /usr/local/bin:

$ pkgx mash pkgx/stub git
created stub: /usr/local/bin/git

$ cat /usr/local/bin/git
#!/bin/sh
exec pkgx git "$@"

 

Contributing

We recommend using dev to make rust available.

  • To add packages see the pantry README
  • To hack on pkgx itself; clone it and cargo build
    • hydrate.rs is where optimization efforts will bear most fruit

Pre-PR Linting

cargo fmt --all --check
cargo clippy --all-features
pkgx npx markdownlint --config .github/markdownlint.yml --fix .

 

Chat / Support / Questions

We love a good chinwag.