Every developer environment eventually degrades into an unmaintainable graveyard of version managers, symlinks, and broken global dependencies. We stack nvm, pyenv, and asdf on top of our base OS, cross our fingers, and hope an upstream path collision does not nuke our morning build. The host operating system pays the price for our tooling requirements. pkgx approaches this architectural failure from first principles.

Weighing in at a compact 4 MiB standalone binary, pkgx bypasses traditional installation rituals. It executes any utility at any arbitrary version instantly without polluting your global namespace, keeping your machine pristine while delivering exact dependency execution on demand.

Bootstrap: Zero-Friction Installation

Bootstrapping pkgx onto a machine requires no complex multi-step pipelines. Choose the mechanism suited to your environment:

Via Homebrew:

bash
brew install pkgx

Via the universal shell installer:

bash
curl https://pkgx.sh | sh

For Windows 10+ environments (experimental native support with a focused package set):

powershell
irm https://pkgx.sh | iex

If you require a direct non-Homebrew binary setup on macOS, documentation is available at docs.pkgx.sh/installing-w/out-brew.

Architectural Superpowers

True Ephemeral Execution Without Host Contamination

The standard approach to one-off CLI tools is fundamentally broken: you install a package, use it once, and leave it lingering in /usr/local/bin forever. pkgx introduces isolated, on-the-fly execution.

Observe how it handles a local runtime request:

bash
$ deno
command not found: deno

$ pkgx deno
Deno 2.1.4
>
^D

$ deno
command not found: deno

The runtime executes cleanly. Your base system remains untouched. Nothing leaks into the global namespace. Under the hood, pkgx downloads, validates, and caches artifacts inside ~/.pkgx, completely isolated from system search paths.

Arbitrary Version Pinning Without Runtime Shims

Traditional version managers rely on fragile shell shims and manual environment swapping. With pkgx, arbitrary version execution is a first-class citizen.

Need to spin up deprecated runtimes or test against a strict version constraint? Simply declare the target:

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

$ pkgx python@2 --version
Python 2.7.18

No pre-installation steps. No shims to rehash. No global state alterations.

Cross-Platform Matrix and Execution Targets

The binary is engineered for extreme portability across contemporary computing architectures:

Platform	Minimum Requirements & Architecture	Implementation Details
macOS	>= 11 (Apple Silicon & 64-bit Intel)	Native binary execution
Linux	glibc >= 2.28 (x86_64 & arm64)	Requires libatomic.so.1, libdl.so.2, libm.so.6, libgcc_s.so.1, libpthread.so.0, libc.so.6, ld-linux-x86-64.so.2
Windows	Windows 10+	Native experimental tier (limited package set)
WSL2	Matches Linux specifications	Full runtime compatibility
Docker	Multi-arch base image	Official container: pkgxdev/pkgx

For containerized environments, invoke the official Docker image directly to execute versions dynamically:

bash
$ docker run pkgxdev/pkgx node@21.1 --version
v21.1.0

You can bake it straight into production Dockerfile manifests or inject it into standard distributions:

dockerfile
FROM pkgxdev/pkgx
RUN pkgx deno@1.35 task start

Or deploy it inside a standard base image:

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

Deep Integration: Workflows and Systems

Lean CI/CD Pipelines

Container build times and runner disk usage explode when CI runs must configure heavyweight toolchains. pkgx streamlines workflow automation by fetching exact dependencies at runtime.

For GitHub Actions workflows:

yaml
- uses: pkgxdev/setup@v4
- run: pkgx shellcheck

For generic CI/CD runners:

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

Self-Contained Shebang Scripting

One of the most potent capabilities of pkgx is contextual dependency injection through shebang declarations. You can bind specific toolchains directly to executable scripts without forcing the host system to maintain them.

bash
#! /usr/bin/env -S pkgx +git python@3.12
# python 3.12 executes the script and git is provisioned on PATH for the duration

In this mode, Python 3.12 runs the script while git is automatically placed on PATH exclusively for the lifecycle of that specific process.

This model integrates directly with modern ecosystem-specific runners like uv:

bash
#! /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])

The script runs with its full dependency graph intact. Zero artifacts are permanently installed on the host system. For teams that want to scale this pattern, mash serves as a dedicated package manager designed explicitly for scripts.

Automated Workspaces with dev

Beyond point execution, pkgx serves as the foundational engine for dev, a tool that auto-detects and provisions project workspaces by parsing repository keyfiles such as Cargo.toml or package.json.

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

Running dev creates a scoped, deterministic environment configured precisely to the requirements of the codebase.

The Extended Ecosystem Architecture

The pkgx ecosystem separates execution, persistence, and complex provisioning into distinct, specialized tools:

• dev: Constructs instant virtual development environments by analyzing keyfiles and wiring toolchains on the fly.
• pkgm: The dedicated manager for permanent system-level installations when persistent paths in /usr/local are strictly necessary. It also generates lightweight shims:

bash
$ pkgm shim git
created shim: ~/.local/bin/git

$ cat ~/.local/bin/git
#! /usr/bin/env -S pkgx -q! git

• pkgo: Designed to eliminate setup complexity for large open-source applications (such as Stable Diffusion WebUI), turning intricate configurations into simple one-command executions.
• Recursive Runner Bridging: Interoperate with existing ecosystem runners without pre-configuring their host runtimes:

bash
pkgx uvx cowsay "Run Python (PyPi) programs with uvx"
pkgx bunx cowsay "Run JavaScript (NPM) programs with bunx"

Catalog Discovery and Package Introspection

You can explore the full runtime index online at pkgx.dev/pkgs or query the catalog directly via the command line:

bash
# Check if a package is available and return its qualified name
$ pkgx -Q git

# List every available package in the registry
$ pkgx -Q

# Filter the global registry for specific extensions or subcommands
$ pkgx -Q | grep git-

Migrating from pkgx^1

Upgrading from pkgx^1 involves distinct structural changes:

• Shellcode Decoupling: Shell hooks have been removed from the core binary. dev is now a standalone tool containing its own shell integration:

  bash
  pkgx pkgx^1 deintegrate
  pkgx dev integrate

• Environment Composition: The legacy env +foo syntax is replaced by evaluating exported statements: eval "$(pkgx +git)". Use set -a and set +a to export variables as needed.
• Permanent Installations: The pkgx install command has been moved to pkgm to govern /usr/local/ installations explicitly.

Contributing to the Core Engine

The pkgx project is completely open source and built with Rust. You can provision your development environment directly with dev, inspect the pantry README to add packages, or dive into the core codebase.

The repository's primary execution and resolution hot path lives in hydrate.rs.

Before opening a pull request, run the standard validation suite:

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

Join the community on Discord or participate in GitHub Discussions to track development and contribute upstream. By isolating toolchains into deterministic runtime environments, pkgx removes the traditional overhead of package management while keeping your host system completely clean.