beeref.org

BeeRef is a reference image viewer built around one idea: arranging and viewing images while you work, without the interface getting in the way. Its feature set splits into two groups — image manipulation (move, scale, rotate, crop, flip, mass-scale, mass-arrange) and workflow features that keep the window usable alongside your art program (text notes, always-on-top mode, hidden title bar). If your reference workflow is "collect images, arrange them, keep them visible while drawing," these features cover it. If you need layered editing or painting tools, BeeRef is not that.

Image manipulation features

BeeRef lists the following image operations:

• Move, scale, rotate, crop and flip images — individual transforms on any image you've placed on the board.
• Mass-scale images to the same width, height or size — normalizes a group of images to a common dimension, useful when references come from mixed sources at different resolutions.
• Mass-arrange images vertically, horizontally or for optimal usage of space — lays out a selection in a row, a column, or a packed arrangement that uses the available area efficiently.

The mass operations are the distinguishing part. Single-image transforms exist in most viewers; applying the same scale or the same layout to a whole set of references is what makes a large mood board or pose sheet manageable.

Window and workflow features

• Add text notes — annotate the board alongside your images.
• Enable always-on-top mode and disable the title bar — the BeeRef window floats unobtrusively above your art program, so references stay visible while you draw.

The always-on-top plus hidden-title-bar combination is the feature that defines the intended use case: BeeRef as a companion window, not a separate application you switch to.

The .bee file format

All images are embedded into the .bee file as PNG or JPG. The file is a SQLite database, with images stored in an sqlar table. That means you can extract them without BeeRef:

sqlite3 myfile.bee -Axv

Export options from inside BeeRef are planned, but the command-line extraction works independently of the application, so your images are not locked into the tool.

Choosing based on these features

Practical notes

Installation files for Windows, Linux and macOS come from the latest release; Linux builds target different Ubuntu versions and may work on other distributions with trial and error, and Linux users need to grant the file executable rights before running it. If something goes wrong, the log is available via Help → Show Debug Log, or on disk at C:\Documents and Settings\USERNAME\Application Data\BeeRef\BeeRef.log on Windows and /home/USERNAME/.config/BeeRef/BeeRef.log on Linux and macOS. BeeRef is published under the GNU General Public License v3.0.

BeeRef ships as a prebuilt file per operating system, so installation is mostly a download-and-run process. Get the file for your OS from the latest release, then follow the platform-specific step below. Linux users must set executable rights before running it; macOS users who hit launch problems should follow the detailed instructions linked from the release page.

Windows

1. Download the Windows file from the latest release.
2. Run it. No separate installer steps are described on the BeeRef page.

If BeeRef doesn't start, check the log at:

C:\Documents and Settings\USERNAME\Application Data\BeeRef\BeeRef.log

Linux

1. Download the Linux file from the latest release. The different Linux versions are built on different Ubuntu versions — they should work on other distros too, but you may have to try which one works.
2. Give the file executable rights before running it.
3. Run the file.

Optional — to make BeeRef appear in your app menu:

• Save the desktop file from the release section into ~/.local/share/applications
• Save the logo
• Adjust the path names in the desktop file to match where you installed BeeRef

If BeeRef doesn't start, the log is at:

/home/USERNAME/.config/BeeRef/BeeRef.log

macOS

1. Download the macOS file from the latest release.
2. Run it.

macOS X users who have problems running BeeRef should look at the detailed instructions referenced from the release page.

If BeeRef doesn't start, the log is at:

/home/USERNAME/.config/BeeRef/BeeRef.log

Verifying it works and troubleshooting

Once running, you can confirm the app is behaving by opening Help -> Show Debug Log to view log output. If BeeRef doesn't start at all, use the log file paths above for your platform.

What you get after install

