Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pg83/ix/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the IX repository, building your first package, installing it into a personal realm, and putting that realm on your PATH. By the end you will have a working IX setup and a feel for the core workflow: build → mutate realm → use. No binary installer is involved — IX bootstraps itself from source.
1

Clone the IX repository

IX is distributed as a source repository. Clone it directly from GitHub:
git clone https://github.com/pg83/ix.git
cd ix
The repository contains the IX entrypoint (ix), supporting tools, and the full package set under pkgs/. You will run all IX commands from this directory using the ./ix wrapper.
2

Build a package

Build bin/b64 (a base64 utility) to verify that your environment is functional:
./ix build bin/b64
IX resolves the package’s dependencies, builds them in a hermetic environment, and places the output in the content-addressed store at /ix/store/<hash>-bin-b64/. The build subcommand uses an ephemeral realm and does not modify any persistent realm anchor.
3

Install a package into your user realm

The mut subcommand modifies a realm. If no realm name is given, IX defaults to the realm named after your current username:
./ix mut bin/zstd
This builds bin/zstd (if not already in the store), assembles a new realm that includes it, and updates the anchor link at /ix/realm/$(whoami) to point to that new realm entry. Your previous realm entry remains in the store until garbage collected.
4

Activate the realm in your PATH

Add your user realm’s bin directory to PATH:
export PATH="/ix/realm/$(whoami)/bin:${PATH}"
You can verify the installation immediately:
zstd --version
Add the export line to your shell’s rc file (~/.profile, ~/.bashrc, etc.) to make it permanent.

​
Common First Tasks

The examples below are taken directly from the IX man page and README. Install a Wayland compositor in a named realm: 
./ix mut gui bin/sway
Install Sway with the AMD GPU acceleration driver: 
./ix mut gui bin/sway --mesa_driver=radv
Flags like --mesa_driver=radv can be applied to an entire realm (affecting all packages in it) or to a single package. To set a flag realm-wide: 
./ix mut gui --mesa_driver=radv
To remove a flag (reset to the default software renderer): 
./ix mut system --mesa_driver=-
Add and remove packages in a single operation: 
# Remove sway, add wayfire
./ix mut gui -bin/sway bin/wayfire
Update all packages in a realm (re-resolve and rebuild everything, picking up recipe changes): 
./ix mut gui
Run a tool from the store without installing it permanently: The run subcommand builds an ephemeral realm and executes a command inside it. Use -- to separate the package list from the command to run: 
./ix run zstd -- zstd --help
Inspect realm contents: 
# List all realms
./ix list

# List packages installed in the gui realm
./ix list gui
Remove a realm’s anchor link: 
./ix purge gui

​
Cross-Target Build

IX has first-class (work-in-progress) support for building packages targeting a different OS or ABI than the host. Pass --target=<os>-<arch> to any build or mutation command: 
./ix build bin/b64 --target=freebsd-x86_64
Packages in the bld/ namespace are always built for the host and are excluded from cross-target builds automatically.

​
Debugging Builds

If a build fails, re-run with --setx --verbose to get a detailed shell trace and dependency log: 
./ix build bin/b64 --setx --verbose >/tmp/build.log 2>&1
Build output can be large. Redirect to a file and then inspect the tail for the error.

​
What’s Next

Core Concepts

Understand the content-addressed store, realm anchors, and how IX identifies packages by build-input hash.

Managing Realms

Learn how to create named realms, apply realm-wide flags, list installed packages, and run garbage collection.

CLI Reference

Full reference for every IX subcommand: mut, build, let, run, gc, list, purge, dep, and tool.

Package Development

Anatomy of an ix.sh recipe, the Jinja2 block system, template inheritance, fetch hashes, and the pkgs/die/ build framework.

Build docs developers (and LLMs) love

Get started for freeTalk to us