Make your inkjet printer print accurate colour — without touching the command line.
ChromIQ is a free, open-source desktop app that builds custom ICC printer profiles — the colour "fingerprint" that tells your computer exactly how your printer, ink, and paper reproduce colour. With an accurate profile, what you see on screen is what comes out of the printer.
Under the hood it drives ArgyllCMS, the gold-standard open-source colour engine, through a friendly five-step wizard. ArgyllCMS does all the colour science; ChromIQ gives it a calm, guided interface so you never have to memorise a single flag.
Note
New to printer profiling? That's exactly who ChromIQ is for. Every screen has a clickable ⓘ icon that explains, in plain language, what the step does, what you need ready (device plugged in, paper loaded…), and what comes next. The in-app tooltips are the real manual — this README is the map.
ChromIQ is free and always will be. If it's useful to you, a coffee is a kind way to say thanks — completely optional, and the app stays fully featured either way.
- What you'll need
- Download & install
- The five-step workflow
- Screenshots
- Feature highlights
- Troubleshooting
- Configuration & logs
- For developers
- Reporting issues & feedback
- License
- Acknowledgements
To build a profile you need three things:
-
A printer — any inkjet (RGB, CMYK, or extended-gamut with extra inks).
-
A spectrophotometer — the device that "reads" the printed colours. ChromIQ supports the X-Rite family:
Code Instrument i1i1Pro / i1Pro 2 / i1Pro 3 p3i1Pro 3 Plus CMColorMunki / i1Studio / ColorChecker Studio SSSpectroScan (flatbed XY table) -
ArgyllCMS installed on your computer — ChromIQ looks for it automatically and walks you through installing it if it's missing. See Installing ArgyllCMS.
ChromIQ itself runs on macOS, Windows (Intel/AMD and ARM64), and Linux (x86_64 and aarch64, currently beta).
Grab the build for your system from the latest release. The pre-built downloads are all most people need — you only need the from-source route if you want to modify the code.
- Download the universal DMG —
ChromIQ-macOS-universal_<version>.dmg(works on both Apple Silicon and Intel). - Open the DMG, then drag ChromIQ into your Applications folder.
- Eject the DMG (⌘E).
- The first time only: open Applications, right-click ChromIQ → Open, then click Open in the dialog. This tells macOS you trust the app.
Tip
Right-click → Open shows only a "Done" button (macOS Sonoma 14+)? Run this once in Terminal, then double-click ChromIQ normally:
xattr -dr com.apple.quarantine /Applications/ChromIQ.app- Download the build for your PC:
ChromIQ-Windows-x64_<version>.zip— Intel/AMD (most PCs)ChromIQ-Windows-arm64_<version>.zip— ARM64 (e.g. Snapdragon X laptops)
- Right-click the ZIP → Extract All…, open the extracted
ChromIQfolder. - Double-click
ChromIQ.exe.
Tip
"Windows protected your PC" / Defender flags the EXE? This is the usual false positive for open-source apps that aren't code-signed yet — see Troubleshooting for how to allow it. The full source is in this repo and every release is built by GitHub Actions from its matching tag.
- Download the build for your machine:
ChromIQ-Linux-x86_64_<version>.tar.gz— Intel/AMDChromIQ-Linux-aarch64_<version>.tar.gz— ARM (Raspberry Pi 4/5, ARM workstations)
- Extract and run:
tar xzf ChromIQ-Linux-x86_64_*.tar.gz ./ChromIQ/ChromIQ
Tip
qt.qpa.plugin: … xcb-cursor0 … on launch? Install the missing library —
see Troubleshooting.
Linux support is beta: ChromIQ runs, but the full workflow hasn't been exercised against real hardware yet. Please report what works (and what doesn't) via Discussions or the issue tracker.
ChromIQ needs ArgyllCMS 3.5.0 to do the colour work. It is not bundled with ChromIQ — you install it once, separately, and ChromIQ finds it automatically.
| OS | How to install |
|---|---|
| macOS | Download from argyllcms.com, unzip, and move the folder into /Applications (e.g. /Applications/Argyll_V3.5.0/). |
| Windows | Download the win64 build from argyllcms.com and extract to C:\Program Files\ArgyllCMS\. |
| Linux | sudo apt install argyll · sudo dnf install argyllcms · sudo pacman -S argyllcms, or download from argyllcms.com. |
On first launch ChromIQ searches automatically — the system PATH, Homebrew,
MacPorts and any Argyll* folder in /Applications on macOS; the standard
install folders on Windows; /usr/bin and common paths on Linux. If it can't
find ArgyllCMS, a setup guide opens. You can also point it manually any time:
Preferences (
⌘,on macOS,Ctrl+,elsewhere) → Auto-detect to search again, or Browse to the ArgyllCMSbinfolder, then Test binaries to confirm it works.
ChromIQ is organised as five numbered tabs. Walk left to right and you have a finished, installed profile.
| Step | What happens | ArgyllCMS tool | |
|---|---|---|---|
| 1 | Create Chart | Generate a test chart with the ideal number of colour patches for your instrument, paper, and page count. | targen + printtarg |
| 2 | Print Chart | Send the chart to your printer with colour management switched off (so you measure the printer's raw behaviour). | CUPS / native dialog |
| 3 | Measure | Scan the printed patches with your spectrophotometer. | chartread |
| 4 | Build Profile | Turn the measurements into a finished .icc profile and install it. |
colprof |
| 5 | Check & Refine | Score the profile's accuracy, view its 3D gamut, and re-measure only the worst patches to improve it. | profcheck + iccgamut |
Every step offers two modes:
- Guided — pick instrument, paper, and page count; ChromIQ chooses sensible, empirically-tuned defaults for everything else.
- Manual — every ArgyllCMS flag is exposed, with a live preview of the exact command that will run. Save your favourite setups as named presets.
Choose Guided or Manual, name your target, and click Generate Chart. The
patch grid appears in the preview on the right. Optionally tick Refinement
profile to base a second, improved pass on an existing .icc/.icm.
Pick your printer and print the chart. On macOS the native print dialog is now the default — ChromIQ opens the OS print sheet and locks the driver's colour controls off for you (via PyObjC), so colour management can't sneak back in. The per-brand steps for confirming colour is disabled are shown right in the tab. On Windows and Linux the OS print sheet opens the same way, with per-brand instructions for turning ICM off.
Tip
Prefer the old behaviour on macOS? Turn Use default macOS printer dialog off in Preferences and ChromIQ falls back to its direct PostScript pipeline, which bypasses colour management automatically with no dialog at all — handy for batch printing.
The chart from Step 1 loads automatically. Follow the on-screen prompts: Enter/Space confirms a strip, and F / B step forward and back between strips (the on-screen strip highlight follows along). Misread a strip? The dialog offers Retry, Skip Stripe, or Save Partial & Quit (which lets you resume later with one click).
Review the colprof settings and click Build Profile. Then Install
Profile copies it to the right place for your OS so every app can use it. To
iterate, click ← Use as Pre-conditioning to seed an improved second pass.
Click Analyse Profile Quality to get per-patch ΔE accuracy scores. The 3D Gamut Volume viewer on the right shows the range of colours your profile can reproduce — and you can load a second profile to compare them (volume difference, overlap, and coverage in both directions). Patches that scored poorly can be re-measured in one click, then rebuilt.
Note
Optional calibration mode. Turn on Enable calibration options in
Preferences to expand Step 4 into a three-part panel — Create Calibration
File (printcal), Build Profile (colprof), and Apply Calibration
(applycal) — for per-channel ink linearisation before profiling.
Every screen is shown in both Dark and Light appearance (ChromIQ also has a System/Auto mode that follows your OS live). Click any step to expand it.
Step 1 — Create Chart
| Dark | Light | |
|---|---|---|
| Guided |  |
 |
| Manual |  |
 |
Step 2 — Print Chart
| Dark | Light | |
|---|---|---|
| Native print dialog (macOS default) |  |
 |
| PostScript pipeline (no-dialog fallback) |  |
 |
Step 3 — Measure
| Dark | Light | |
|---|---|---|
| Guided |  |
 |
| Manual |  |
 |
| "All stripes read" prompt |  |
 |
Step 4 — Build Profile
| Dark | Light | |
|---|---|---|
| Guided |  |
 |
| Manual |  |
 |
| "Profile built" — what next? |  |
 |
Calibration mode — Create Calibration File (printcal) |
 |
 |
Calibration mode — Apply Calibration (applycal) |
 |
 |
Step 5 — Check & Refine
| Dark | Light | |
|---|---|---|
| Analysis run |  |
 |
| Quality assessment (per-patch ΔE) |  |
 |
| Manual options |  |
 |
| 3D gamut comparison (two profiles) |  |
 |
Preferences
| Dark | Light |
|---|---|
 |
 |
- Guided uses an empirical patch-capacity database to pick the right patch count for your instrument/paper/page combo — no guesswork.
- Manual exposes every
targen/printtarg/colprofflag with a live command preview, plus per-tab Save as Defaults and named presets.
- PostScript Level 2/3 pipeline (macOS) that disables colour management automatically — no driver fiddling, no ColorSync in the way.
- Automatic TIFF fallback for AirPrint / driverless printers that reject PostScript, plus 16-bit TIFF output for true 16-bit printers and RIPs.
- Native OS print dialog option — on macOS it even locks the driver's colour controls via PyObjC so they can't be re-enabled by accident; on Windows/Linux it shows per-brand instructions for turning ICM off.
- Preflight confirmation with paper-size and orientation checks, offline printer detection, and a Clear Print Queue button for stuck jobs.
- Full
colprofoption set — illuminants (D50/D65/A/C/F5/F8/F10), observers (1931 2°, 1964 10°, 2015 variants), FWA compensation, gamut-mapping intents. - RGB, CMYK, and multi-channel (DeviceN) targets — from 4-channel CMYK to
extended-gamut ink sets (CMYK plus Orange, Green, Light Cyan, …). The UI lets
you stack up to 11 colorant overrides (
-D); ArgyllCMS supports up to 16 device channels. - Pre-conditioning (second-pass) refinement — drive a
targen -cpass from an existing profile to iteratively improve it, with automatic archiving. - CIECAM02 viewing-condition presets for correct perceptual/saturation tables.
- ICC media attributes (
colprof -Z) embedded in the profile header.
profcheckintegration with per-patch ΔE statistics and quality grading.- Targeted re-measurement — only the patches above your ΔE threshold.
- Interactive 3D gamut viewer (
iccgamut+viewgam+ X3DOM) with volume in ΔE³, Lab / CIECAM02 Jab, cusp markers, and edge plots. - Profile-vs-profile comparison — volume delta, intersection volume, and bidirectional coverage.
Most people never need this — Guided mode already picks a great chart. But when you want full control over which colours you measure and how the sheet is laid out, the chart layout editor (Tools → Edit / create chart layout) is a complete design surface:
- Start from anything — load an existing
.ti2, pull in the chart you just made on the Create Chart tab, or build a fresh patch set from a targen seed, pasted colours or the colour-set generators. - Rearrange freely — move patches and whole strips with Front / Up / Down / Back, and see the printed sheet redraw in a live, multi-page preview.
- Recolour patches and spacers — set or nudge patch colours, edit the spacer palette, or paint individual separator strips, all while ChromIQ keeps the measurement data and the printed pixels perfectly in sync.
- Combine charts — append or prepend the colours from another
.ti2/.ti1/.ti3/i1Profiler file to merge two targets into one. - See it in 3D — the 3D distribution viewer plots your whole patch set as an interactive RGB cube so you can spot gaps and clumps at a glance.
- Save & apply pushes your custom layout straight back into the Create Chart tab, ready to print.
Build a target around the colours you actually print. The colour-set generator (in New chart and Add patches) lets you stack any mix of these, with live patch counts and automatic de-duplication so combined sets never double up:
- 3D RGB cube — even coverage across the whole colour range.
- Skin tones — light→dark ramps through all six Fitzpatrick phototypes.
- Blues / turquoise and Greens (foliage) — denser sampling of skies, water, forests, and foliage.
- Near-neutral greys — a neutral ramp plus subtle hue rings for clean, cast-free greys.
- Saturated edges and gamut faces — the most vivid colours your printer can reach, for accurate gamut boundaries.
- Highlights & shadows — extra detail at the bright and dark ends where printers struggle most.
- Pastels — soft, low-chroma colours across every hue.
- From image — load a photo and ChromIQ extracts its most representative colours, so you can profile around a specific image or palette.
- White & black anchors and Fill remaining gaps — guarantee pure paper-white/black, then scatter extra patches into the sparsest parts of the set up to a target count.
The masthead Tools button opens a menu of conversions and checks you can run on their own, outside the five-step flow:
- Edit / create chart layout — the full layout editor and colour-set generator described above: reorder strips, recolour patches and spacers, combine charts, generate custom colour sets, and view them in 3D.
- Average measurements — combine repeat reads of the same chart for lower noise.
- Merge measurements — fold extra measurements into an existing set.
- Convert TI1 → i1Profiler and Convert i1Profiler → TI1 / TI3 — move charts and measurements between ChromIQ/ArgyllCMS and X-Rite i1Profiler.
- Verify a profile (independent check) and Verify against reference — validate an existing profile's accuracy without rebuilding it.
- Light / Dark / System (Auto) appearance that follows your OS theme live.
- Per-tab onboarding tooltips, live command preview, and a zoomable multi-channel TIFF preview (RGB, CMYK, extended-gamut).
- Session restore, rotating log file, and a built-in update checker.
- Self-documenting chart TIFFs — the exact commands and ChromIQ version are stamped into each generated TIFF's margin.
Windows: "Windows protected your PC" or Defender removed the EXE
ChromIQ is packaged with PyInstaller and isn't code-signed yet, so unsigned-app heuristics sometimes flag it. This is common and not specific to ChromIQ.
- SmartScreen warning: click More info → Run anyway.
- EXE disappeared after extracting: open Windows Security → Virus & threat protection → Protection history, find ChromIQ, and choose Restore / Allow on device.
- Keeps recurring: add the ChromIQ folder under Virus & threat protection → Manage settings → Exclusions → Add an exclusion → Folder.
Linux: xcb-cursor0 error on launch
Install the missing system library:
sudo apt install libxcb-cursor0 # Debian / Ubuntu
sudo dnf install xcb-util-cursor # Fedora / RHEL
sudo pacman -S xcb-util-cursor # ArchChromIQ can't find ArgyllCMS
Open Preferences → Auto-detect. If that fails, click Browse, select
the ArgyllCMS bin folder, and click Test binaries. See
Installing ArgyllCMS for the expected locations.
Windows/Linux: colour looks wrong in the printed chart
The CUPS/PostScript auto-bypass is macOS-only. On Windows and Linux you must disable ICM/colour management in the printer driver before printing a profiling target — ChromIQ shows per-brand instructions in the Print tab and can't do this for you without CUPS.
Settings are stored with QSettings (on macOS,
~/Library/Preferences/ChromIQ.ChromIQ.plist). The Preferences dialog (⌘,)
exposes:
| Setting | Default | What it does |
|---|---|---|
| ArgyllCMS bin path | auto-detected | Folder containing the ArgyllCMS executables |
| Output folder | ~/ChromIQ/ |
Where chart/profile projects are saved |
| Restore last active tab on launch | On | Reopen on the last-used tab |
| Restore last session on launch | Off | Reload the last project's files at startup |
| Enable calibration options | Off | Unlock the printcal → applycal workflow |
| Use default macOS printer dialog | Off | Use the native print sheet instead of the PostScript pipeline (macOS) |
| Confirm print settings before sending | On | Show a preflight summary before each job |
| Use app theme colours for 3D gamut viewer | On | Tint the gamut mesh with ChromIQ's palette |
Each project lives in its own folder under ~/ChromIQ/<project-name>/, holding
every generated file for that run (chart, measurements, profile, quality
reports). See docs/dev_folder_layout.md for the
exact layout.
Logs (rotating, max 5 MB × 5 backups) record every ArgyllCMS command run — the fastest way to diagnose a problem:
- macOS:
~/Library/Logs/ChromIQ/chromiq.log - Windows:
%LOCALAPPDATA%\ChromIQ\Logs\chromiq.log - Linux:
~/.local/state/ChromIQ/logs/chromiq.log
Most users don't need this section — the pre-built downloads above are all you need. Continue here only to run or modify the source.
git clone https://github.com/itsab1989/ChromIQ.git
cd ChromIQ
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python main.pyRequires Python 3.12+. Key dependencies: PyQt6 / PyQt6-WebEngine (≥ 6.11),
Pillow, PyYAML, NumPy, tifffile, imagecodecs, certifi, and (macOS only) pycups
and pyobjc. See requirements.txt.
source .venv/bin/activate
QT_QPA_PLATFORM=offscreen pytest # ~1–2s, 284 testspip install pyinstaller
pyinstaller ChromIQ.spec # macOS → dist/ChromIQ.app
# ChromIQWin.spec (Windows) ChromIQLinux.spec (Linux)ArgyllCMS binaries are not bundled — install them separately and set the path in Preferences.
The screenshots in docs/ are generated by a script that drives the real app:
scripts/make_sample_projects.sh # build sample data (needs ArgyllCMS)
python scripts/capture_screens.py # opens the app and captures docs/*.pngChromIQ is a thin GUI over ArgyllCMS; the heavy colour science is all Argyll.
| Directory | Purpose |
|---|---|
core/ |
Settings, ArgyllCMS detection, the QProcess runner, file/project management, logging |
data/ |
parameters.yaml (every CLI flag + tooltip) and the patch-capacity database |
ui/ |
All Qt widgets — main window, the five tabs, shared TIFF preview, gamut panel, dialogs |
workflow/ |
Business logic — chart creation, PostScript generation, printing, measuring, profiling |
A few patterns worth knowing:
data/parameters.yamldrives the UI. Add a parameter there — withtool,flag,type,default,tooltip_title,tooltip_body— and it appears in Manual mode automatically, no code changes needed. (no_space: trueappends the value directly to the flag;expert_only: truehides it under "Expert".)- All file paths go through
Project/Run/Calibrationincore/file_manager.py— never hard-code a filename pattern. ArgyllRunneris a singleton — only one ArgyllCMS process runs at a time.
More developer docs live in docs/ (folder layout, built-in presets,
the i1Profiler export format, and more), and project-specific guidance is in
CLAUDE.md.
You can reach all of these from inside the app — Preferences (⌘,) →
Report a Bug… in the bottom row.
- Found a bug? Open a bug report. Please attach the log file (see Configuration & logs) — it captures every ArgyllCMS command and is usually the fastest path to a fix.
- Have an idea? Open a feature request.
- Question or open-ended chat? Use Discussions.
ChromIQ is free software, licensed under the GNU General Public License v3.0
(see LICENSE). You're free to use, study, share, and modify it; if
you distribute a modified version, it must stay free under the same license.
GPLv3 is the right fit because ChromIQ builds on GPL-licensed components (PyQt6 and pycups), so the combined application is, and remains, free and open source. ArgyllCMS (AGPLv3) is used at arm's length as a separate command-line program and is not bundled or modified, so its copyleft does not extend to ChromIQ's own code.
ChromIQ stands on the shoulders of ArgyllCMS by Graeme Gill — an outstanding open-source colour management system that does all the real colour science here. ChromIQ is purely a friendly front-end to it.
A heartfelt thanks to soul-traveller for Argyll_Printer_Profiler — a mature, in several areas more comprehensive printer-profiling tool. If you prefer working from proven, pre-made test charts rather than randomly generated targets, his project ships an excellent curated collection for exactly that.
