Install pkg
On macOS and Linux, one command installs pkg at ~/.local/bin/pkg. It needs no compiler, no mise, and no other package manager:
curl -fsSL https://gotpkg.dev | shRun the command the installer prints last to load the new PATH in this terminal. Then go to Set up a machine: pkg bootstrap restores the mise configuration in your dotfiles, and pkg setup starts fresh.
Before you start
Section titled “Before you start”- macOS or Linux, on an arm64 or x86_64 machine. Windows uses a release archive instead.
curlorwget,tar, andsha256sumorshasum. The installer names whichever is missing.- An ordinary user account. The installer refuses to run as root and never uses
sudo.
Installer options
Section titled “Installer options”Pass options after sh -s --:
curl -fsSL https://gotpkg.dev | sh -s -- --dry-run| Option | Effect |
|---|---|
--version <version> |
Install that released version, such as 0.3.0, instead of the latest |
--no-modify-path |
Leave startup files alone and print the line to add |
--dry-run |
Report the version, platform, destination and files it would change; change nothing |
https://gotpkg.dev/install.sh returns the same script regardless of request headers. Use it for custom HTTP clients or if you override curl’s user agent. To read it before it runs, download it first:
curl -fsSL https://gotpkg.dev/install.sh -o install.shless install.shsh install.sh --dry-runsh install.shThe root serves this website to browsers and sharing crawlers by default. Ordinary curl and wget requests receive the installer unless they explicitly request HTML.
What the installer changes
Section titled “What the installer changes”The script comes from the latest GitHub release, and so do the archive and its SHA256SUMS manifest, so one installation never mixes versions. The installer downloads the archive for your platform, checks it against SHA256SUMS, and only then replaces an older ~/.local/bin/pkg. A failed download leaves the old copy working.
Apart from PATH, below, it changes nothing else. It does not install mise or restore a configuration. It refuses to replace anything at ~/.local/bin/pkg that is not pkg, and it leaves alone the link mise manages once pkg has been handed to mise; pkg update github:gotpkg/pkg updates that one.
Checksums and attestations
Section titled “Checksums and attestations”The checksum catches a corrupted download. It cannot catch a compromised release, because SHA256SUMS comes from that same release. Every release archive also has a build attestation, which you can verify independently with the GitHub CLI:
gh attestation verify <archive> --repo gotpkg/pkgOnce mise manages pkg, mise checks the digest and attestation of each update itself.
PATH and the current terminal
Section titled “PATH and the current terminal”When ~/.local/bin is not on PATH already, the installer adds it at the end of the startup file that every new shell of your login shell ($SHELL) reads:
| Shell | File |
|---|---|
| zsh | ${ZDOTDIR:-$HOME}/.zshenv |
| bash | ~/.bashrc, and ~/.bash_profile if it exists, else ~/.profile |
| fish | ~/.config/fish/conf.d/pkg.fish |
The lines sit in a block pkg owns, so running the installer again adds nothing:
# >>> pkg >>>export PATH="$HOME/.local/bin:$PATH"# <<< pkg <<<In fish the middle line is set -gx PATH "$HOME/.local/bin" $PATH. The installer prints the line for you to add, and edits no file, for any other shell, with --no-modify-path, and when the startup file or a directory between it and your home directory is a link, such as one your dotfiles deploy. It never edits a file in your dotfiles checkout.
An installer cannot change the shell that ran it. So it ends with next steps: first the command that loads the change in this terminal, such as source ~/.zshenv, then pkg bootstrap or pkg setup. A new terminal needs nothing.
To check which pkg your shell runs:
command -v pkgpkg context showcommand -v pkg should print a path ending in .local/bin/pkg. When it prints another path, a different program named pkg comes earlier on your PATH; move ~/.local/bin ahead of it, or run ~/.local/bin/pkg by its full path. pkg context show reads only and works before mise is installed. It reports which pkg is running and who owns it, the mise it found, and the config files pkg would write to.
When the installer fails
Section titled “When the installer fails”The installer’s own errors start with error:, often followed by a hint: that says what to do next. The common failures:
- When GitHub cannot provide the installer, gotpkg.dev answers
502.curlreports the error,shreceives nothing, and nothing on the machine changes. That happens before the first release is published and while GitHub cannot be reached. The releases page lists what is published; until it lists a release, build pkg from source. --versionwith a version that was never released fails to download the archive and points at the releases page.- On Windows, or on a machine that is neither arm64 nor x86_64, the installer names the platform and stops.
Update pkg
Section titled “Update pkg”Until pkg is handed to mise, run the installer again. It replaces the old copy only after the new one is downloaded and checked.
A successful pkg setup or pkg bootstrap hands pkg to mise. From then on pkg outdated lists new pkg releases and pkg update installs them along with everything else. Hand pkg to mise explains what changes on disk.
Other ways to install
Section titled “Other ways to install”Windows
Section titled “Windows”The installer, pkg setup, and pkg bootstrap support macOS and Linux only; on Windows, setup and bootstrap fail with PRECONDITION_FAILED. The package commands still work. Download pkg-x86_64-pc-windows-msvc.zip from a GitHub release, unpack it, put pkg.exe on your PATH, and install mise 2026.11.9 or newer yourself.
With mise
Section titled “With mise”With mise 2026.11.9 or newer already installed, mise use -g github:gotpkg/pkg installs pkg as a mise tool, and pkg update keeps it current.
Build from source
Section titled “Build from source”Building needs Git, Rust 1.100 or newer with Cargo, and no release. The checkout pins Rust 1.100.0 in rust-toolchain.toml, which rustup reads when you build inside it.
git clone https://github.com/gotpkg/pkg.gitcd pkgcargo install --locked --path crates/pkg --root ~/.local--locked builds with the exact dependency versions in Cargo.lock. --root ~/.local puts the binary at ~/.local/bin/pkg, where the installer puts it. Cargo does not change PATH, so add ~/.local/bin yourself with the line above. To update, run git pull and the same cargo install command.
pkg treats this build like the installer’s copy. A successful pkg setup or pkg bootstrap replaces it with a link to mise’s release of pkg, unless that release is older than your build.
Uninstall
Section titled “Uninstall”Once mise manages pkg, pkg remove github:gotpkg/pkg removes it like any other tool. A copy from the installer is the single file ~/.local/bin/pkg: delete it, or for a source build run cargo uninstall pkg --root ~/.local. The # >>> pkg >>> block stays in your startup file until you delete it. Your mise config and everything pkg installed stay as they are.
The README and Setting up a machine own these instructions.