Install the Postman CLI

Install the Postman CLI by following the instructions for your operating system below.

The Postman CLI supports the same system requirements as the Postman desktop app. For a complete list of requirements, see Install and update Postman.

Install with the Postman desktop app

If you use the Postman desktop app, you can install the Postman CLI from the app. Click Help > Postman CLI and Plugins > Install Postman CLI. When the installation finishes, open a new terminal window and run postman -v to check it.

The app installs the Postman CLI without asking for administrator permissions:

• macOS and Linux — The app installs the postman binary to /usr/local/bin if that directory is writable without sudo, and otherwise to $HOME/.local/bin. If the directory isn’t on your PATH, the app adds it to your shell startup file, such as ~/.zshrc or ~/.bashrc.
• Windows — The app installs the postman binary to %USERPROFILE%\AppData\Local\Microsoft\WindowsApps.

If the Postman CLI is already on your PATH, the app leaves it in place and doesn’t update it. To update the Postman CLI, see Update your Postman CLI installation.

The Postman desktop app doesn’t install the Postman CLI automatically. If the app installed the Postman CLI for you automatically before, you can remove it from the app. To learn more, see Uninstall the Postman CLI.

The app includes its own copy of the Postman CLI for its built-in terminal. That copy runs only in the built-in terminal. To use the Postman CLI from your own terminal or from coding agents, install it with one of the methods on this page.

npm installation for Windows, macOS, and Linux

If you have Node.js and npm installed on your system, you can run the following command. This will download and install the Postman CLI binary, making the postman command available in your terminal.

npm install -g postman-cli

Windows installation

Run the following command to install the Postman CLI for Windows. This will download and run an install script. The script creates a %USERPROFILE%\AppData\Local\Microsoft\WindowsApps directory if it doesn’t exist yet, then installs the postman binary there.

powershell -NoP -NonI -c "irm https://dl-cli.pstmn.io/install/win64.ps1 | iex"

macOS, Linux, and Windows Subsystem for Linux (WSL) installation

Run the following command to install the Postman CLI on systems running macOS, Linux, or Windows Subsystem for Linux (WSL). This will download and run a unified install script that detects your OS and architecture. Where the script installs the postman binary depends on your system. If the /usr/local directory is writable without sudo, as it is for the root user, in most containers, and on hosted CI runners, the script installs to /usr/local/bin. Otherwise, it installs to $HOME/.local/bin, creating the directory if needed. Either way, the script doesn’t prompt for sudo.

The script makes two exceptions to these locations. If a Postman CLI that the script installed earlier is on your PATH, the script updates it in place. If /usr/local/bin/postman is a symlink, such as one that npm or Homebrew created, the script installs to $HOME/.local/bin instead of writing through the symlink.

curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh

At the install location, the script writes the new binary over whatever bin/postman is already there. When that path is a symlink, such as one left by an earlier install to a different location, the script replaces the symlink itself and leaves the file it pointed to unchanged.

Whichever location the script installs to, the Postman CLI is also reachable at $HOME/.local/bin/postman. When the script installs the binary somewhere else, it adds a symlink at that path pointing to the binary, so callers such as the Postman desktop app can check one fixed path. If a binary or symlink is already there, the script leaves it in place.

If the installed binary doesn’t print a version, the script ends with an error.

/usr/local/bin is on the default PATH of most systems, so a /usr/local install makes the postman binary available in later CI steps and Docker RUN lines, which don’t read shell startup files. To keep a user-local install even when /usr/local is writable, set POSTMAN_CLI_SYSTEM_INSTALL=0.

Pass --prefix <directory> to install to <directory>/bin/postman instead, or --system to install system-wide (to /usr/local when you don’t also pass --prefix). A system install is the only case that prompts for sudo, and only when the target directory isn’t writable without it. If the target isn’t writable and you didn’t pass --system, the installer fails before downloading anything, with a message naming these flags, instead of escalating to sudo without asking.

