Quick Start¶

Before you begin, confirm that your system meets the Requirements. Some steps shown below are optional depending on the profile you run. See Qualification for the list of available qualification profiles.

Installation¶

1. System Drivers¶

Configure system drivers:

sudo bash -c "$(wget -qLO - https://raw.githubusercontent.com/open-edge-platform/edge-developer-kit-reference-scripts/refs/heads/main/main_installer.sh)"

Additional Reference

For detailed information about system drivers, see the Edge Developer Kit Reference Scripts documentation.

2. Docker Engine¶

Docker* Engine Download Source

Intel® ESQ uses download.docker.com* as the default download source. To use a custom download source*, configure it with:

export DOCKER_SOURCE_URL=<custom_docker_source_url>

Install Docker* Engine:

# Add Docker's official GPG key:
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL ${DOCKER_SOURCE_URL:-https://download.docker.com/linux/ubuntu}/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: ${DOCKER_SOURCE_URL:-https://download.docker.com/linux/ubuntu}
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group:

Warning

Adding your user to the docker group grants root-level access. This should only be done on development or test systems.

sudo usermod -aG docker $USER

To activate your new group membership immediately in your current terminal, run:

newgrp docker

This command starts a new shell session with updated group permissions, allowing you to use Docker* without logging out. You can now verify Docker* installation is successful by running the hello-world image:

docker pull hello-world

Note

If you see a list of containers (even if empty), your user is correctly added to the docker group. If you get a permission error, ensure you have run newgrp docker in your terminal. For persistent access across all sessions, log out and log back in, or reboot your system.

Note

If you cannot pull the image, your network may be unable to reach the default registry. Configure a mirror registry in the Docker* daemon configuration:

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json > /dev/null <<EOF
{
    "registry-mirrors": [
        "<mirror-registry-source>"
    ]
}
EOF

Additional Reference

For detailed Docker* installation instructions, see the official Docker* Engine installation documentation.

3. Python Package Manager¶

Install uv to accelerate Python* package management:

curl -LsSf https://astral.sh/uv/install.sh | sh && source $HOME/.local/bin/env

Additional Reference

For detailed uv installation instructions, see the official uv Installation documentation.

4. System Setup¶

Run system-setup.sh once after the OS installation to install required system packages and configure file read permissions:

sudo bash -c "$(wget -qLO - https://raw.githubusercontent.com/open-edge-platform/edge-system-qualification/refs/heads/release/2026.3/scripts/system-setup.sh)"

Feature Availability

Some features configured by this script are optional. Intel® ESQ will still run if skipped, but certain metrics and capabilities may be unavailable.

Run the advanced setup script to enable full test coverage:

sudo bash -c "$(wget -qLO - https://raw.githubusercontent.com/open-edge-platform/edge-system-qualification/refs/heads/release/2026.3/scripts/system-setup-advanced.sh)"

Re-run after reboot

All changes applied by system-setup-advanced.sh are in current session only and resets automatically after reboot. Re-run the script after each reboot before executing tests that depend on it.

Advanced setup modules:

Module	What it changes
Locked Memory Limit	Sets `RLIMIT_MEMLOCK` to unlimited for the current session so memtester can lock all available RAM pages. Without this, memory-related tests will be limited or fail

For RT latency tests, run the RT setup script:

sudo bash -c "$(wget -qLO - https://raw.githubusercontent.com/open-edge-platform/edge-system-qualification/refs/heads/release/2026.3/scripts/system-setup-rt.sh)"

Re-run after reboot

All changes applied by system-setup-rt.sh are in current session only and resets automatically after reboot. Re-run after each reboot before executing RT tests.

RT setup modules:

Module	What it changes
Real-Time Latency Tools	Copies `cyclictest` and `chrt` with `cap_sys_nice` and `cap_ipc_lock` capabilities to a session tmpfs so RT latency tests run at `SCHED_FIFO` priority without `sudo`. Cleared on reboot
MSR Tools	Copies `rdmsr` and `wrmsr` with `cap_sys_rawio` to the same session tmpfs for Intel® RDT/CAT partition reporting and L3 CAT write verification. Cleared on reboot
Kernel Tuning	Grants world-write on cpuidle sysfs disable files (C-state control); disables timer migration (`/proc/sys/kernel/timer_migration=0`); sets up a session `tee` with `cap_sys_admin` for non-root cpuidle writes. Cleared on reboot

5. Intel® ESQ¶

Development Version

To access the latest features that may not be available in the current release, you can install the development version from the main branch:

uv tool install --force --refresh git+https://github.com/open-edge-platform/edge-system-qualification.git@main

Install Intel® ESQ from GitHub*:

uv tool install --force --refresh git+https://github.com/open-edge-platform/edge-system-qualification.git@release/2026.3

Verify that Intel® ESQ is working correctly:

esq --version

After completing the installation, go to Qualification Profiles to select a specific qualification profile, or continue to the Usage step below to use the interactive prompt.

Usage¶

1. Run¶

Run esq run to start the interactive prompt:

esq run

By default, this command:

Prompts you to select only one qualification profile to run.
If the selected qualification profile has associated vertical profiles, it prompts you to include them.
Collects metrics and generates a test report.

Upgrading Intel® ESQ

Before running a new version of Intel® ESQ, clean up any previously created esq_data folder to prevent leftover data from interfering with the new installation:

esq clean --all

Verbose Output

Use --verbose to show detailed execution logs:

esq --verbose run

Driver Requirements and Hardware Changes

Intel® GPU and NPU tests require specific drivers. Ensure you have the latest Intel® drivers installed for your hardware configuration. If you run tests on different hardware or swap system components, clean up the cache before rerunning tests:

esq --verbose clean --cache-only

Download Source

Intel® ESQ uses HuggingFace* as the default download source. For ModelScope*, configure it with:

export PREFER_MODELSCOPE=1

2. Uninstall¶

Before uninstalling, clean up all data created by Intel® ESQ, including Docker images built during test execution:

esq clean --all

Then remove Intel® ESQ:

uv tool uninstall esq

Ready to run a qualification? Continue to Qualification Profiles →