Distinct tools.
One creative flow.

Getting started

Emulsion brings Photo, Paint, Library, Design, and Diagram together in one desktop app for Linux, macOS, and Windows. Its original code is MIT licensed. The creative workspaces work without an AI account.

Install the Linux x86_64 release or download the macOS Apple silicon disk image or Windows x64 installer using the button below. You can also build from the repository. Linux requires a working graphics driver; source builds also need Rust and the GPUI system libraries; Windows source builds require the MSVC Rust toolchain and Visual Studio C++ Build Tools; macOS packaging requires Rust and the standard icon tools.

Choose a workspace from Home: Photo opens an image, Paint starts a canvas, and Library opens your photo catalog. Design and Diagram offer templates or a Blank document. You can also press Ctrl + N (Cmd + N on macOS) or select + beside the tabs to open New document. Choose Blank canvas to set your own size and background, or Import photo… to open an image. Save editable work before exporting a copy for sharing.

Linux also has a local Flatpak build via scripts/build-flatpak.sh, requiring Flatpak and flatpak-builder. Its sandbox cannot use converters installed on the host. For Windows source builds, scripts/build-windows.ps1 builds an executable; add -Package after installing the documented packaging tools for an NSIS installer. Local Windows builds are unsigned; local macOS builds are signed ad hoc for local use.

Compare workspaces / Which one do I use?

Each workspace has its own tools. Library catalogues and develops photos, including camera RAW. Photo retouches and composites. Paint draws and paints with brushes. Design lays out posts, print, and presentations. Diagram builds structured flowcharts and architecture diagrams. Every workspace has a reference guide and a short first-project tutorial.

RAW files always open in Library Develop. Choose Edit in Photo… to continue in layers. Photo and Paint share one document; Ctrl + Alt + Shift + D switches between them.

Photo / Retouch, composite, and refine

Develop camera RAW files in Library, then choose Edit in Photo… after the settings have saved. Photo receives the developed pixels in a new document for layered editing. Later Library adjustments do not update an existing Photo document; use Edit in Photo again to open a new version.

Open a photograph in Photo, then choose a tool and adjust its options. Use brushes and erasers for painting, clone and heal for retouching, or smudge, gradients, and liquify to reshape the image. Add a selection or mask when an edit should affect only part of the artwork.

The right dock includes Layers, Channels, and Paths. Use Ctrl + Shift + N (Cmd + Shift + N on macOS) to create a transparent layer; F7 opens Layers. Add groups, duplicate layers, and combine raster artwork with editable text and paths. The layer controls and Properties panel hold transforms, blending, and masks; use Window → Properties to open that panel.

Choose Grade (Shift + Q with the canvas focused) for exposure, curves, colour balance, and hue/saturation adjustment layers. Select an existing adjustment layer to edit its controls. Add references through the Ref (Reference) panel to keep an image beside your canvas; references belong to the open session and must be reattached after reopening.

Enhance and refine

The Enhance panel gathers one-click looks and tools for structure, glow, skin, sky replacement, relighting, and more. Filter tools remain editable on the layer; tools that use local models can add new layers and masks. Refine or remove the result as you continue editing.

Move and align artwork

Choose Move (V) to drag a selected layer or group. With the canvas focused, arrow keys nudge by one document pixel; Shift+arrow nudges by ten. These move artwork, while Hand and Rotate View change how you look at the canvas.

Paint / Brushes, references, and layers

Choose Paint in Home to create a canvas. Set its dimensions and background, give it a name, and select Create. Paint, erase, and smudge on separate layers so you can adjust individual parts of an illustration. Save your work as .ora to retain editable layers and history.

Use the Reference panel to keep a source image beside the canvas. References belong to the open session; reattach them after reopening. The Layers panel controls order, opacity, blending, and masks, just as it does in Photo.

Brush Library and Brush Studio

Open Brush library… from the Brushes tab of the brush panel to browse, search, pin, and organize brushes into sets and libraries. Double-click a brush or choose Brush Studio to edit its settings, shape and grain sources, or dual components. Try strokes on the Studio pad; Done publishes the draft and Cancel discards it without painting your document.

Native .embrushes packages retain editable settings and source assets. Imported .brush, .brushset, .brushlibrary, and supported sampled-tip .abr files are conversions with format-specific limits; they do not promise identical brush behavior or complete archive compatibility.

Use the brush size and opacity controls for quick changes. Hand, zoom, and Rotate View change your view of the canvas; Move changes the artwork itself.

Library / Organize, develop, and export

Open Library from Home or the top bar. Import local folders into the catalog; files remain at their original paths. Create collections, search names and keywords, and filter by ratings, flags, or colour labels.