BeeRef is a reference image viewer: you arrange reference images and view them while you create, with a minimal interface meant not to get in the way. Features include moving, scaling, rotating, cropping and flipping images; mass-scaling to the same width, height or size; mass-arranging vertically, horizontally or for optimal space usage; text notes; and an always-on-top mode with the title bar disabled so the window can float above your art program.

Note on the .bee file format: all images are embedded as PNG or JPG inside a sqlite database, stored in a sqlar table. You can extract them independently of BeeRef with:

sqlite3 myfile.bee -Axv

Export options from inside BeeRef are planned, but the sqlite command above always works.

BeeRef is published under the GNU General Public License v3.0.

BeeRef is a simple reference image viewer: it lets you quickly arrange reference images and view them while you create, in a minimal interface designed not to get in the way of your creative process. It is aimed at artists, designers, and anyone else who works while consulting a set of reference pictures. If you only need to look at one image at a time, a normal image viewer is enough; BeeRef is worth considering when you want many references arranged on screen next to your art program.

What BeeRef does

The core idea is a single canvas of reference images that stays open beside the tool you are actually working in. According to the project page, its features are:

• Move, scale, rotate, crop and flip images
• Mass-scale images to the same width, height or size
• Mass-arrange images vertically, horizontally or for optimal usage of space
• Add text notes
• Enable always-on-top mode and disable the title bar, so the BeeRef window floats unobtrusively above your art program

That last item is the feature that defines the workflow: instead of switching windows or alt-tabbing to a folder of references, you keep a floating, chrome-free board of images over your canvas.

Installation

BeeRef runs on Windows, Linux and macOS. Get the file for your operating system from the latest release.

• Linux: the different Linux versions are built on different versions of Ubuntu. They should work on other distros as well, but you might have to try which one works. Linux users need to give the file executable rights before running it. Optionally, if you want BeeRef to appear in the app menu, save the desktop file from the release section in ~/.local/share/applications, save the logo, and adjust the path names in the desktop file to match the location of your BeeRef installation.
• macOS: the page points macOS users to detailed instructions if they have problems running BeeRef.
• Windows: no extra steps are described beyond downloading the release for your system.

The .bee file format

When you save a board, all images are embedded into the .bee file as PNG or JPG. The format is a SQLite database, with the images stored in a sqlar table. That means you can extract them without BeeRef at all, using the SQLite command line program:

sqlite3 myfile.bee -Axv

Options for exporting from inside BeeRef are planned, but the command above always works independently of BeeRef — useful if you want your references back and the application is unavailable.

Troubleshooting

You can access the log output via Help -> Show Debug Log. If BeeRef doesn't start at all, the log file is at:

• Windows: C:\Documents and Settings\USERNAME\Application Data\BeeRef\BeeRef.log
• Linux and macOS: /home/USERNAME/.config/BeeRef/BeeRef.log

License and who it suits

BeeRef is published under the GNU General Public License v3.0. It fits best if you want a lightweight, always-available reference board that stays out of the way of your main creative application, and if you are comfortable installing a release manually — especially on Linux, where you may need to set executable rights and try a build that matches your distribution.

If BeeRef won't start, the first thing to check is its log file. When the app is running, you can open the log from Help -> Show Debug Log. If BeeRef doesn't start at all, you can't reach that menu, so you need to open the log file directly from your system:

• Windows: C:\Documents and Settings\USERNAME\Application Data\BeeRef\BeeRef.log
• Linux and macOS: /home/USERNAME/.config/BeeRef/BeeRef.log

Replace USERNAME with your actual user name. The log records what BeeRef did before it stopped, which is usually enough to tell whether the problem is a missing file, a permissions issue, or something in your system setup.

Reading the log

Open the file in any text editor. You are looking for the last lines before the app stopped, since those describe the step it failed on. Errors about missing libraries, unreadable files, or failed writes point to different fixes:

• A missing or unreadable file usually means the BeeRef download is incomplete or was moved after installation.
• A permissions error on Linux or macOS often means the executable bit was never set, or the app can't write to its config directory.
• A library or dependency error suggests the build doesn't match your system (see the Linux note below).

