Repository: pkgxdev/pkgx

Stars: 9721

README.md Copy Chapter

!pkgx.dev

pkgx is a 4 MiB, standalone binary that can _run anything_.

[![coverage][]][coveralls] [![teaRank][]](https://tea.xyz)

on packaging things as well as possible because we want you to change the

world with what you build and not have to worry about the rest.

 

Quickstart Copy Section

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

$ pkgx node@14 --version
Node.js v14.21.3
$ pkgx python@2 --version
Python 2.7.18

Run Anywhere Copy Chapter

<details><summary>macOS</summary><br>

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

</details>
<details><summary>Linux</summary><br>

- glibc >=2.28 repology
- libgcc
- x86_64 & arm64

Specifically these libs are needed:

> - libatomic.so.1 (provided by libgcc)

- libdl.so.2 (provided by glibc)

- libm.so.6 (provided by glibc)

- libgcc_s.so.1 (provided by libgcc)

- libpthread.so.0 (provided by glibc)

- libc.so.6 (this _is_ glibc)

- ld-linux-x86-64.so.2 (provided by the kernel, you get this for free)

> libgcc is built as part of the GCC distribution and usually is split out

into multiple packages by the linux distribution. libgcc is almost always

a separate package, but you may need to install gcc in its entirety.

Sometimes libatomic is also a separate package rather than being part of

gcc or libgcc.

</details>
<details><summary>Windows</summary><br>

- Experimental Windows native support (limited packages)
- WSL2 (everything Linux supports)

</details>
<details><summary>Docker</summary><br>

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

</details>
<details><summary>CI/CD</summary><br>

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

Or in other CI/CD providers:

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

</details>
<details><summary>Scripts</summary><br>

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

</details>
<details><summary>Editors</summary><br>

Use [dev][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 .

</details>

What Can pkgx Run? pkgx Run?')" title="Copy chapter prompt for LLMs"> Copy Chapter

We have a web based package listing at
pkgx.dev/pkgs.

From the CLI you can use query mode:

$ pkgx -Q git
^^ can you run git? (outputs the fully qualified project name)
$ pkgx -Q
^^ list everything that could be run
$ pkgx -Q | grep git-
^^ what git extensions does pkgx provide?

&nbsp;

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')" title="Copy chapter prompt for LLMs"> Copy Chapter

dev uses pkgx and pkgm (or 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][dev]

pkgm pkgm')" title="Copy chapter prompt for LLMs"> Copy Chapter

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

[github.com/pkgxdev/pkgm][pkgm]

Scripting Copy Chapter

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][teaBASE-release-script]

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

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

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!) pkgo (Package…GO!)')" title="Copy chapter prompt for LLMs"> Copy Chapter

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

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

&nbsp;

Further Reading

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

&nbsp;

Migrating from pkgx^1

Shellcode Copy Chapter

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 env +foo')" title="Copy chapter prompt for LLMs"> Copy Chapter

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 pkgx install')" title="Copy chapter prompt for LLMs"> Copy Chapter

We now provide [pkgm][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

&nbsp;

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

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

&nbsp;

Chat / Support / Questions

We love a good chinwag.

- Discord
- [github.com/orgs/pkgxdev/discussions][discussions]

[docs]: https://docs.pkgx.sh
[pantry README]: ../../../pantry#contributing
[discussions]: ../../discussions
[docs.pkgx.sh/scripts]: https://docs.pkgx.sh/scripts
[docs.pkgx.sh/installing-w/out-brew]: https://docs.pkgx.sh/installing-w/out-brew
[dev]: https://github.com/pkgxdev/dev
[pkgm]: https://github.com/pkgxdev/pkgm
[teaBASE-release-script]: https://github.com/teaxyz/teaBASE/blob/main/Scripts/publish-release.sh
[hydrate.rs]: crates/lib/src/hydrate.rs
[mash]: https://github.com/pkgxdev/mash
[dev]: https://github.com/pkgxdev/dev
[pkgo]: https://github.com/pkgxdev/pkgo
[“Stable Diffusion WebUI”]: https://github.com/AUTOMATIC1111/stable-diffusion-webui
[coverage]: https://coveralls.io/repos/github/pkgxdev/pkgx/badge.svg?branch=main
[coveralls]: https://coveralls.io/github/pkgxdev/pkgx?branch=main
[teaRank]: https://img.shields.io/endpoint?url=https%3A%2F%2Fchai.tea.xyz%2Fv1%2FgetTeaRankBadge%3FprojectId%3D79e9363b-862c-43e0-841d-4d4eaad1fc95