The Library panel

Browse Catalog, Folders, and Collections on the left. The photo grid and filmstrip keep your selection in view; the right panel holds Quick Develop, Metadata, Keywording, and export settings. Use Panels and Filmstrip at the top to adjust the workspace.

Find the photographs you want to keep

Click a photo to select it, Shift-click for a range, or Ctrl/Cmd-click to toggle individual selections. With the grid focused, use 0–5 for ratings and P / U / X to pick, unflag, or reject. Use G for the grid, E for loupe, D for Develop, or Enter to open the photograph in Photo.

Develop a set without overwriting originals

Use Quick Develop for a starting treatment, or open Develop for light, white balance, curves, colour, crop, and detail controls. Synchronize selected settings across photographs, or keep alternate treatments as virtual copies. RAW support depends on the camera and file; rendered JPEG, TIFF, PNG, and WebP photos can also use development sidecars.

Edits save to fingerprint-bound <original>.emulsion-raw.json sidecars after a short pause. Keep the source and sidecar together. Saved Develop history and named snapshots can be revisited; the original image is never overwritten. Save failures remain visible, and opening in Photo or exporting requires saved settings.

Add presets to Library

1. Select a photograph and open Develop.
2. Expand Presets in the left panel and choose Import preset pack…. Select a Lightroom .xmp or .lrtemplate file, an Emulsion preset .json, or a ZIP preset pack.
3. Choose a name under Imported presets to apply it to the selected photograph. Importing adds presets to the list; applying one is a separate step.
4. Turn on Before / After to compare the result, then fine-tune the Develop controls. Use Sync settings when you want to copy selected adjustments to other photographs.

Open Show import details to review compatibility notes. Supported adjustments are translated; proprietary Adobe/VSCO profiles and some settings are not reproduced, so imported looks can differ from Lightroom.

Prepare a delivery

Select photographs, choose an export preset, and set the destination. Export presets cover size, quality, depth, sharpening, and optional watermark settings. Export produces separate output files. To put the selected photographs on paper, choose Print selected… and review the print preview and layout. For portable backups of a collection, the .emulibrary format can include originals, sidecars, and supporting assets.

Design / Templates, layouts, and pages

Choose Design in Home. Browse templates for social graphics, print, invitations, and presentations, or select Blank document to choose a size and start empty. The Blank canvas tab offers the same custom setup. A template brings its authored size and editable content into the document.

Make the layout your own

Edit text, change shape fills and strokes, replace images in frames, and arrange objects with selection, alignment, and grouping controls. Responsive row, column, and grid layouts help organize related objects. Add or remove pages to build a series or presentation.

Save, present, and share

Save a multi-page .emu project to retain the editable pages. Present shows a Design project as slides; a separate presenter view can show notes and navigation. To share selected artwork, use Export → Export selected objects… for SVG, PDF, or PNG. Supported text and paths retain vector geometry; effects that require rendering are reported by the exporter. To export every page, choose File → Export…, then Project export, for PNG, JPEG, or SVG pages or a Print PDF with optional bleed. Keep the native project for future edits.

Diagram / Shapes, connections, and structure

Choose Diagram in Home. Start with a flowchart, org chart, timeline, or concept map, or select Blank document for an empty canvas with your own dimensions. You can also switch to Blank canvas in New document.

Build and explain the structure

Add shapes and editable text, then connect objects through their ports. Bound connectors follow the objects they connect. Choose straight, orthogonal, curved, or cyclical routes and add labels to describe relationships. Use containers to group related parts, and alignment controls or auto-layout to keep the drawing readable.

Browse Shapes, Templates, Containers, Themes, and Packs for reusable starting points, including AWS and Azure icon sets. Generate a diagram from text, CSV, Mermaid, or SQL with Generate from data. Use the object context menu to arrange, align, group, lock, or annotate the selection.

Keep the working diagram

Save a .emu project to retain editable pages, objects, and connections. Export an editable draw.io file, or PDF, SVG, PNG, or JPEG for sharing. Import draw.io, Visio, and Lucid files. Imported diagram formats have feature-specific limits; keep the source file and review the import report before relying on the conversion.

RAW in Library / Developing and saving

Opening a supported RAW file always enters Library Develop, which develops the sensor data rather than the embedded preview. Develop has twelve sections, including Basic, Tone Curve, Color Mixer, Color Grading, Detail, Lens Corrections, Calibration, Masking, White Balance, and Enhance. It also offers sensor denoise, highlight reconstruction, HDR merge, and panorama stitching. When the photo needs layers, selections, or retouching, choose Edit in Photo… to open the developed image in a new Photo tab.