Common causes and what to check

Linux: the file isn't executable

BeeRef's Linux builds are distributed as files that need executable rights before they will run. If you skipped that step, the app simply won't launch. Set the permission, then try again.

Also note that the different Linux versions are built on different Ubuntu releases. They should work on other distributions, but you may have to try more than one build to find the one that runs on your system.

macOS: the app is blocked from running

macOS users who have trouble running BeeRef should follow the detailed instructions linked from the BeeRef site for their situation. This is the usual cause when the log is empty or the app never gets far enough to write one.

The log file doesn't exist

If there is no log at the path above, BeeRef likely never reached the point of creating its config directory. In that case, re-download the file for your operating system from the latest release and start from a clean copy.

A note on the .bee file format

If BeeRef starts but a specific .bee file won't open, the problem is in the file rather than the app. A .bee file is a SQLite database with the images stored in an sqlar table, so you can inspect or extract it independently of BeeRef:

sqlite3 myfile.bee -Axv

This works even if BeeRef itself is misbehaving, and it's a useful way to confirm whether the file is intact.

If the log doesn't explain it

Work through the basics in order: confirm you downloaded the build for your operating system, confirm the file has executable rights on Linux, and confirm the app can write to its config directory. If BeeRef still won't start, the log output is the detail to share when asking for help, since it shows exactly where startup stopped.

A .bee file is a SQLite database. Every reference image you add to a BeeRef board is embedded into that database as PNG or JPG data, stored in a sqlar table. Because the format is plain SQLite, you can extract your images without BeeRef at all, using the sqlite3 command line program.

What the format actually is

BeeRef saves your board as a single .bee file. Inside, it is not a folder of loose images or a proprietary binary blob — it is a standard SQLite database. That choice has a practical consequence: the file stays readable by ordinary SQLite tooling, independent of the BeeRef application.

The images themselves are embedded, not linked. When you add a reference image, its pixel data is written into the file as PNG or JPG. Moving or deleting the original image on disk does not break the board, and sharing a .bee file carries the images with it.

Where the images live inside the file

The embedded images are kept in a sqlar table. SQLite's sqlar extension is a convention for storing an archive — files with their names and contents — inside a SQLite database. BeeRef uses that table to hold your images.

You do not need to understand the table schema to get your images back. The archive layout is what makes the extraction command below work.

Extracting images without BeeRef

The documented method is the sqlite3 command line program:

sqlite3 myfile.bee -Axv

Here is what each part does:

• sqlite3 — the SQLite CLI, which you need installed separately.
• myfile.bee — the path to your BeeRef board file.
• -A — selects the sqlar archive mode.
• -x — extracts the archived files.
• -v — verbose output, so you can see what is being written.

The expected result is that the images stored in the board are written out as files in the current working directory. Because the command relies only on SQLite and the sqlar convention, it works regardless of whether BeeRef is installed or even still available — the site notes this "always works independently of BeeRef."

Exporting from inside BeeRef

Export options inside the application are planned but not yet available. Until they arrive, the sqlite3 command above is the reliable way to get images out of a .bee file. If you only ever open boards in BeeRef, you never need to touch the database directly.

Practical implications

• Backups are simple. A board is one file, so copying it preserves both layout and images.
• The file can grow large. Since images are embedded rather than referenced, a board with many high-resolution references produces a correspondingly large .bee file.
• You are not locked in. Any tool that can read SQLite or the sqlar table can reach your images, so the format does not trap your work inside one application.

If a .bee file ever fails to open, the site's troubleshooting guidance points to the debug log, reachable via Help → Show Debug Log, with the log file at C:\Documents and Settings\USERNAME\Application Data\BeeRef\BeeRef.log on Windows and /home/USERNAME/.config/BeeRef/BeeRef.log on Linux and macOS.