Skip to main content

​
Installation

Better PM can be installed via Homebrew (recommended) or npm. After installation, you’ll set up shell integration to enable features like pm cd.

​
System Requirements

  • Operating System: macOS (arm64/x64) or Linux (x64/arm64)
  • Shell: zsh or bash (for shell integration)
  • Node.js: Not required for Homebrew install; v16+ required for npm install

​
Install with Homebrew

Recommended: Homebrew installs a native binary, so shell completions resolve in ~60ms. The npm version uses Node.js and is slightly slower.
Install from the custom tap:
Verify the installation:
You should see version 0.3.3 or later.

​
Install with npm

If you prefer npm or don’t have Homebrew:
Verify the installation:
The npm installation includes optional native binaries for your platform (better-pm-darwin-arm64, better-pm-linux-x64, etc.) to improve performance.

​
Shell Integration

Shell integration is required for pm cd to work properly. The pm activate command outputs shell wrapper functions and completions.
1

Generate shell integration code

Run the activate command for your shell:
This outputs shell code that wraps the pm command and adds completions.
2

Add to your shell profile

Add the following line to your shell configuration file:
You can also add this to ~/.zprofile (zsh) or ~/.bash_profile (bash) if you prefer.
3

Reload your shell

Source your configuration file or restart your terminal:
4

Verify shell integration

Test that pm cd works:
If you’re in a monorepo, this should change to the root directory. If not, it will output the current directory (meaning shell integration isn’t active yet).

​
What the Shell Wrapper Does

The pm activate command generates a shell function that intercepts pm cd commands:
It also sets up completions so you can tab-complete workspace package names after pm cd.

​
Verify Installation

Confirm everything is working:
1

Check version

Should output 0.3.3 or later.
2

Test package manager detection

Navigate to any project with a lockfile and run:
Better PM should detect your package manager automatically.
3

Test completions

In a monorepo, type pm cd and press Tab. You should see your workspace packages listed.

​
Troubleshooting

Shell integration not working? Make sure you:
  1. Added eval "$(pm activate <shell>)" to the correct file (~/.zshrc or ~/.bashrc)
  2. Reloaded your shell with source ~/.zshrc or opened a new terminal
  3. Verified the function is loaded with type pm — you should see a shell function, not just the binary path

​
Permission Issues

If you get EACCES errors with npm global install:
Or configure npm to use a different directory without sudo (see npm docs).

​
Completion Conflicts

If completions don’t work, check for conflicts with other completion systems:

​
Next Steps

Quickstart Guide

Learn the basic commands and try your first workflow