Skip to main content

Installation

This page installs the pie CLI. After this, see Initial setup to create a config and run your first prompt.

Install​

On Linux and macOS:

curl -fsSL https://pie-project.org/install.sh | bash

On Windows (PowerShell):

irm https://pie-project.org/install.ps1 | iex

The installer downloads a release archive and installs pie into ~/.local/bin on Unix or %LOCALAPPDATA%\Pie\bin on Windows. It picks a build for your platform automatically:

  • Linux (x86_64 or arm64) with an NVIDIA GPU: cuda13.0 (driver 580+). CUDA device code is compiled at runtime by NVRTC and cached on disk, so one build per architecture serves every compute capability.
  • Linux x86_64 without an NVIDIA GPU: vulkan or wgpu. Linux arm64: vulkan.
  • macOS Apple Silicon: metal (Apple GPU via Metal), or wgpu.
  • Windows (x86_64): cuda with an NVIDIA GPU, otherwise vulkan.

Intel Macs have no prebuilt binary — build from source (below); the default build links the dummy (mock) driver.

If pie is not on your PATH, add the install directory:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Linux CUDA prerequisites​

The CUDA flavors require a matching NVIDIA driver, the CUDA toolkit runtime libraries, and NCCL on the host. On Debian or Ubuntu with NVIDIA's package repositories configured:

sudo apt install libnccl2 libnccl-dev

If pie doctor reports missing libraries on a CUDA build, install the CUDA 13.x runtime.

Verify​

pie --version
pie doctor

pie doctor checks platform readiness, lists compiled-in drivers, probes GPU visibility, and confirms that ~/.pie/config.toml and any subprocess driver venvs resolve.

Optional: inferlet authoring​

The release installer provides the pie engine CLI. To scaffold, build, and publish inferlets, install Bakery from PyPI:

pip install pie-bakery

This provides the standalone bakery command and the Python package used by pie new / pie build.

Advanced installation​

Most users do not need anything in this section.

Choose a build manually​

Override the auto-picked flavor with PIE_FLAVOR:

curl -fsSL https://pie-project.org/install.sh | PIE_FLAVOR=metal bash      # macOS Apple Silicon
curl -fsSL https://pie-project.org/install.sh | PIE_FLAVOR=cuda13.0 bash
curl -fsSL https://pie-project.org/install.sh | PIE_FLAVOR=vulkan bash

On Windows:

$env:PIE_FLAVOR = "cuda"; irm https://pie-project.org/install.ps1 | iex
PlatformAvailable flavors
Linux x86_64cuda13.0, vulkan, wgpu
Linux aarch64cuda13.0, vulkan
macOS Apple Siliconmetal, wgpu
Windows x86_64cuda, vulkan

Intel Macs are not supported.

The cuda* flavors (Linux and Windows) bundle the native cuda_native driver — the recommended path on NVIDIA GPUs. macOS metal bundles the metal driver for Apple Silicon. vulkan runs on any Vulkan 1.2 device; wgpu is the portable fallback. There is no CPU build.

Override the install directory​

curl -fsSL https://pie-project.org/install.sh | PIE_INSTALL_DIR=/usr/local/bin bash

Install a specific version​

curl -fsSL https://pie-project.org/install.sh | PIE_VERSION=0.4.0 bash

Install from source​

For development:

git clone https://github.com/pie-project/pie.git
cd pie

# Default build: no real backend feature → the always-linked `dummy` (mock) driver.
cargo install --path worker

# Include the embedded CUDA driver (Linux/Windows, NVIDIA).
CUDACXX=/usr/local/cuda/bin/nvcc \
  cargo install --path worker --features driver-cuda

# Include the embedded Metal driver (macOS Apple Silicon).
cargo install --path worker --features driver-metal

Re-run pie doctor after building to confirm which drivers are compiled in.

Windows CMD​

curl -fsSL https://pie-project.org/install.cmd -o install.cmd && install.cmd && del install.cmd

Next steps​