pkgx: Run Anything

pkgx is a compact, stand-alone binary — a 4 MiB toolkit capable of running almost anything you throw at it. It’s designed to “just work,” letting you focus on building world-changing ideas instead of wrestling with toolchains, dependencies, or fragile environment setups. This post takes you through what pkgx does, how to use it, and why it sits at the intersection of reliability, portability, and developer freedom.

Introduction: The Promise of a Tiny Yet Mighty Runner

pkgx aims to be a universal runner: a single binary that can launch programs, languages, and tools without polluting your host system.
The project emphasizes lean packaging, enabling you to craft robust builds and experiments without the overhead of traditional language ecosystems.

Images and branding

Banner image at the top. It visually communicates the spirit of pkgx as a compact, capable tool for modern development workflows.

Quickstart: Getting Started with pkgx

A straightforward installation path exists for most environments:
macOS or Linux via Homebrew: brew install pkgx
Direct install via curl: curl https://pkgx.sh | sh
Windows users on PowerShell: irm https://pkgx.sh | iex (noting that Windows support is experimental and currently limited to a subset of packages)
The goal of these steps is to install pkgx without altering the wider system, preserving your existing setup while giving you a new, dependable way to run tools.
A practical demonstration shows you can run commands that would normally fail if the tool weren’t present, and you’ll observe that nothing invasive is installed globally:
Example: deno command not found: deno followed by pkgx deno, which allows Deno to run in a controlled, ephemeral context.

Run Any Version of Anything: Flexible Version Pinning

One of pkgx’s core strengths is the ability to run any version of a given tool:
Example: pkgx node@14 --version returns Node.js v14.21.3
Example: pkgx python@2 --version returns Python 2.7.18
This capability makes it easy to test, build, and run across multiple versions without juggling local installations or global PATH changes.
You can specify language runtimes and tools with exact versions to reproduce builds, reproduce bugs, and validate compatibility across environments.

Run Anywhere: Cross-Platform Support and Dependence Awareness

Supported platforms include:
macOS (>= 11), 64-bit Intel and Apple Silicon
Linux with glibc >= 2.28
Windows (experimental native support; broader Linux compatibility via WSL2)
Docker environments (there is a ready-to-use image with pkgx installed)
Essential libraries and runtime requirements:
libgcc (often provided by the GCC distribution)
libatomic.so.1 (often part of libgcc)
libdl.so.2, libm.so.6, libpthread.so.0 (from glibc)
libc.so.6 (glibc)
ld-linux-x86-64.so.2 (kernel-provided)
The packaging approach emphasizes that libgcc is usually a separate package, and sometimes libatomic is standalone rather than bundled with gcc. The aim is to keep pkgx lean while still enabling broad compatibility, so users don’t need to transplant entire toolchains into their systems.

Running in Docker and Containerized Environments

A pkgx-provided Docker image makes it easy to test and run a wide array of tools and versions in isolated containers:
Example: docker run -it pkgxdev/pkgx
Inside the container, you can run node@16 and see the Node.js welcome message
You can run other versions directly:
Example: docker run pkgxdev/pkgx [email protected] --version
Integrating pkgx into Dockerfiles is straightforward:
FROM pkgxdev/pkgx
RUN pkgx [email protected]
You can also use pkgx in any image to bootstrap a quick environment, such as:
Dockerfile: FROM ubuntu RUN curl https://pkgx.sh | sh RUN pkgx [email protected] -m http.server 8000
For CI/CD, pkgx is designed to be used in pipelines:
YAML example: uses: pkgxdev/setup@v4 - run: pkgx shellcheck
Commands to invoke scripts and checks can be embedded directly in CI definitions

Scripting with pkgx: Declarative, Reproducible Automation

Scripting is a powerful and central use case for pkgx. It enables you to orchestrate tools without permanently installing them.
A representative script (illustrative) could demonstrate how you load multiple tools and chain commands:
Shebang example shows how to load tools with a +pkg prefix, bringing in the necessary tooling without polluting the system
The script can include steps like formatting, version checks, and repository operations
Advanced usage demonstrates the breadth of ecosystems you can tap into:
uv to run Python scripts with PyPI dependencies
pkgx to load uv and a specific Python version
A small Python snippet uses requests to fetch data from a public API and pretty-prints results
Mash: A companion tool to pkgx that focuses on scripting discovery and dependency resolution
Mash is designed to let scripts declare their dependencies in a concise, script-friendly language
Notably, dependencies for scripts loaded through pkgx aren’t installed globally; they’re downloaded to ~./pkgx during execution, leaving the wider system untouched

pkgo: Package…GO! Making Complex Tools Easy to Access

pkgo is a packaging interface intended to simplify using powerful tools that traditionally require long, manual installation procedures.
The idea is to make tools like Stable Diffusion WebUI as approachable as a single command, thanks to pkgx’s packaging and runtime capabilities.

