{"id":8228,"library":"imgcat","title":"imgcat Python Library","description":"imgcat provides a Python API and CLI tool to display images directly in supporting terminals (like iTerm2 or Kitty) using their graphics protocols. The current version is 0.6.0, released in November 2024, with major updates occurring periodically to add features and improve compatibility.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/wookayin/python-imgcat","tags":["cli","image","terminal","display","ipython","numpy","pytorch","jax","tensorflow"],"install":[{"cmd":"pip install imgcat","lang":"bash","label":"Install base library"},{"cmd":"pip install imgcat[torch]","lang":"bash","label":"Install with PyTorch support"},{"cmd":"pip install imgcat[jax]","lang":"bash","label":"Install with JAX support"},{"cmd":"pip install imgcat[tensorflow]","lang":"bash","label":"Install with TensorFlow support"}],"dependencies":[{"reason":"Required for image file format handling and general image processing.","package":"Pillow","optional":false},{"reason":"Required for array handling and numerical image data processing.","package":"numpy","optional":false},{"reason":"Optional: Enables direct display of PyTorch tensors.","package":"torch","optional":true},{"reason":"Optional: Enables direct display of JAX arrays.","package":"jax","optional":true},{"reason":"Optional: Enables direct display of TensorFlow eager tensors.","package":"tensorflow","optional":true},{"reason":"Optional: Enables imgcat as a matplotlib backend.","package":"matplotlib","optional":true}],"imports":[{"symbol":"imgcat","correct":"from imgcat import imgcat"},{"note":"IPython magic commands are loaded using '%load_ext' not direct import.","wrong":"import imgcat.ipython_magic","symbol":"IPython Magic","correct":"%load_ext imgcat"}],"quickstart":{"code":"from imgcat import imgcat\nimport numpy as np\n\n# Display a random numpy array as an image\n# (100x100 pixel RGB image with values 0-255)\nimgcat(np.random.randint(0, 256, size=(100, 100, 3), dtype=np.uint8))\n\n# In an IPython/Jupyter environment, you can also use:\n# %load_ext imgcat\n# %imgcat np.random.rand(100, 100, 3)\n","lang":"python","description":"This example shows how to import and use the `imgcat` function to display a randomly generated NumPy array directly in a compatible terminal. Ensure your terminal (e.g., iTerm2, Kitty, WezTerm) supports iTerm2/Kitty graphics protocols."},"warnings":[{"fix":"Upgrade to Python 3.6 or newer. Previous versions (<=0.5.0) supported Python 2.","message":"Python 2 support has been dropped.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Use a compatible terminal emulator such as iTerm2, Kitty, or WezTerm. Check your terminal's documentation for image display support.","message":"Images will only display in terminals that support iTerm2 or Kitty graphics protocols.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your NumPy array data is scaled correctly (e.g., `np.uint8` with values 0-255, or `float` with values 0-1). For example, `(np.random.rand(H, W, 3) * 255).astype(np.uint8)`.","message":"NumPy arrays passed to `imgcat` expect values in the 0-255 range (for `uint8`) or 0-1 range (for `float`). Incorrect ranges can lead to distorted or dark images.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `imgcat` version 0.6.0 or newer to benefit from fixes for matplotlib integration problems.","message":"Matplotlib integration issues were present in older versions.","severity":"gotcha","affected_versions":"<0.6.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install imgcat` to install the library.","cause":"The imgcat library is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'imgcat'"},{"fix":"Switch to a compatible terminal like iTerm2, Kitty, or WezTerm, or ensure your terminal is configured to enable image display.","cause":"Your terminal emulator does not support the necessary image protocols (iTerm2/Kitty graphics).","error":"Image does not display in terminal (no error, just blank output or text output)."},{"fix":"Convert your data to a supported type, e.g., a NumPy array, a PIL Image object, or a path to an image file. Ensure you have the necessary optional dependencies installed for tensor types.","cause":"The object passed to `imgcat` is not one of the supported image data types.","error":"TypeError: Invalid input type for imgcat. Expected bytes, path-like, numpy.ndarray, PIL.Image.Image, or torch.Tensor/tf.Tensor/jax.Array"},{"fix":"In an IPython/Jupyter environment, use the magic command `%load_ext imgcat` to enable the `%imgcat` magic.","cause":"You are trying to import the IPython magic directly, which is not how it's loaded.","error":"AttributeError: module 'imgcat' has no attribute 'ipython_magic'"}]}