How to Set Up Your First Reference Workspace in refern (2026)

Setting up a reference library in refern takes about 10 minutes. Point refern at an existing folder, let it index your files in place (nothing is copied or moved), then add tags, organize folders, and save a smart folder. Here is the complete walkthrough.

The pain that brings most people to refern is the same: reference images scattered across Downloads, project folders, desktop, and half a dozen browser bookmarks folders. You want one place to search, browse, and relate them, but you do not want to reorganize your entire drive or let an app make a second copy of everything.

refern handles this differently from tools like Eagle (which copies every file into a proprietary .library folder, doubling disk usage) or TagStudio (which is free and indexes in place but is still in alpha and has no canvas or capture tools). refern indexes your folder in place, stores a small SQLite sidecar next to your originals, and never touches the files themselves.

This guide walks through every step of the first-run setup: creating a workspace, watching the index run, organizing what you have, and setting up the tools that save the most time.

Before you start

What you need:

• refern installed (download at refern.app, free 30-day trial, no account required)
• A folder on your computer, external drive, or network path that already contains reference images

What you do not need to do first:

• You do not need to reorganize your existing folder structure before importing. refern reads your folder tree as-is.
• You do not need to create a new blank folder. Using an existing folder is the intended workflow.
• You do not need to be online. refern works fully offline.

Step 1: Create your first workspace

Open refern. On the first launch you will see the workspace selector screen (the one-screen overview of all your workspaces, which stays accessible later via the workspace switcher in the top bar).

Click "New workspace". A file picker opens. Navigate to the folder you want to index and click Select. This is your workspace root.

Important: pick the broadest folder that makes sense for a single project or collection. If you keep all your reference images under Documents/References/, point refern there. If you keep them split across multiple top-level folders on different drives, create one workspace per folder and switch between them. Each workspace keeps its own index sidecar (refern-db.sqlite) inside the folder you chose, so the workspace travels with the folder.

Name the workspace something descriptive. Then click Create.

Step 2: Watch the index run

After creating the workspace, refern immediately starts scanning. A progress card at the bottom of the screen shows the phases:

1. Scanning - refern walks the folder tree and discovers every image, video, PDF, and canvas file.
2. Thumbnails - refern generates WebP thumbnails for each file and stores them in a refern-thumbnails/ subfolder inside your workspace folder.

You do not need to wait for this to finish before browsing. The grid populates as thumbnails complete. For a folder with a few hundred files the whole process usually finishes in under a minute. For a large library (tens of thousands of files) it can take several minutes on first run.

While it runs, you will see a live count: files scanned, thumbnails done, estimated time remaining. If you close refern mid-index, the process resumes exactly where it stopped the next time you open that workspace.

What gets indexed: JPEG, PNG, GIF, WebP, SVG, HEIC, RAW formats, and many more image types. Video, PDF, and canvas (.refern-canvas) files. Creative source files like PSD, AI, Sketch, and Clip Studio files are indexed with full metadata but not rendered as previews. See refern.app for the full format list.

Step 3: Browse what you have

Once scanning starts, click through your folder tree in the left sidebar. Each subfolder of your workspace root appears as a folder in the sidebar. Select one to see its contents in the grid.

Use the layout controls at the top right to switch between masonry, justified, and horizontal grid layouts. Hover over any image to see a quick preview. Click it to open the full-size view and the metadata sidebar on the right.

Spend a few minutes browsing before you start organizing. You will quickly develop a sense of which files need tags, which folders need renaming, and where you want smart folders.

Step 4: Add tags

Tags are the fastest way to make your library searchable. In refern, tags are hierarchical: you can create a parent tag like Character and child tags like Character / Pose, Character / Lighting, Character / Expression. Searching for Character returns everything tagged with any child tag automatically.

To tag a file:

1. Click a file to select it.
2. In the metadata sidebar on the right, find the Tags field.
3. Type a tag name. If the tag already exists, it autocompletes. If it does not, press Enter to create it.
4. Press Tab to move to the next tag field, or click elsewhere when done.

To tag multiple files at once:

1. Select multiple files (click the first, then Shift-click or Cmd/Ctrl-click others).
2. The metadata sidebar shows bulk editing. Any tag you add applies to all selected files.

Tag macros let you create shortcuts that insert a group of tags at once. If you always apply Lighting / Rim, Lighting / Backlight, and Mood / Dramatic together, create a macro for that combination and insert all three in one step. Set up macros in Settings under the Tags section.

Tag hierarchy tips:

• Start with a few broad parent categories (subject matter, mood, medium, source).
• Add child tags as you encounter specific things that need them.
• You do not need to plan the full hierarchy upfront. refern lets you reparent and rename tags at any time.

Step 5: Organize your folder structure

