Installation instructions - Capsize-Games/airunner GitHub Wiki

💽 Installation

🐋 Docker

This is the fastest and recommended way to run AI Runner locally.

  1. First install the NVIDIA Container Toolkit for Docker and make sure you don't forget the Configuring Docker section. This step is crucial as it allows Docker to utilize the GPU on your host machine.
  2. Clone this repo then run setup.sh - this will allow you to run AI Runner scripts locally.
git clone https://github.com/Capsize-Games/airunner.git
cd airunner
sh src/airunner/bin/setup.sh

You will be presented with several options

1) Setup xhost for Docker                       3) Install AI Runner locally (not recommended)
2) Install AI Runner scripts                    4) Quit
  1. Choose option 1
  2. Choose option 2
  3. Choose the "Quit" option.
  4. Start AI Runner with the command airunner-docker airunner

Common issues

xhost is required in order to run the GUI. If you are using a remote server, you may need to run xhost + on your local machine to allow access to the display.

Here are some potential fixes for common issues:

  • If your GUI app inside Docker isn't showing up, make sure you're allowing local Docker containers to access your display with xhost +local:docker. This is safer than using xhost +, which allows all hosts.

  • The container needs to know which display to use. Make sure you're passing the display environment variable using -e DISPLAY=$DISPLAY in your docker run command.

  • Docker containers also need access to the X11 socket. Mount it with -v /tmp/.X11-unix:/tmp/.X11-unix so the container can communicate with your host's X server.

  • If GUI apps still can't connect, try running the container with --net=host. This lets the container use the host network stack, which sometimes resolves display routing issues.

  • Missing GUI libraries inside the container can cause silent failures. You can test basic X11 functionality by installing tools like x11-apps using apt-get update && apt-get install -y x11-apps.

  • If nothing seems to work and you're just testing locally, try running the container with --privileged. This isn't recommended long-term but can help rule out permission-related problems.

  • Ubuntu may default to Wayland instead of X11, which can break X11-based Docker GUIs. Check your session with echo $XDG_SESSION_TYPE. If it returns wayland, log out and choose an X11 session.

  • Some Qt-based apps crash due to shared memory issues. If that happens, add -e QT_X11_NO_MITSHM=1 to your docker run command to disable MIT-SHM.

Docker commands

airunner-docker will run a wrapper script found at src/airunner/bin/docker.sh which will run the AI Runner Docker container and use any arguments you pass to it.

  • airunner-docker airunner - Run AI Runner
  • airunner-docker down - Stop and remove the container
  • airunner-docker build - Build the container
  • airunner-docker - Enter the container shell

Archived instructions

The following instructions are outdated. The preferred method of using AI Runner locally is via Docker. However, if you want to use AI Runner as a library or don't want to use Docker, you will be able to gain valuable insights from the following instructions.

🛠 Using Python 3.10 on Ubuntu 24.04

Ubuntu 24.04 comes with Python 3.12 by default, but AI Runner requires Python 3.10. To install Python 3.10 from Deadsnakes and set it up properly, follow these steps:

sudo apt update && sudo apt upgrade
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install python3.10 python3.10-venv python3.10-distutils python3.10-dev

Ensure that you use python3.10 explicitly when creating your virtual environment:

python3.10 -m venv venv
source venv/bin/activate

AI Runner can be installed and used for development in two ways: via PyPi or from source.

Install CUDA and cuDNN

Prerequisites

  1. Download CUDA 12.5.1 from NVIDIA
  2. Download and install cuDNN 9
  3. Set up your environment variables:
# CUDA & cuDNN - system-level config
export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python3.10/site-packages/PySide6/Qt/lib:/usr/lib/x86_64-linux-gnu:$CUDA_HOME/lib64:$CUDA_HOME/extras/CUPTI/lib64

🎧 PyPi Installation

Setting Up a Virtual Environment (Recommended)

To keep your dependencies isolated and prevent conflicts, it is recommended to use a virtual environment.

Create and activate a virtual environment:

Windows:

python -m venv venv
venv\Scripts\activate

Linux/macOS:

python3.10 -m venv venv
source venv/bin/activate

Install Prerequisites

Before installing AI Runner, install the required PyTorch packages:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

