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.

 

Quickstart

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

# Windows 10+
irm https://pkgx.sh | iex
# ^^ we only have limited packages so far

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

• 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

docs.pkgx.sh/scripts

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 .

 

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 [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

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.

pkgo (Package…GO!)

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).

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`

 

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

 

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.

• Discord
• github.com/orgs/pkgxdev/discussions