# Install to a custom location (installs to /opt/postman/bin/postman)
curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh -s -- --prefix /opt/postman
# Install system-wide
curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh -s -- --system

For scripted installs, each flag can also be set as an environment variable instead: POSTMAN_CLI_INSTALL_PREFIX, POSTMAN_CLI_SYSTEM_INSTALL=1 (or =0 to keep a user-local install), and POSTMAN_CLI_NO_MODIFY_PATH=1 for --no-modify-path, which skips editing your shell startup file and prints the export PATH=... line to add yourself instead.

For CI environments, the default install needs no extra setup because hosted runners make /usr/local writable, and /usr/local/bin is already on PATH. If the install falls back to $HOME/.local, add $HOME/.local/bin to your PATH environment variable to make the postman binary available in later steps of your CI workflow (on GitHub Actions, echo "$HOME/.local/bin" >> "$GITHUB_PATH").

Agent instruction files

The install scripts for Windows and for macOS, Linux, and WSL add a short note to your coding agents’ global instructions, so your agents know the Postman CLI is installed. The note goes in Claude Code’s ~/.claude/CLAUDE.md and in Codex’s ~/.codex/AGENTS.override.md, or ~/.codex/AGENTS.md if there’s no override file. The scripts add the note only if that agent’s configuration directory exists, and they honor the CLAUDE_CONFIG_DIR and CODEX_HOME environment variables.

The note sits between <!-- postman-cli:installation:start --> and <!-- postman-cli:installation:end --> markers. The scripts don’t change anything else in these files. When the Postman desktop app installs the Postman CLI, it doesn’t add this note.

Update your Postman CLI installation

To update your Postman CLI installation to the latest version, run the same command you used to install it, or run postman update. Both overwrite the earlier version in place. The postman update command performs the installation into the same location the running binary already uses, so a --system or --prefix install updates there instead of installing a second copy elsewhere. For details about the latest changes and features, see the Postman CLI release notes.

Uninstall the Postman CLI

If you installed the Postman CLI with npm, you can uninstall it with the following command:

npm uninstall -g postman-cli

If you installed the Postman CLI with the Postman desktop app or an install script, you can uninstall it from the app. Click Help > Postman CLI and Plugins > Uninstall Postman CLI, then click Uninstall. The app removes the Postman CLI and the files the installer added, including the PATH entry in your shell startup file and the note in your agent instruction files. It doesn’t remove a Postman CLI that you installed with npm or with the --prefix option.

To uninstall a Postman CLI that an install script installed without using the app, delete the following files. The script lists the ones it added when it finishes installing:

• The postman binary (postman.exe on Windows) and the lib directory next to it. On Windows, they’re in %USERPROFILE%\AppData\Local\Microsoft\WindowsApps by default. On macOS, Linux, and WSL, they’re in /usr/local/bin or $HOME/.local/bin, depending on where the script installed them.
• On macOS, Linux, and WSL, the $HOME/.local/bin/postman symlink, if the script added one, and the postman.1 man page in /usr/local/share/man/man1 or $HOME/.local/share/man/man1.
• The line marked # Added by the Postman CLI installer in your shell startup file, and the line after it, if the script added them.
• The block between the postman-cli:installation markers in your agent instruction files.

Coding agent setup

After installing the Postman CLI, you use the postman init command to set up an AI-ready API project in your local repository. In a single step, it creates the Postman Native Git project structure, adopts an existing API specification if your repository has one, and installs agent skills under postman/skills/, with one SKILL.md per skill and a root AGENTS.md that points agents to them.

For more information, see postman init

Troubleshooting

If you’ve installed the Postman CLI using both npm and the curl-based script, your system may have two copies of the binary. Which binary is active depends on the order of directories in your PATH environment variable.

To check which binary is active, do the following:

1. Run one of the following commands, depending on your system:

   • For macOS, Linux, or WSL, run which postman.

   • For Windows, run where postman.

2. Run postman --version.

If you have two copies of the binary in your PATH environment variable, you can resolve the conflict by uninstalling one of the binaries.