Library saves Develop settings to <filename>.emulsion-raw.json beside the source without modifying it, with its own history and snapshots. Reopening the original restores these settings. Emulsion sidecars are not Adobe XMP. Keep them with the original when moving or backing up photos; rename the sidecar to match if you rename the photo. An invalid or mismatched sidecar produces an error instead of silently dropping your saved settings.

Older Photo projects with an embedded RAW recipe offer Develop in Library…. This creates an independent Library virtual copy carrying the recipe, including unsaved development settings, while leaving existing Photo layers and the original’s sidecar unchanged. For those projects, use Save as → .ora to preserve layers, history, and versioned RAW settings. Keep the original: the project stores a verified link, not an embedded RAW. If it has layers or named versions that a sidecar cannot preserve, Save also asks for a project. Use Locate original… if an identical source has moved. The project can reopen without its original, but changing RAW settings or exporting the linked RAW layer requires it. Painting directly on that layer detaches its RAW recipe; use a separate layer for retouching. If Save or Export reports that RAW development is still running, wait for the preview to finish and retry.

Camera support and colour reconstruction vary by source. Library keeps development settings and history with the source; save subsequent Photo layers in an ORA project.

Recipes and batch export

Open the dock’s Panels menu and choose Recipes. The Emulsion collection holds starter recipes, camera presets, and saved looks. Other collection chips open the community library, grouped by film simulation family. Use tags to narrow a collection; each library recipe retains its creator and source in its notes.

In Library, select the photographs you want to process. Search the recipe chooser by name or tag, or expand Category for a filter. Set the format and output folder in the right dock, then select Export in the top bar.

Use Fit image and the − / + controls to navigate the preview. Drag or scroll to pan; Ctrl/Alt/Cmd+scroll or pinch zooms around the pointer. Double-click to fit again. Preview zoom uses a rendered image up to 1100 pixels; export retains its own output settings. Selecting another photo resets the view; changing the recipe keeps the view for that photo.

Printing / Photographs, pages, and PDFs

Choose File → Print… from an open document, or select photos in Library and choose Print selected…. The shortcut is Ctrl+P on Windows and Linux, or Cmd+P on macOS. Printing captures the current edited appearance, including unsaved document changes or Library Develop settings and the selected recipe. It does not save drafts, flatten the project, or change original photos.

Choose the paper and layout

Select an installed printer, paper size, orientation, and margins. Fit keeps the whole image; Fill crops to the available area; Actual size uses the document’s dimensions and resolution, with a scale control. Canvas zoom does not affect print size. Arrange one image per sheet, a contact sheet, a repeating grid, or a tiled poster. Preview each sheet and check cropping warnings before printing.

Save a PDF

Choose Save PDF… to create a file instead. The default Document page sizes · no scaling layout preserves the selected pages’ physical dimensions and orientation. Choose a sheet layout for contact sheets or poster tiles. PDF output saves one set of the composed sheets.

Native printing adapters are included for Linux, macOS, and Windows; physical output and platform acceptance are still being validated. Printer capabilities depend on the installed driver, and the preview is not a colour proof. The full guide covers platform requirements, borderless sizes, bleed, crop marks, and colour management.

History, project files, and replay

Use undo, redo, and history branches to explore alternatives. Save an OpenRaster (.ora) project to retain editable work and history. Emulsion’s native data keeps text and paths editable; other OpenRaster readers can use the included layer previews. Newly saved native version 2 projects require an updated Emulsion build for native editing.

Open the dock’s Panels → Timeline, then choose Replay drawing to play the picture back from its history and export a GIF. Leaving Timeline stops playback and returns to the full document.

Save Design and Diagram pages in a .emu project, which retains each page’s native editable content and history. Library has its own saved development history and snapshots in sidecars. Export is a delivery step: keep the native project, or the photo originals with their sidecars, for future editing.

Bringing files in and sending them out

CMYK sources are converted to RGB for editing, with support depending on format and profile. CMYK PSD/PSB support is limited to the saved merged appearance for supported 8-bit files. Projects and exports retain RGB pixels, not CMYK ink separations. Formats without transparency composite over white.

Optional assistant and image generation

An assistant that uses editing tools

Install and authenticate a supported Claude Code, Codex, OpenCode, or Kimi Code CLI, then click Ask AI or press F1 (or Alt + F1) to open the Ask bar and select Assistant. Ask it to inspect the canvas, use a reference, build artwork, adjust colours, or automate a recipe. Review proposed document changes with Apply/Skip. Model access or a provider subscription is not bundled.

Emulsion connects its MCP server to the active app so the assistant can call editing operations directly. A connected MCP client lists the current catalog with tools/list. Starting emulsion mcp-serve alone still answers that request but cannot edit an open document without the app connection.

