Comment on page

FAQ

How do I run the latest version of pkgx?
pkgx is just another pkg so:
pkgx@latest npx@latest cowsay@latest 'fancy a cuppa?'
Is a valid command, provided you have shell integration.
If you are looking to upgrade the “installed” pkgx version then use brew upgrade pkgx, re-run the installer (it upgrades itself) or repeat your installation method.
A self-upgrade feature is coming soon.
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
​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?
Coming soon.
For now, all packages are encapsulated in individual, versioned folders in ~/.pkgx just like brew.
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​

Last modified 4d ago

FAQ

How do I run the latest version of `pkgx`?

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

How do I “install” pkgs?

What is a package?

A package version I need is unavailable

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

What does `+pkg` syntax do?

How do I list what packages are cached?

A pkg I was expecting is not available

Where do you put pkgs?

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

Will you support other platforms?

How do I add my package to pkgx?

What happened to ”Magic”?

I added a package to the pantry but `pkgx foo` fails

How do I uninstall `pkgx`?

macOS

Non macOS

Caveats

What are the rules for `@` syntax?

Where does `pkgx` store files

What happens if two packages provide the same named program?

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

I have another question