Comment on page
FAQ
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.
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
You can update installed packages with
pkgx install foo@latest
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“)
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.
+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.Coming soon.
For now, all packages are encapsulated in individual, versioned folders in
~/.pkgx
just like brew
.Open source is ever moving and somebody needs to keep up with it. You may need to contribute to the pantry.
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.
Yes! Our pkgs are relocatable.
We would love to support all platforms. All that is holding is back from new platforms is expertise. Will you help? Let’s talk.
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.$ 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.
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``
Try
pkgx --sync foo
to force a pantry sync. Typically this isn’t needed but this flag can help in confusing situations.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:
rm -rf "${XDG_CACHE_HOME:-$HOME/Library/Caches}/pkgx"`
rm -rf "${XDG_DATA_HOME:-$HOME/Library/Application Support}"/pkgx`
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/pkgx"
rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}"/pkgx
@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.
- 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.
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
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
Last modified 4d ago