Install
Binary Tarball
We provide a traditional binary tarball based on nix-user-chroot. Note that the tarball requires Linux kernel user namespaces to work.
A list of all released versions of isQ compiler binaries can be seen at https://www.arclightquantum.com/isq-releases/isqc-standalone/.
VERSION=0.2.8
ARCH=x86_64-unknown-linux-gnu
# Create empty directory for isQ installation.
mkdir isqc && cd isqc
# Check if user namespace is supported for your Linux kernel.
# If not, see FAQ below.
unshare --user --pid echo YES
# Download and unpack tarball.
TARBALL=isqc-${VERSION}-${ARCH}.tar.gz
wget https://www.arclightquantum.com/isq-releases/isqc-standalone/${VERSION}/${TARBALL}
wget https://www.arclightquantum.com/isq-releases/isqc-standalone/${VERSION}/${TARBALL}.sha256
sha256sum -c ${TARBALL}.sha256
tar -xvf ${TARBALL}
# Now isQ is here.
./isqc --version
Nix Flake (Recommended)
isQ is built with Nix Flakes, making it super easy to obtain when you have Nix installed:
# Add isQ binary cache to Cachix to prevent building from source.
nix-shell -p cachix --run "cachix use arclight-quantum"
# Enter the environment with isQ installed.
nix shell github:isQ-Team/isQ-Compiler
# Now isQ is placed in $PATH.
isqc --version
Or you may create a project folder pinned to a compiler version.
Docker Container
We provide two Docker images with isQ compiler builtin: one for normal users providing a full Ubuntu environment, and the other for professional Docker users with only binary files necessary for isQ.
# Ubuntu-based Docker image.
docker run -it arclightquantum/isqc:ubuntu-0.0.1 bash
isqc --version # Run in container.
# Binary only Docker image.
docker run --rm -v $(pwd):/workdir arclightquantum/isqc:0.0.1 isqc --version
Frequently Asked Questions
unshare failed and nix-user-chroot cannot be used.
Q:
Error occurs while running unshare:
or error occurs while running isqc:
user@server:~/isqc$ ./isqc
thread 'main' panicked at src/main.rs:124:70:
unshare failed: Sys(EPERM)
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
A:
nix-user-chroot requires unpriviledege user namespaces to work.
- Kernel version must be >=3.8.
- Follow the guides here to enable user namespaces, roughly:
- Make sure
CONFIG_USER_NS=yis set in kernel compile options. - (Suggested for RedHat/CentOS users): make sure
user.max_user_namespacesis not zero by running:
- Make sure
If you still cannot get user namespaces to work (e.g. you're in a container environment), an alternative is to unpack the tarball at the root directory.
binary_path=/usr/bin/isqc # Set your installation path.
# First unpack the tarball.
tar -xvf isqc.tar.gz
# This will move the `nix` folder to the root directory.
# Note: this may conflict with your Nix installation if you already have Nix installed!
cp -r ./nix /
# isqc should be located at path like:
# /nix/store/hps1c4vap5zc8nkdq1yshpqg9mm3aqd2-isqc/bin/isqc
# This path resides in our `isqc` entrypoint.
# The line below extracts the path from our entry-point script.
isqc_path=$(perl -ne 'print "$1\n" if /\s(\/nix\/store\/.*\/bin\/isqc)/' ./isqc)
# Do a traditional installation
echo '#!/usr/bin/env bash' > $binary_path
echo "$isqc_path \"\$@\"" >> $binary_path
chmod +x $binary_path
# Remove the unpacked files.
rm -rf ./isqc ./nix
# Test
isqc --version
AppArmor constraining unprivileged user namespace.
Q:
Unshare succeeded, but error occurs while running isqc:
user@server:~/isqc$ ./isqc --version
thread 'main' panicked at src/main.rs:138:43:
failed to list /nix directory: Os { code: 13, kind: PermissionDenied, message: "Permission denied" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
Kernel dmesg outputs be like:
[ 1804.496798] audit: type=1400 audit(1718885622.496:241): apparmor="AUDIT" operation="userns_create" class="namespace" info="Userns create - transitioning profile" profile="unconfined" pid=5921 comm="nix-user-chroot" requested="userns_create" target="unprivileged_userns"
[ 1804.497103] audit: type=1400 audit(1718885622.496:242): apparmor="DENIED" operation="open" class="file" profile="unprivileged_userns" name="/" pid=5921 comm="nix-user-chroot" requested_mask="r" denied_mask="r" fsuid=1000 ouid=0
This problem is first reported on Ubuntu 24.04.
A:
Default security profiles of some distros using AppArmor has put stricter restrictions on unprivileged user namespaces, including but not limited to:
- Denying capabilities required to mount
/nix. - Denying accessing
/from user namespaces. - Denying mounting.
Details can be seen here: https://gitlab.com/apparmor/apparmor/-/wikis/unprivileged_userns_restriction
The simplest way to fix this is to disable AppArmor restriction on unprivileged user namespaces:
Warning
While the line above provides a hands-on workaround by disabling some functionalities of AppArmor, you may want to rollout finer-grain AppArmor policies if you care about safety.