Install FlyDSL

Install FlyDSL#

FlyDSL is a Python DSL and MLIR compiler stack for writing high-performance AMD GPU kernels. This page explains how to install FlyDSL using pip or from source, verify the installation, and resolve common issues.

Prerequisites#

  • Python: 3.10 or later

  • ROCm: Required for GPU execution tests and benchmarks (IR-only tests do not need a GPU)

  • GPU targets: See the architecture and validation scope below.

  • OS: Linux; use a ROCm version supported by your GPU and the selected wheel.

For the latest ROCm installation instructions, see the ROCm installation guide.

Architecture and validation scope#

Compiler support for an instruction family does not imply that every prebuilt kernel supports every target, dtype, or shape. The following describes the current source tree; consult the tests and CI results for the revision you use.

Target-specific implementation and validation#

Target

Implementation

Validation scope

gfx942

CDNA3 MFMA and buffer-copy paths

MI325 runners are included in source and wheel CI. Kernel tests cover selected shapes and dtypes, not all possible configurations.

gfx950

CDNA4 MFMA, including target-specific FP4 paths

MI35x source runners and MI355 wheel runners exercise selected kernels. Check per-kernel restrictions before reusing a configuration.

gfx11*

RDNA WMMA paths

Architecture-gated RDNA GEMM tests exist. Test presence alone is not evidence of a passing wheel validation run on every RDNA device.

gfx120*

RDNA WMMA paths, with separate dtype/shape restrictions

Architecture-gated RDNA GEMM tests exist; source CI includes a Navi runner. The wheel CI matrix is narrower than the source target set.

For other target-specific APIs, see Compiler and pipeline and the corresponding kernel tests. This table is not a blanket support guarantee. The authoritative runner matrices and environments are in the source workflow and wheel workflow; inspect their run results for validation of a particular commit. See also RDNA GEMM tests.

Install from PyPI#

For standalone use, install the published package directly:

python -m pip install flydsl

Verify that Python can import FlyDSL:

python -c "import flydsl; print('FlyDSL version', flydsl.__version__)"

Documentation and integration versions#

The GitHub Pages documentation tracks main. Its version comes from the source tree and can be ahead of the package available from PyPI or a GitHub Release. Use the release list and the docs/ directory at the corresponding tag when working with a release; APIs described on the main site may not be available in an older wheel.

When FlyDSL is a dependency of another project, follow that project’s installation instructions and dependency constraints instead of upgrading FlyDSL independently:

Integration compatibility sources#

Project

How to select a version

AITER

Use the FlyDSL pin in the requirements.txt of the AITER revision being installed. See AITER dependencies.

MORI

Follow the selected MORI release’s optional FlyDSL dependency and device-API instructions. See MORI package metadata and the MORI installation guide.

Dependency constraints describe installation compatibility; they do not prove that every kernel or communication topology has been tested. Record the FlyDSL, ROCm and consuming-project versions when reporting an integration issue.

Build from source#

Build from source only if you are developing FlyDSL itself or need a custom MLIR/LLVM build.

Start from a checkout and run the commands below from its root:

git clone https://github.com/ROCm/FlyDSL.git
cd FlyDSL

Additional prerequisites for source builds:

  • Build tools: cmake (>=3.20), a C++17 compiler, and optionally ninja

  • Python deps: nanobind, numpy, pybind11 (installed automatically)

Step 1: Build LLVM/MLIR#

If you already have an MLIR build with Python bindings enabled, point to it:

export MLIR_PATH=/path/to/llvm-project/build-flydsl/mlir_install

Otherwise, use the helper script that clones the ROCm llvm-project and builds MLIR:

bash scripts/build_llvm.sh -j64
export MLIR_PATH=/path/to/llvm-project/build-flydsl/mlir_install

Step 2: Build FlyDSL#

Build the Fly C++ dialect, compiler passes, and embedded Python bindings:

bash scripts/build.sh -j64

build.sh auto-detects MLIR_PATH from common locations. Override with:

MLIR_PATH=/path/to/mlir_install bash scripts/build.sh -j64

After a successful build, you have:

  • build-fly/bin/fly-opt – the Fly optimization tool

  • build-fly/bin/flydsl-lsp-server – MLIR Language Server for FlyDSL .mlir

  • build-fly/python_packages/flydsl/ – Python package root containing:

    • flydsl/ – Python DSL API (sources from python/flydsl/)

    • _mlir/ – embedded MLIR Python bindings (no external mlir wheel required)

Step 3: Install FlyDSL#

For development (editable install):

pip install -e .

Or use setup.py directly:

python setup.py develop

This creates an editable install — changes to python/flydsl/ are immediately reflected.

Without installing, you can also set paths manually:

export PYTHONPATH=$(pwd)/build-fly/python_packages:$(pwd):$PYTHONPATH
export LD_LIBRARY_PATH=$(pwd)/build-fly/python_packages/flydsl/_mlir/_mlir_libs:$LD_LIBRARY_PATH

To build a distributable wheel:

python setup.py bdist_wheel
ls dist/

Verify installation#

Run the test suite to verify that everything works:

bash scripts/run_tests.sh

This runs the following:

  • MLIR lit tests: tests/mlir/{LayoutAlgebra,Conversion,Transforms}/*.mlir through fly-opt

  • Python tests: tests/python/examples/ (AOT examples)

  • Kernel/GPU execution tests (only if ROCm is detected): tests/kernels/test_*.py

Troubleshooting#

fly-opt not found

Run bash scripts/build.sh, or build explicitly:

cmake --build build-fly --target fly-opt -j$(nproc)
Python import issues (No module named flydsl)

Install the published package, or use the source checkout after building:

pip install flydsl
pip install -e .
MLIR .so load errors

Add the MLIR build lib dir to the loader path:

export LD_LIBRARY_PATH=$MLIR_PATH/lib:$LD_LIBRARY_PATH
Contents