Recursive Run: Cross-L ecosystem Invocations

pkgx shines at running tools from different language ecosystems without leaving your shell:
Example: pkgx uvx cowsay "Run Python (PyPI) programs with uvx"
Or: pkgx bunx cowsay "Run JavaScript (NPM) programs tools with bunx" (akin to npx)
This recursive run capability enables you to chain tools across ecosystems, bringing together the strengths of multiple languages in a single, coherent workflow.

The Ecosystem: A Composable Primitive for Development Tooling

pkgx is more than a static tool; it’s a composable primitive designed to underpin an ecosystem of utilities and workflows.
Core components:
dev: A system that uses pkgx and pkgm (or shellcode) to create virtual environments tailored to project requirements
- Example: cd my-rust-proj && ls Cargo.toml src/ my-rust-proj
- Running dev ensures the project can be built with the exact toolchain and dependencies
pkgm: A packaging mechanism that installs pkgx packages to /usr/local alongside the base pkgx
Mash: A scripting-centric package manager for scripts
pkgo: A user-friendly wrapper to access tools with long and painful installation instructions
The idea is that the ecosystem enables reproducible, portable, and scalable toolchains that live alongside your projects without polluting host systems.

Migration Notes: Moving from pkgx v1 to v2 and Beyond

Shellcode: The scope of pkgx has been tightened; shellcode is no longer part of pkgx. The dev tool now handles the dynamic loading of dependencies in a separate workflow.
Migration steps:
- pkgx pkgx^1 deintegrate
- pkgx dev integrate
env +foo: If you were using an environment flag like env +git, you’re encouraged to switch to mash-like tooling for dependency and environment management, or achieve the same effect via a safe eval pattern:
Example: eval "$(pkgx +git)"
When using eval, consider shell options to control export scope (set -a and set +a)
pkgx install: A dedicated path now exists for installation of pkgx packages to /usr/local/, with a lean shim option for those who preferred the earlier shims
Example shim: a minimal wrapper script that forwards to pkgx

Contributing: How to Get Involved

The project encourages contributors to start with the dev workflow to ensure Rust-based components and tooling are available locally
To add packages, consult the pantry README
For hacking on the pkgx runtime itself, clone the repository and run cargo build
Hydrate.rs is a critical optimization target; it’s highlighted as a place where performance improvements can yield the most benefit
Pre-PR linting helps preserve code quality:
cargo fmt --all --check
cargo clippy --all-features
pkgx npx markdownlint --config .github/markdownlint.yml --fix .

Support, Community, and Contact Points

The pkgx project maintains a friendly, open community where you can ask questions, request features, or discuss ideas:
Discord: https://discord.gg/rNwNUY83XS
GitHub discussions: https://github.com/pkgxdev/discussions
Documentation and references:
Docs and guides: https://docs.pkgx.sh
Scripts, install paths, and developer guides are available in the docs portal, with specific sections for scripts and editors
Helpful references and external resources:
The project’s scripts and tools have associated pages and repositories:
- Mash: https://github.com/pkgxdev/mash
- Dev: https://github.com/pkgxdev/dev
- PKGO: https://github.com/pkgxdev/pkgo
Stable Diffusion WebUI reference: https://github.com/AUTOMATIC1111/stable-diffusion-webui
TeaRank badge and related signals: a comic-style badge source at tea.xyz

Closing Thoughts: The World Through pkgx

pkgx represents a design philosophy for modern development tooling: keep things small, predictable, and portable, yet powerful enough to orchestrate complex workflows.
By decoupling tool installation from your host system, you gain reproducibility, shareable environments, and safer experimentation.
The ecosystem around pkgx — including dev, pkgm, mash, pkgo, and the broader script-oriented tooling — enables you to compose, reuse, and scale your automation with a consistent, minimal surface area.
If you’re curious about what you can run, the web listing at pkgx.dev/pkgs offers a glimpse into the expansive universe of possibilities, while the CLI’s query mode lets you explore without leaving the shell:
pkgx -Q to list all runnable tools
pkgx -Q | grep git- to discover git-related extensions
The journey with pkgx is not just about running binaries; it’s about building a portable, resilient toolchain that travels with your projects — from local development to CI/CD to edge deployments.

Images included from the input

Banner: A banner visual at the top communicates pkgx’s compact strength
Optional badge visuals are referenced in the input and can be included to enrich the post (e.g., a coverage or teaRank emblem) to reflect the project’s ecosystem signals

If you’re exploring how to simplify tool management, increase reproducibility, and accelerate your development workflows, pkgx offers a compelling approach. Its emphasis on lean, portable packaging, cross-language compatibility, and a modular ecosystem makes it worth a deeper dive. Whether you’re a seasoned engineer chasing robust automation or a researcher aiming for reproducible experiments, pkgx invites you to run anything, anywhere, with confidence.