1 stable release

new 1.0.0	May 6, 2025

#426 in Procedural macros

Used in xray-tui

Custom license

16KB

Xray

![](./resources/xray.png =250x)

A blazing fast Docker (or any OCI-compliant) image layer inspector!

Xray helps developers understand and optimize container images by visualizing layers and their contents using a minimalistic but powerful UI with performance in mind.

Features

Demo

🛠️ Supports Vim motions
📌 Relatively small memory footprint (~80Mb for an 8Gb image)
🗒️ Supports path filtering (with full RegEx support)
⛓️ Supports size-based filtering
🚀 Fast startup times due to optimized image parsing
🏡 Convenient and minimalistic UI
📦 Works with any OCI-compliant container image
⚙️ No needless re-rendering of the UI: xray values your CPU cycles

Disclaimer

This is essentially a beta release at this point, so don't hesitate to open an issue if you find any bugs while using it 🍀

Installation

From source

⚠️ Requires the nightly compiler

# If Rust nightly wasn't installed before
$ rustup toolchain install nightly
$ cargo +nightly install --locked xray

Motivation

Everyone who had to work with container images before knows about the dive tool created by @wagoodman. It's a great tool, but it doesn't work that well for bigger images, especially the ones that are 5 GB or more in size.

Xray fixes this problem by carefully managing available resources and applying a set of small but important optimizations. All these things make Xray far more responsive when used with large images, while still providing the core functionality and being easy to use.

Usage

$ xray --help
Usage: xray [OPTIONS] <IMAGE>

Arguments:
  <IMAGE>

Options:
  -p, --config-path <CONFIG_PATH>
  -h, --help                       Print help
  -V, --version                    Print version

Starting the app

To inspect a Docker image stored as a tarred repository use:

xray <PATH_TO_IMAGE_TAR>

Keybindings

💡 You can always use the help popup available by pressing / to get the contextualized help for the currently active pane.

Key Sequence	Action
`1`	select the "Image Information" pane
`2`	select the "Layer Information" pane
`3`	select the "Layers" pane
`4`	select the "Layer Changes" pane
`Left`, `h`	scroll the current entry left (if supported by pane)
`Down`, `j`	select the next entry in the current pane
`Up`, `k`	select the previous entry in the current pane
`Right`, `l`	scroll the current entry right (if supported by pane)
`Tab`	cycle through the panes: next pane
`Shift-Tab`	cycle through the panes: previous pane
`q`	exit the app

Actions

Key Sequence	Action
`Enter`, `Space`	toggle the selected directory (inside the "Layer Changes" pane)
`Ctrl-f`	open the filter popup (inside the "Layer Changes" pane)
`y`	copy the currently selected value to the clipboard (if supported by pane)
`/`	open/close the help popup

Limitations

GZipped Tar image layers are not supported, which may cause issues for certain images
Opaque whiteouts are not handled properly
Some panes are missing the vertical/horizontal scroll feature, which may cause issues in certain contexts

Planned Improvements

This section contains additional good-to-have things that I plan to add besides fixing everything in the Limitations section.

Reduce the memory footprint further
Add unit and fuzz tests
Improve the scrolling behaviour in the "Layer Changes" tab
Add more installation options
Add configurable keybindings
Add layer caching

Copyright and License

Xray is distributed under the GNU General Public License version 3. See COPYING for full details.

Dependencies

~195–630KB
~15K SLoC

macro formatted-index-macro