FlatImage packages your entire application—code, dependencies, and configuration—into a single executable that runs sandboxed on any Linux distribution. No installation, no external files, no compatibility issues.
🔒 Sandboxed by Default Granular permissions (network, GPU, home, audio...). Default: zero access, fully isolated.
📦 Self-Contained All config embedded in the ELF binary's reserved space.
⚡ Fast & Compact DwarFS compression delivers high ratios with on-the-fly decompression.
✨ Truly Portable Static linking + embedded tools. One file runs on any Linux distro without dependencies.
🔧 Reconfigurable After Build Change permissions, environment, boot commands, and bindings post-creation without rebuilding.
🗂️ Multiple Filesystem Backends Switch between OverlayFS (fast), UnionFS (compatible), BWRAP (native), or CIOPFS (case-insensitive) at runtime.
🎮 Case-Insensitive Filesystem
Windows-style case folding for Wine/Proton compatibility. Toggle with fim-casefold on.
🔌 Portal IPC System Transparent host-guest communication. Execute host commands from containers with full I/O redirection.
🧱 Layered Architecture
Stack compressed layers with fim-layer commit. Copy-on-write, incremental builds, immutable base layers.
📦 Package Recipes
Install curated package sets with dependency resolution: fim-recipe install gpu,audio,xorg.
🔗 Runtime Bind Mounts
Map host paths dynamically without rebuilding: fim-bind add rw '$HOME/Documents' /Documents.
🚀 Multi-Instance Support
Run multiple isolated instances simultaneously. Execute in specific instances with fim-instance.
🖥️ Desktop Integration Auto-generated menu entries, MIME types, and icons. Paths auto-update on file moves.
# Download and run a complete Alpine Linux environment
wget -O alpine.flatimage https://github.com/flatimage/flatimage/releases/latest/download/alpine-x86_64.flatimage
chmod +x alpine.flatimage
./alpine.flatimage # You're now inside an isolated Alpine container!📚 User Documentation: https://flatimage.github.io/docs
💻 Developer Documentation: https://flatimage.github.io/docs-developer
Download one of the following distributions of a FlatImage package:
-
Alpine Linux is a complete
MUSLsubsystem with theapkpackage manager. Download -
Arch Linux is a complete
GNUsubsystem with thepacmanpackage manager. Download -
Blueprint is an empty FlatImage so you can build your own Linux sub-system. Download
The following commands download and enter the alpine container.
# Download the container
$ wget -O alpine.flatimage https://github.com/flatimage/flatimage/releases/latest/download/alpine-x86_64.flatimage
# Make it executable
$ chmod +x ./alpine.flatimage
# Enter the container
$ ./alpine.flatimage
[flatimage-alpine] / > echo hello
helloTo exit the container, just press CTRL+D.
By default, no permissions are set for the container. To allow one or more permissions use the fim-perms command.
$ ./alpine.flatimage fim-perms add xorg,wayland,networkThe permissions xorg and wayland allow applications to create novel windows which appear in the host system. The network permission allows network access to applications inside the container.
To execute commands without entering the container, use fim-exec and fim-root. These commands bring up the container, execute your command, and bring down the container after the command is finished.
fim-root executes the command as the root user.
# Allow network access
$ ./alpine.flatimage fim-perms add xorg,wayland,network,audio
# Using 'fim-root' to install firefox in the alpine image
$ ./alpine.flatimage fim-root apk add firefoxfim-exec executes the command as a regular user.
# Using 'fim-exec' to run firefox as a regular user
$ ./alpine.flatimage fim-exec firefox font-notofim-boot configures the default boot command, by default it is bash.
# Configure the boot command
$ ./alpine.flatimage fim-boot set firefox
# Opens firefox
$ ./alpine.flatimagefim-layer compresses and saves your installed applications. FlatImage offers three flexible commit modes:
Embed layers directly in the executable for maximum portability:
# Install Firefox
$ ./alpine.flatimage fim-root apk add firefox
# Commit to binary
$ ./alpine.flatimage fim-layer commit binary
# Rename and share as a single file
$ mv ./alpine.flatimage ./firefox.flatimagePerfect for: Distributing portable apps, creating standalone executables
Save layers to a managed directory with auto-increment naming:
# Install development tools
$ ./alpine.flatimage fim-root apk add vim git gcc
# Save as layer-000.layer
$ ./alpine.flatimage fim-layer commit layer
# Install more tools
$ ./alpine.flatimage fim-root apk add nodejs npm
# Save as layer-001.layer
$ ./alpine.flatimage fim-layer commit layerLayers are stored in .alpine.flatimage.data/layers/ and are automatically mounted on every run.
Perfect for: Development workflows, organizing modular packages, testing configurations
Create shareable layer files with custom names:
# Build a GPU layer
$ ./alpine.flatimage fim-root apk add mesa vulkan-loader
$ ./alpine.flatimage fim-layer commit file ./shared/gpu-support.layer
# Share with others or use in multiple images
$ FIM_LAYERS=./shared/gpu-support.layer ./another-app.flatimagePerfect for: Sharing layers between projects and version control.
fim-casefold enables filesystem case-insensitivity. Linux filesystems are case-sensitive by default. This means:
file.txt,File.txt, andFILE.txtare treated as three completely different files- You can have all three in the same directory simultaneously
- This applies to most common Linux filesystems like ext4, XFS, and Btrfs
Example:
$ touch readme.txt
$ touch README.txt
$ ls -1
readme.txt
README.txtWindows filesystems (NTFS, FAT32) are case-insensitive but case-preserving. This means:
file.txtandFile.txtrefer to the same file- The system preserves the capitalization you used when creating the file
- You cannot have two files in the same directory that differ only by case
- Commands and file access treat names as case-insensitive.
To make FlatImage's filesystem case insensitive:
# Enable case-insensitivity
$ ./alpine.flatimage fim-casefold on
# Create create a README file.
$ ./alpine.flatimage fim-root touch /READme.md
# Try to access it as 'readme.md'
$ ./alpine.flatimage fim-root stat /readME.md
File: /readME.md
Size: 0 Blocks: 0 IO Block: 4096 regular empty file
Device: 61h/97d Inode: 26 Links: 1
Access: (0644/-rw-r--r--) Uid: ( 0/ UNKNOWN) Gid: ( 0/ root)
Access: 2025-10-11 19:14:21.106722076 +0000
Modify: 2025-10-11 19:14:21.106722076 +0000
Change: 2025-10-11 19:14:21.107484017 +0000The current implementation is not case-preserving, the file names are always created in lower-case. Thus, if disabled with fim-casefold off, the file in the previous example will be accessible only as readme.md until casefolding is turned back on.
- RunImage: Portable single-file Linux container in unprivileged user namespaces.
- AppBundle: The .AppImage alternative designed for Linux, BSDs and more!
- NixAppImage: Nix-based AppImages.
- Flatpak: Linux application sandboxing and distribution framework.
- Conty: Container-based portable apps.
- binctr: Fully static, unprivileged, self-contained, containers as executable binaries.
- nix-bundle: Bundle Nix derivations to run anywhere!
- AppImage: Linux apps that run anywhere.
- exodus: Painless relocation of Linux binaries–and all of their dependencies–without containers.
- statifier: Statifier is a tool for creating portable self-containing Linux executable.
- bubblewrap: Low-level unprivileged sandboxing tool used by Flatpak and similar projects.
- Proot: chroot, mount --bind, and binfmt_misc without privilege/setup for Linux.
