Docs 2.4.4 · 4 min read

Installing Apsi on Windows and Linux

Supported systems

After installing, run apsi doctor to check your machine against these targets.

The easy way: the ready-made installers (recommended)

Download: the Windows installer, the Linux installer (ApsiSetup-2.4.4-linux.sh) and the .deb are on apsi.dev/download, each with its SHA-256. When you build Apsi yourself (BUILD.md), all of these files are in the dist/ folder.

What the Windows setup wizard does

1. Shows Preparing Apsi Setup… immediately while it unpacks, then keeps that window on top of other windows until the wizard has finished loading, closes it and opens the wizard in its place.
2. Lets you choose Express (recommended defaults) or Custom (folder, components, optional AI packages, security profile).
3. Installs to %LOCALAPPDATA%\Programs\Apsi — per user, no administrator rights.
4. Adds apsi to your user PATH. Windows that were already open keep the old PATH: open a new terminal (quit VS Code completely) or see TROUBLESHOOTING.md for a command that fixes the current window.
5. Registers .apsi files: the Apsi icon, Run with Apsi (double-click), Edit (VS Code when installed, otherwise Notepad), Test with Apsi, and New → Apsi source file in Explorer's right-click menu.
6. Creates Start-menu entries: Apsi REPL, Examples, Documentation, Uninstall.
7. Adds Apsi to the code editors it finds — VS Code, Cursor, Windsurf, VSCodium, VS Code Insiders, Trae, Sublime Text, Neovim, Vim and Notepad++ — and lists them on the System check page (see EDITORS.md).
8. Registers in Settings → Apps so it can be removed normally. Every change is recorded and undone on uninstall; a failed install rolls back completely.

Unattended install: ApsiSetup-2.4.4-x64.exe --silent [--dir PATH] [--profile strict] [--no-editors] [--with-torch]. Windows older than 10 and 32-bit Windows are not supported.

What the .deb package does

• installs python3-numpy from apt automatically
• creates the /usr/bin/apsi command
• puts the examples and documentation in /usr/share/apsi/examples and /usr/share/apsi/docs

Windows 10 / 11 from source

1. Install Python (if you do not have it)

winget install Python.Python.3.12

Or download it from python.org and tick "Add python.exe to PATH" during setup.

2. Install Apsi

Double-click install\install.bat, or run in PowerShell:

powershell -ExecutionPolicy Bypass -File install\install.ps1

The script:

• finds Python 3.12+ (py -3 first, then python)
• creates a separate virtual environment in %LOCALAPPDATA%\Apsi\venv, so other Pythons on the machine are untouched
• creates the apsi command (%LOCALAPPDATA%\Apsi\bin\apsi.cmd) and adds it to your user PATH, without administrator rights
• sets the console to UTF-8 so symbols such as ✓ ± ² display correctly

Open a new terminal and try:

apsi version
apsi run examples\01_hello.apsi
apsi doctor

Uninstall: powershell -ExecutionPolicy Bypass -File install\install.ps1 -Uninstall

Without installing

pip install numpy
apsi.bat run examples\01_hello.apsi

Windows tips

• Windows Terminal (included with Windows 11) shows Unicode symbols such as ✓ ± ² best
• .apsi files saved by Notepad (UTF-8 with BOM, CRLF line endings) work as they are
• the REPL understands Windows paths directly: cd C:\Users\me\project, run app.apsi, ls
• compiling C for the FFI: examples\native\build.bat works with MSVC (cl) and MinGW-w64 (gcc)
• cload("native/vecmath") finds vecmath.dll on Windows and libvecmath.so on Linux
• shell completion: apsi completion powershell | Out-String | Invoke-Expression (add it to your $PROFILE)

Linux from source

1. Install Python and venv

# Ubuntu / Debian
sudo apt install python3 python3-venv
# Fedora
sudo dnf install python3
# Arch
sudo pacman -S python

2. Install Apsi

sh install/install.sh

• installs into ~/.apsi/venv and creates ~/.local/bin/apsi without sudo
• if ~/.local/bin is not on your PATH yet, the script prints the line to add to ~/.bashrc

Uninstall: sh install/install.sh --uninstall

Without installing

pip install numpy
./apsi.sh run examples/01_hello.apsi

Executable scripts

#!/usr/bin/env apsi

Put this line at the top of a file and chmod +x it to run .apsi files like any other program (a # line is a comment).

Optional extras

Problems after installing

apsi not recognized, no colours in VS Code, needs permission 'python': see TROUBLESHOOTING.md.

Checking the installation

apsi doctor                                   # hardware and operating system
apsi verify                                   # runtime files match the release manifest
apsi test examples tests/apsi --allow-all     # the whole language test suite
python -m unittest discover tests             # the toolchain test suite

If you keep the code on GitHub, .github/workflows/ci.yml runs every test automatically on Windows Server 2022/2025 and Ubuntu 22.04/24.04 with Python 3.12, 3.13 and 3.14.

Found a mistake? Report it · Markdown source