If your card uses Blackwell architecture (50xx cards) install the nightly version of PyTorch with CUDA 12.8 support:

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128

These versions are working for me

  • torch 2.8.0.dev20250419+cu128
  • torchao 0.11.0.dev20250420+cu126
  • torchaudio 2.6.0.dev20250419+cu128
  • torchvision 0.22.0.dev20250419+cu128

Install AI Runner

Windows:

pip install airunner

Linux:

pip install airunner[all_dev]

Selective Installation

AI Runner provides optional extras that allow you to install only the necessary dependencies based on your use case. You can install these selectively using:

pip install airunner[gui,linux,art,llm,llm_weather,tts]

For development, you can install AI Runner with editable mode and the dev requirements:

pip install -e .[gui,linux,dev,art,llm,llm_weather,tts]

Available Extras:

  • gui - Installs PySide6 for the graphical user interface
  • linux - Installs Linux-specific dependencies like faiss-gpu and tensorrt
  • dev - Installs development tools like pytest and python-dotenv
  • art - Installs dependencies for Stable Diffusion and image generation
  • llm - Installs dependencies for language models and AI processing
  • llm_weather - Installs dependencies for weather API (used with LLM requests in handler if enabled).
  • tts - Installs text-to-speech dependencies

If you plan to run AI Runner as an application, install all of the extras.

Run AI Runner

airunner

🛠 Command-Line Arguments

AI Runner supports several command-line arguments that provide additional functionality:

  • --clear-window-settings: Clears the window settings, useful when the application crashes at an unusual window size or if a user needs to reset the UI settings before launching.
  • --print-llm-system-prompt: Prints the LLM system prompt to the command line, helpful for debugging and understanding system-generated prompts.
  • --perform-llm-analysis: Enables experimental LLM analysis, allowing advanced AI-related computations and insights.

To use these arguments, simply pass them when running AI Runner:

airunner --clear-window-settings

You can combine multiple flags if needed:

airunner --clear-window-settings --print-llm-system-prompt

🛠️ Source Installation

First install prerequiites

1. Clone and checkout the latest version of AI Runner:

git clone -b develop https://github.com/Capsize-Games/airunner.git
cd airunner

2. Install Dependencies

Windows:

pip install -e .

Linux:

pip install -e .[linux]

3. Upgrade timm

The controlnet-aux package requires an older version of timm, so manually upgrading is necessary. The following error after upgrading can be safely ignored.

pip install --upgrade timm==1.0.15

4. Run AI Runner from Source

cd src/airunner
python main.py

🐳 Docker Installation

Current builds of AI Runner are compiled using PyInstaller within Docker. See container registry.

🐧 Linux Docker Installation

Pull Docker Container

docker pull ghcr.io/capsize-games/airunner/airunner:linux

Build Docker

docker-compose -f docker-compose.yml build

Push Latest Docker Image (Admin Only)

docker tag ghcr.io/capsize-games/airunner/airunner:linux ghcr.io/capsize-games/airunner/airunner:linux
docker push ghcr.io/capsize-games/airunner/airunner:linux

Build AI Runner Locally

This command outputs build and dist folders on your machine.

docker run -it --privileged \
    -e DEV_ENV=0 \
    -e AIRUNNER_ENVIRONMENT=prod \
    -e AIRUNNER_OS=linux \
    -e PYTORCH_CUDA_ALLOC_CONF=garbage_collection_threshold:0.9,max_split_size_mb:512 \
    -e NUMBA_CACHE_DIR=/tmp/numba_cache \
    -e DISABLE_TELEMETRY=1 \
    -e TCL_LIBDIR_PATH=/usr/lib/x86_64-linux-gnu/ \
    -e TK_LIBDIR_PATH=/usr/lib/x86_64-linux-gnu/ \
    -v $(pwd)/build:/app/build \
    -v $(pwd)/dist:/app/dist \
    --user root \
    ghcr.io/capsize-games/airunner/airunner:linux \
    bash -c "mkdir -p /app/build /app/dist && chmod -R 777 /app/build /app/dist && su appuser -c 'cd /app && bash build.sh'"

Run AI Runner

./dist/airunner/airunner