Installing hipCIM

Installing hipCIM#

2025-12-17

4 min read time

Applies to Linux

This topic discusses how to install hipCIM using the following options:

Build from source (for developers)
Recommended: AMD PyPI (for users)

System requirements#

ROCm version	Ubuntu version	Python version	AMD Instinct GPU
6.4.3	22.04	3.10	MI325X

Setting up the environment#

Optional: Use ROCm Docker to get started.

docker pull rocm/dev-ubuntu-22.04:6.4.3-complete
docker run --cap-add=SYS_PTRACE --ipc=host --privileged=true   \
      --shm-size=128GB --network=host --device=/dev/kfd     \
      --device=/dev/dri --group-add video -it               \
      -v $HOME:$HOME  --name ${LOGNAME}_rocm                \
                                       rocm/dev-ubuntu-22.04:6.4.3-complete

For bare metal, skip this step.

Install system dependencies.

sudo apt update
sudo apt install -y lsb-release software-properties-common libopenslide0 python3.10-venv rocjpeg
sudo apt install -y rocthrust-dev hipcub hipblas \
            hipblas-dev hipfft hipsparse      \
            hiprand rocsolver rocrand-dev git git-lfs
pip install --upgrade pip

Create the Python virtual environment.

python3 -m venv hipcim_dev
source hipcim_dev/bin/activate

Set up the environment variables.

export ROCM_HOME=/opt/rocm
export AMDGPU_TARGETS=gfx942

Building hipCIM from source#

To build hipCIM from source, follow the steps given in this section. hipCIM developers should use this installation method. hipCIM users should use the Installing hipCIM using AMD PyPI.

Install the required system dependencies.
```
pip install --upgrade pip
```
Download the latest version of hipCIM from the git repository.
```
git clone git@github.com:ROCm-LS/hipCIM.git
cd hipCIM
```
Install the rest of the dependencies.
```
pip install -r ./requirements.txt
```
Build and install hipCIM.

To build the hipCIM library on a ROCm-based AMD system using the development environment, follow these steps:
1. Build the base C++ libraries.
```
./run_amd build_local cpp release
```
1. Build the Python bindings.
```
./run_amd build_local hipcim release
```
1. Install the Python bindings.
```
python3 -m pip install python/cucim --extra-index-url https://pypi.amd.com/simple
```
Verify the installation.

To verify the installation, follow these steps:
1. Execute the tests in the base C++ libraries.
```
./run_amd test cpp release
```
1. Execute the Python tests.
```
./run_amd test_python
```

Installing hipCIM using AMD PyPI (recommended)#

Packaged versions of hipCIM and its dependencies are distributed via AMD PyPI. This section discusses how to install hipCIM using this package index. hipCIM users should use this installation method. hipCIM developers should use the Building hipCIM from source.

Install amd-cupy.

pip install amd-cupy --extra-index-url=https://pypi.amd.com/simple

Install hipCIM.

pip install amd-hipcim --extra-index-url=https://pypi.amd.com/rocm-6.4.3/simple

Verify the installation.

pip show -v amd-hipcim

Expected output:

Name: amd-hipcim
Version: 25.4.0
Summary: hipCIM - an extensible toolkit designed to provide GPU accelerated I/O, computer vision & image processing primitives for N-Dimensional images with a focus on biomedical imaging.
Home-page: https://rocm.docs.amd.com/projects/hipcim/en/latest/
Author: AMD Corporation
Author-email:
License: Apache 2.0
Location: /scratch/integration/hipcim_dev/lib/python3.10/site-packages
Requires: amd-cupy, click, lazy-loader, numpy, scikit-image, scipy
Required-by:
Metadata-Version: 2.4
Installer: pip
Classifiers:
   Development Status :: 4 - Beta
   Intended Audience :: Developers
   Intended Audience :: Education
   Intended Audience :: Science/Research
   Intended Audience :: Healthcare Industry
   Topic :: Scientific/Engineering
   Operating System :: POSIX :: Linux
   Environment :: Console
   Environment :: GPU :: AMD Instinct :: MI300
   License :: OSI Approved :: Apache Software License
   Programming Language :: C++
   Programming Language :: Python
   Programming Language :: Python :: 3
   Programming Language :: Python :: 3.10
Entry-points:
   [console_scripts]
   cucim = cucim.clara.cli:main
Project-URLs:
   Homepage, https://rocm.docs.amd.com/projects/hipcim/en/latest/
   Documentation, https://rocm.docs.amd.com/projects/hipcim/en/latest/reference/hipcim/index.html#hipcim-reference
   Source, https://github.com/AMD-AIOSS/hipCIM
   Tracker, https://github.com/AMD-AIOSS/hipCIM/issues

Getting started#

Here is a sample Python code and its expected output to help you get started.

Sample code:

from cucim import CuImage
img = CuImage("sample_image/oxford.tif")
resolutions = img.resolutions
level_dimensions = resolutions["level_dimensions"]
level_count = resolutions["level_count"]
print(resolutions)
print(level_count)
print(level_dimensions)
region = img.read_region([0,0], level_dimensions[level_count - 1], level_count - 1, device="cuda")
print(region.device)