Installation

Requirements

• macOS, Linux, or Windows (x86_64 or ARM64)
• git for dependency management
• Python 3.10+ (only for pip or from-source installs)

Quick install (recommended)

macOS / Linux:

curl -sSL https://aka.ms/apm-unix | sh

Windows (PowerShell):

irm https://aka.ms/apm-windows | iex

The installer automatically detects your platform (macOS/Linux/Windows, Intel/ARM), downloads the latest binary, and adds apm to your PATH.

Package managers

Homebrew (macOS/Linux):

brew install microsoft/apm/apm

Scoop (Windows):

scoop bucket add apm https://github.com/microsoft/scoop-apm
scoop install apm

pip install

pip install apm-cli

Requires Python 3.10+.

Manual binary install

Download the archive for your platform from GitHub Releases and install manually:

Windows x86_64

# Download and extract the Windows binary
Invoke-WebRequest -Uri https://github.com/microsoft/apm/releases/latest/download/apm-windows-x86_64.zip -OutFile apm-windows-x86_64.zip
Expand-Archive -Path .\apm-windows-x86_64.zip -DestinationPath .

# Copy to a permanent location and add to PATH
$installDir = "$env:LOCALAPPDATA\Programs\apm"
New-Item -ItemType Directory -Force -Path $installDir | Out-Null
Copy-Item -Path .\apm-windows-x86_64\* -Destination $installDir -Recurse -Force
[Environment]::SetEnvironmentVariable("Path", "$installDir;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")

macOS / Linux

# Example: macOS Apple Silicon
curl -L https://github.com/microsoft/apm/releases/latest/download/apm-darwin-arm64.tar.gz | tar -xz
sudo mkdir -p /usr/local/lib/apm
sudo cp -r apm-darwin-arm64/* /usr/local/lib/apm/
sudo ln -sf /usr/local/lib/apm/apm /usr/local/bin/apm

Replace apm-darwin-arm64 with the archive name for your macOS or Linux platform:

Platform	Archive name
macOS Apple Silicon	apm-darwin-arm64
macOS Intel	apm-darwin-x86_64
Linux x86_64	apm-linux-x86_64
Linux ARM64	apm-linux-arm64

From source (contributors)

git clone https://github.com/microsoft/apm.git
cd apm

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create environment and install in development mode
uv venv
uv pip install -e ".[dev]"
source .venv/bin/activate

Build binary from source

To build a standalone binary with PyInstaller:

cd apm  # cloned repo from step above
uv pip install pyinstaller
chmod +x scripts/build-binary.sh
./scripts/build-binary.sh

The output binary is at ./dist/apm-{platform}-{arch}/apm.

Verify installation

apm --version

Troubleshooting

apm: command not found (macOS / Linux)

Ensure /usr/local/bin is in your PATH:

echo $PATH | tr ':' '\n' | grep /usr/local/bin

If missing, add it to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export PATH="/usr/local/bin:$PATH"

Permission denied during install (macOS / Linux)

Use sudo for system-wide installation, or install to a user-writable directory instead:

mkdir -p ~/bin
# then install the binary to ~/bin/apm and add ~/bin to PATH

Authentication errors when installing packages

See Authentication — Troubleshooting for token setup, SSO authorization, and diagnosing auth failures.

File access errors on Windows (antivirus / endpoint protection)

If apm install fails with The process cannot access the file because it is being used by another process, your antivirus or endpoint protection software is likely scanning temp files during installation.

APM retries file operations automatically with exponential backoff to handle transient locks. If the issue persists, set APM_DEBUG=1 to see retry diagnostics:

$env:APM_DEBUG = "1"
apm install <package>

Next steps

See the Quick Start to set up your first project.