Requirements

-   ASCT is supported on Linux systems
-   Python 3.10 or later. You need pip if you want to use a Python virtual environment (options 1 and 2).
-   Build tools such as:
    -   gcc
    -   make
-   If you want to install ASCT as a system-wide tool (option 3), you need:
    -   uv. Install uv from: https://docs.astral.sh/uv/getting-started/installation/
    -   sudo privileges
    -   Permission to create:
        -   /opt/uv/tools
        -   /usr/local/bin

Install ASCT

You can install ASCT in one of the following ways:

-   Option 1 (recommended): Install into a Python virtual environment using the install.sh helper script.

-   Option 2: Install manually using pip into a Python environment.

-   Option 3: Install system-wide using uv (for shared machines or CI systems).

Option 1: Install ASCT with the helper script

This is the simplest installation method. It creates a dedicated Python virtual environment and installs ASCT into it.

Steps

From inside the extracted asct-<version>/ directory:

        ./install.sh --install-dir /path/to/install/directory

If --install-dir is not specified, the script installs into the directory containing install.sh.

The install.sh script performs the following tasks:

-   Creates a Python virtual environment
-   Installs ASCT into that environment using pip
-   Optionally builds fio if required

By default, the virtual environment is created at <install-dir>/asct_venv.

After installation, follow the instructions printed by the script to activate the virtual environment before running ASCT.

Option 2: Install ASCT manually using pip

Use this method if you prefer to manage Python environments manually, are installing into an existing virtual environment, or are automating installation in your own scripts.

You can install ASCT into any active Python environment.

Install into a new virtual environment

1.  Create a virtual environment:

        python3 -m venv asct_venv

2.  Activate it:

        source asct_venv/bin/activate

3.  Install ASCT from the bundled source distribution:

        python3 -m pip install ./asct-<version>.tar.gz

    ASCT is now installed inside the virtual environment.

Install into an existing environment

    python3 -m pip install ./asct-<version>.tar.gz

ASCT is installed into the currently active Python environment.

Option 3: Install ASCT as a system-wide tool with uv

This method installs ASCT as a system-wide tool available on the system PATH.

Use this option only for shared systems, managed environments, or CI environments.

Steps

1.  Create the required directories:

        sudo mkdir -p /opt/uv/tools /usr/local/bin

2.  Install ASCT with uv and place the executable in /usr/local/bin:

        sudo UV_TOOL_DIR=/opt/uv/tools UV_TOOL_BIN_DIR=/usr/local/bin uv tool install ./asct-<version>.tar.gz

    After installation, ASCT is available on the system PATH.

Runtime tools

Some workloads require additional system tools, such as:

-   numactl
-   fio 3.36 or later

If tools are missing, ASCT reports this at runtime.

Run ASCT

-   If you installed ASCT in a virtual environment, activate the environment first.
-   If you installed ASCT with uv, no activation is required.

To verify the installation, run:

    asct help

You can also open the offline documentation at: asct_docs/index.html.

Uninstall ASCT

Option 1: If you installed ASCT using the helper script

To uninstall ASCT, remove that virtual environment directory:

    rm -rf <install-dir>/asct_venv

Option 2: If you manually installed ASCT using pip

If you installed ASCT into a dedicated virtual environment, you can remove that environment directory.

Alternatively, activate the relevant Python environment and uninstall ASCT:

    python3 -m pip uninstall asct

Option 3: If you installed ASCT system-wide using uv

Remove ASCT using uv:

    sudo UV_TOOL_DIR=/opt/uv/tools UV_TOOL_BIN_DIR=/usr/local/bin uv tool uninstall asct
