GitHub

FAQ

How do I run the latest version of pkgx?

Typically you want to upgrade pkgx so either:

  1. brew upgrade pkgx; or

  2. curl -LSsf pkgx.sh | sh

[!NOTE] Indeed! Our installer installs and upgrades too.

OTOH, pkgx packages itself so:

pkgx@latest npx@latest cowsay@latest 'fancy a cuppa?'

Is a valid command, provided you have shell integration.

How do I run the latest version of a specific pkg?

Unless otherwise instructed, pkgx executes the latest version of pkgs that are cached. The first time you run a pkg the latest version will be cached, but after that updates will only be fetched if requested.

pkgx deno@latest

For us neophiliacs we have written a [mash] script to check for newer versions of what you have cached and fetch them:

pkgx mash pkgx/cache upgrade

OSS.app can automatically install updates.

How do I “install” pkgs?

To make pkgs available to the wider system use pkgx install.

You can update installed packages with pkgx install foo@latest

What is a package?

A package is:

  • A plain tarball containing a single project for a single platform and architecture compiled from that project’s sources

  • A bundle of metadata (package.yml) from the [pantry]

Relative to some other packaging systems:

  • No scripts are executed post install

  • Packages must work as is from any location provided their deps are installed in parallel (we say our pkgs are “relocatable“)

A package version I need is unavailable

Sorry about that. Open a ticket asking for it and we’ll build it.

I need to pin a pkg to greater than v20.1.3 but less than v21

The commonly used @ syntax would pin the pkg to v20.1.x (@20.1.3).

To provide more control we support the full semantic version range syntax. So for the given example we would use the caret (^):

$ pkgx node^20.1.3 --version
v20.1.5

Which will match node v20.1.3 up to but not including v21.

What does +pkg syntax do?

+pkg syntax is a way to include additional pkgs in your environment. Typing pkgx +deno dumps the environment to the terminal, if you add additional commands then those commands are invoked in that environment.

How do I list what packages are cached?

We have created a [mash] script to list cached packages:

pkgx mash pkgx/cache ls

All packages are encapsulated in individual, versioned folders in ~/.pkgx just like brew so you can just browse them with a file browser.

A pkg I was expecting is not available

Open source is ever moving and somebody needs to keep up with it. You may need to contribute to the pantry.

Where do you put pkgs?

Everything goes in ~/.pkgx. eg. Deno v1.2.3 installs an independent POSIX prefix to ~/.pkgx/deno.land/v1.2.3, thus the deno executable is at ~/.pkgx/deno.land/v1.2.3/bin/deno.

We also install symlinks for majors, minors and latest:

$ cd ~/.pkgx/deno.land
$ ls -la
v*   -> v1.2.3
v1   -> v1.2.3
v1.2 -> v1.2.3

Open source is vast and unregulated, thus we use fully-qualified naming scheme to ensure pkgs can be disambiguated.

Can I bundle ~/.pkgx into my distributable app?

Yes! Our pkgs are relocatable.

Will you support other platforms?

We would love to support all platforms. All that is holding is back from new platforms is expertise. Will you help? Let’s talk.

How do I add my package to pkgx?

You need to add to the pantry.

Eventually we will support describing how to build or obtain distributables for your package via your repo so you can just add a pkgx.yaml and users can use pkgx to use your package automatically.

How should I recommend people install my pkg with pkgx?

$ pkgx your-package --args

You can also recommend our shell one-liner if you like:

sh <(curl https://pkgx.sh) +your-package sh

Will for example install pkgx and your pkg then open a new shell with it available to the environment.

What happened to ”Magic”?

We removed “magic” from pkgx at v1 because it had a number of unsolvable issues. If you want it back however fortunately the shellcode is simple:

function command_not_found_handle {
  pkgx -- "$*"
}
# NOTE in zsh append an `r` ie `command_not_found_handler``

I added a package to the pantry but pkgx foo fails

Try pkgx --sync foo to force a pantry sync. Typically this isn’t needed but this flag can help in confusing situations.

How do I uninstall pkgx?

We’ll provide pkgx uninstall pkgx at some point, for now:

pkgx deintegrate
sudo rm /usr/local/bin/pkgx
rm -rf ~/.pkgx

Then there are a couple platform specific cache/data directories:

macOS

rm -rf "${XDG_CACHE_HOME:-$HOME/Library/Caches}/pkgx"
rm -rf "${XDG_DATA_HOME:-$HOME/Library/Application Support}"/pkgx

Non macOS

rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/pkgx"
rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}"/pkgx

Caveats

Though not a problem unique to pkgx you should note that tools installed with pkgx may have polluted your system during use. Check directories like:

  • ~/.local

  • ~/.gem

  • ~/.npm

  • ~/.node

  • etc.

What are the rules for @ syntax?

The rules for @ are complex, but more human. We convert them to the following semver syntax:

  • @3 → ^3

  • @3.1 → ~3.1

  • @3.1.2 → >=3.1.2<3.1.3

  • @3.1.2.3 → >=3.1.2.3<3.1.3.4

  • etc.

Where does pkgx store files

  • pkgs are cached to ~/.pkgx ($PKGX_DIR overrides)

  • pkg tarballs are cached to

    • ~/Library/Caches/pkgx on Mac

    • ~/.cache/pkgx on *nix

    • %LOCALAPPDATA%/cache/pkgx on Windows

    • ⚠️⚠️$XDG_CACHE_HOME overrides on all platforms

  • runtime data like the [pantry] is stored in:

    • ~/Library/Application Support/pkgx on Mac

    • ~/.local/share/pkgx on *nix

    • %LOCALAPPDATA%/pkgx on Windows

    • ⚠️⚠️ $XDG_DATA_HOME overrides on all platforms

If $XDG_STATE_HOME is set then $XDG_STATE_HOME/pkgx is used for some temporary shellcode state.

What happens if two packages provide the same named program?

We error with a method to disambiguation, eg:

$ yarn
× multiple projects provide: yarn
│ pls be more specific:
│
│     pkgx +classic.yarnpkg.com --internal.use +yarn
│     pkgx +yarnpkg.com --internal.use +yarn
│
╰─➤ https://docs.pkgx.sh/help/ambiguous-pkgspec

How do I see a man page for a pkgx pkg?

man foo won’t work since pkgx pkgs are not “installed”. Thus you have to first create an environment that contains that package before invoking man:

pkgx +foo man foo

This uses pkgx’s man tool. To use the system man:

pkgx +foo -- man foo

I have another question

Support

mash

Last updated