If your existing folder structure already makes sense, you may not need to change anything. refern reflects your folder tree exactly.

If you want to reorganize, you can rename and move folders directly inside refern. Right-click any folder in the sidebar and choose Rename or Move. refern updates every file's path in the index automatically. Your files move on disk too, with the watcher paused so the disk change does not trigger a false "files changed" alert.

A few structural patterns that work well:

• Organized by subject: Characters, Environments, Props, Textures, Color Palettes. Good for concept art libraries.
• Organized by project: Project A, Project B, Archive. Good for freelancers with per-client work.
• Organized by source: Screenshots, Pinterest Saves, Purchased Assets, Original Scans. Good for mixed-source libraries.

You do not have to pick one pattern and stick to it. Tags handle cross-cutting organization (a file in Characters/ can also be tagged Mood / Melancholic and show up in a smart folder for mood research regardless of which folder it lives in).

Step 6: Create your first smart folder

A smart folder is a saved search. It behaves like a real folder in the sidebar but automatically collects every file that matches a set of filters. The contents update live as you add new files and tags.

To create a smart folder:

1. Click the + button next to Smart Folders in the sidebar, or open the Smart Folders section and click New smart folder.
2. Give it a name.
3. Add one or more filters. Common first smart folders:
   • Favorites - filter: is:favourite
   • High rated - filter: rating:>=4
   • Recent imports - filter: date added: last 7 days
   • Untagged - filter: tags: none (useful for finding files that still need tagging)
   • A specific subject - filter: tag: Character / Pose (shows every file with that tag, across all folders)
4. Save.

The smart folder appears in the sidebar. Click it any time to see the current live results.

Smart folders do not contain files in the filesystem sense. The files stay in their original folders. A smart folder is purely a view.

Step 7: Set a default import folder

When you drag images into refern, paste from the clipboard, or save from the browser extension, refern needs somewhere to put them. By default it places new files in an Unsorted folder at the root of your workspace.

To change this, go to Settings (gear icon, top right) and look for Default import folder. Select any existing folder in your workspace. From now on, new imports land there automatically.

If you use the browser extension a lot, consider creating a folder called Inbox or To Review as your default import destination. Clear it regularly by tagging and moving files to their permanent homes.

Step 8: Set up the browser extension (optional but recommended)

If you want to save images from the web directly into your library, install the refern browser extension for Chrome, Firefox, or Safari from refern.app.

Once installed:

1. Click the extension icon and connect it to your running refern desktop app.
2. Hover over any image on a web page to see the save button.
3. Right-click any image and choose Save to refern.
4. Use the extension panel to select which workspace folder to save into, add tags at save time, and batch-save multiple images from a page.

Images saved via the extension land in your workspace without copying to a browser download folder first. The source URL is stored automatically with each saved image, so you always know where it came from.

Common problems and fixes

The index is stuck or never finishes Close refern and reopen it. The index is crash-resumable: it picks up from where it stopped. If it stalls on a specific file (rare, usually a corrupt or very large file), that file will be skipped and the rest will continue.

I see a "files changed, resync" toast after moving files inside refern This is normal when you use refern's own folder operations. Dismiss the toast or click Resync if you moved files outside refern (using Finder, Explorer, or another app). Resync reconciles the index with what is actually on disk.

A file I know exists does not appear in the grid Check that the file format is supported. AVIF is not currently supported by refern's backend. Fonts and audio files are not indexed. If the file is a supported format, try opening the workspace folder and triggering a resync via the sidebar menu.

Thumbnails look blurry or are missing The thumbnail pipeline may still be running (especially for very large libraries). Wait for it to complete. If thumbnails are still missing after the pipeline shows as done, go to Settings and run Verify workspace to catch any stale index entries.

I want to start over with a fresh index Delete the refern-db.sqlite and refern-thumbnails/ folder from your workspace root. The next time you open the workspace in refern, it will rebuild from scratch.

Next steps

Once your first workspace is set up:

• Build your first canvas - drag images from the grid onto a new canvas to start a moodboard or reference board. See the canvas guide at refern.app to learn about layers, groups, and pin-on-top mode.
• Learn the search operators - type rating:>=4 tag:Character in the search bar to combine filters in one query. The full list of operators is in refern's documentation.
• Explore the relationship graph - once you have built canvases and used grouping, open the graph view (the icon in the top navigation) to see how your images, folders, canvases, and tags connect to each other.
• Compare tools - if you are coming from Eagle, refern can import your Eagle library with folders, tags, ratings, sources, and notes intact. See the refern vs Eagle comparison for the full migration walkthrough.
• Review the visual style reference - for team workflows, refern's metadata presets let you auto-apply tags, ratings, and descriptions to any file that lands in a specific folder.