Generate an image or fill a selection

Open Settings with Ctrl + K (Cmd + K on macOS) and configure Image generation, then choose Local SD, OpenAI, or Google in the Ask bar opened by Ask AI or F1. Local SD uses an A1111/Forge API server. Cloud providers require their own API keys and separately billed access. Enter a prompt; generated results arrive as labeled raster layers you can hide or undo. With an active selection, generation uses the surrounding canvas as context.

Environment API keys take precedence over saved keys: OPENAI_API_KEY for OpenAI, and GEMINI_API_KEY before GOOGLE_API_KEY for Google. Cloud generation sends prompts and fill context to the selected provider. Save & test checks key/model access, not generation quota. A Google free_tier error with limit: 0 needs a billing or quota change for that API project; waiting for a retry timer does not add quota. Cancelling discards the result but does not guarantee cancellation of provider processing or charges. Attached references are available to Assistant; image modes use the prompt and selected canvas context.

Optional subject selection, background removal, inpainting, face restoration, and upscaling require the relevant models or providers to be configured.

Workspace and shortcuts

Open the theme button (a sun or moon icon) in the top bar and choose Light or Dark. On Linux, choose Follow Omarchy in the same menu to follow your active Omarchy theme. Emulsion picks up theme changes live while it is running and shows the theme’s name in the menu item and the button’s tooltip. No hooks or system configuration changes are needed. Choose Light or Dark to return to Emulsion’s built-in palette. The canvas surround stays neutral, and theme changes never alter your artwork’s pixels. The current interface uses compact chrome; switch between Photo, Paint, Library, Design, and Diagram from the top bar. Use Home to return to your projects.

Use the dock’s Panels menu for Navigator, Info, Recipes, Timeline, History, or Histogram. The Window menu also opens Properties, Adjustments, History, Info, Layers, Channels, and Paths. Tool buttons support Tab navigation and Enter/Space activation. Focused sliders accept arrows, Shift+arrow for larger steps, and Home/End for limits.

These are the default editor shortcuts. On macOS, Ctrl-based shortcuts also accept Cmd; Alt is the Option key. Bare tool keys apply when the canvas has focus; text fields retain typing behavior. Library has its own selection, culling, and preview controls described above.

F1 / Alt + F1

Toggle the Ask bar; select Assistant or an image provider

Ctrl + K

Settings, including the Shortcuts section

Shift + Q

Grade tool (canvas focused)

H / hold Space

Hand tool / temporary pan (canvas focused)

Z

Zoom tool; hold Shift or Alt to zoom out

R

Rotate View tool (canvas focused)

Ctrl + 0

Fit the editor image to the canvas

Ctrl + 1

Set editor zoom to 100%

Ctrl + +

Zoom in; Ctrl + = also works

Ctrl + −

Zoom out

[ / ]

Decrease / increase brush size (canvas focused)

Ctrl + Alt + I

Image size

Ctrl + Alt + C

Canvas size

Ctrl + Shift + N

New transparent layer

Ctrl + F

Search layers

Ctrl + Alt + Shift + D

Switch Photo / Paint mode

Tab

Hide / show panels (canvas focused)

F5 / F7 / F8

Brush Settings / Layers / Info

Ctrl + S

Save a project or eligible RAW sidecar

Ctrl + Shift + S

Save as

Ctrl + Alt + Shift + W

Export

Your bindings may differ. Open Settings → Shortcuts to see the effective bindings. Use open keymap file to edit overrides, then reload to apply them.

Help and further guides

The documentation index separates current user guides from dated reports and plans. Use the current guides for feature behavior; a backlog or benchmark report is not a promise of supported features.

Recover work and find your files

Home lists recovery copies left by other sessions and offers Open or Discard. Autosaves are recovery copies, not a replacement for saving your project. Settings, shortcut overrides, recipes, brush libraries, and recovery files live in Emulsion’s application data directory; its location depends on the platform and environment.

The files, folders, and environment guide covers paths, backups, command-line options, installer flags, and log capture. Saved API keys are unencrypted in settings.json; remove them before sharing that file with a bug report.

When something does not work

Use the troubleshooting guide for missing converters, RAW sidecar or original-file errors, undetected assistant CLIs, generation quotas, theme issues, and startup failures. For an undetected CLI, Settings offers a provider path field, use path, and detect again.

On Linux, a machine without usable hardware graphics needs an installed software Vulkan driver. Windows can fall back to WARP; macOS has no software fallback. GPU brush painting is experimental and opt-in. See the dedicated guides for renderer and compute controls.