Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

ELNPack is a desktop app for creating ELN archives you can import into ELNs like eLabFTW. Everything runs locally—no network access required. This guide shows how to install, record an experiment, attach your data, and export the archive.

Tip

Do all of this entirely offline. Ideal for use in labs with limited network access:

Copy the ELN archive to a USB drive and import it into eLabFTW from another computer with proper network access.

Prerequisites

  • Prebuilt binaries are available for:
    • Windows 10+ on x86_64, and arm64
    • macOS on x86_64, and arm64
    • GNU/Linux on x86, x86_64, and arm64.
  • For other operating systems or architectures, you can build ELNPack from source.
  • For a full list of supported OS and CPU combinations, see Rust Platform Support.

Warning

Windows XP and earlier are not supported. Supporting very old and current operating systems at the same time is difficult due to missing APIs, libraries, and compiler support.

There is limited compiler support for Windows 7. You can try to build ELNPack for Windows 7 yourself.

What you can do

  • Set the experiment date/time.
  • Write experiment notes in the Markdown editors.
  • Add keywords to your experiment.
  • Describe your experiment using metadata. Import existing metadata from eLabFTW extra field JSON files.
  • Attach arbitrary files.
  • Export an ELN archive compatible with eLabFTW.

License

This User Guide is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

Install & Launch

Easiest: download the release binary

  1. Go to the project’s Releases page on GitHub.
  2. Download the asset for your platform (Windows, macOS, or Linux) and CPU (x86_64, i686, or aarch64/arm64).
  3. Extract the archive and run the executable.

Windows (10+)

Important

Binaries are not code-signed; if SmartScreen appears, choose “More info” → “Run anyway”.

  1. Download the Windows .zip (x86_64 or i686):
    • elnpack-x86_64-pc-windows-msvc.zip (64-bit)
    • elnpack-i686-pc-windows-msvc.zip (32-bit)
  2. Extract it (right-click → Extract All…).
  3. Double-click elnpack.exe.
    • If the Universal CRT is missing, install the latest VC++ Redistributable (x64 or x86).

macOS (Intel & Apple Silicon)

Important

Binaries are not code-signed; if Gatekeeper blocks execution, using “Open” once will allow it to run.

  1. Download the macOS .tar.gz matching your Mac:
    • Apple Silicon → elnpack-aarch64-apple-darwin.tar.gz
    • Intel → elnpack-x86_64-apple-darwin.tar.gz
  2. Double-click to extract (or run tar -xzf elnpack-*.tar.gz).
  3. In Finder, right-click the elnpack app/binary → Open → confirm.

GNU/Linux

  1. Download the Linux .tar.gz for your CPU (x86_64, i686, or aarch64):
    • elnpack-x86_64-unknown-linux-gnu.tar.gz
    • elnpack-i686-unknown-linux-gnu.tar.gz
    • elnpack-aarch64-unknown-linux-gnu.tar.gz
  2. Extract and run:
tar -xzf elnpack-<version>-<arch>-unknown-linux-gnu.tar.gz
cd elnpack-<version>
chmod +x elnpack
./elnpack
  1. Needs glibc ≥ 2.31 (e.g., Ubuntu 20.04+). On minimal systems ensure libc6, libgcc-s1, and libm exist.

Build from source

Prerequisites

Build & Run

Building and running ELNPack from source is straightforward. Ensure you have the prerequisites in place and follow these steps:

# Clone the repository
git clone https://github.com/Athemis/ELNPack.git && cd ELNPack
# Compile and run a debug build
cargo run
# Compile and run a release build
cargo run --release

Windows 7

Important

Windows 7 is a so-called Tier 3 build target, which means it is not officially supported by Rust. Our testing has shown that it is possible to build and run ELNPack on Windows 7, however there are some known issues with the Windows 7 build target (see below).

Furthermore, building requires a nightly toolchain.

The *-win7-windows-msvc targets can only be built on Windows and need the MSVC BuildTools. If you have problems compiling or running the produced binary, try installing an older version of the BuildTools such as MSVC v140 - VS 2015 C++ build tools (v14.00) from the installer. Make sure to install the Windows SDK as well.

Unfortunately, the *-win7-windows-gnu targets which in theory would allow cross compilation and are not dependent on the MSVC BuildTools, produce binaries that are not compatible with Windows 7 due to the lack of certain system libraries.

# Install Rust Nightly Toolchain
rustup toolchain install nightly
rustup component add rust-src --toolchain nightly

# The MSVC targets can only be built on Windows and need the MSVC BuildTools:
# https://visualstudio.microsoft.com/en/downloads

# Build binaries; use your desired target
# cargo +nightly build -Z build-std --target x86_64-win7-windows-msvc
cargo +nightly build -Z build-std --target i686-win7-windows-msvc
Known Issues

Note

Limited testing was performed in virtualized Windows 7 systems due to a lack of physical hardware running this OS.

Some or all of the following issues may be solely caused by the state of virtualized graphics hardware driver support and may or may not be absent on real hardware.

  • The mouse pointer is off by a significant amount. While the application remains functional, you may have a hard time hitting the intended interface elements.
  • There were severe graphical distortions, when the window is not maximized. Work around this by maximizing the window before interacting with it.
  • The application will not launch without functional OpenGL support due to requirements of the underlying user interface library.

Quick Workflow

Follow these steps after your experiment to create an ELN archive you can import into eLabFTW or other ELN tools.

  1. Launch the app (cargo run or open your packaged binary).
  2. Write your notes in the Markdown editor.
  3. Add files in the Attachments list: raw data, images, scripts. Rename in-place if needed; the app will sanitize names for the archive.
  4. Set date and time in the Date & Time Picker. Use the original experiment time.
  5. Metadata and Keywords: add search terms and any instrument/sample fields you want to carry into your ELN.
  6. Click Save ELN archive, choose a destination folder. If the button is disabled, see Saving ELN Archives for the required fields.
  7. You now have an ELN archive on disk. Everything above works fully offline; import it later into your ELN (e.g., eLabFTW) once you are back online or transferred the ELN archive to a computer with an internet connection.

UI Overview

ELNPack UI overview

Key areas on the screen:

  1. ELN export controls: Switch between export formats of the main text HTML (default) and Markdown; Button to save the final ELN archive.
  2. Title: enter a short title.
  3. Type: choose the entry type (Experiment/Resource). Defines the type of the entry when imported into eLabFTW.
  4. Performed at: set date, time, and timezone (local time shown; stored as UTC).
  5. Main text: editor with toolbar for headings, emphasis, lists, links, code, superscript/subscript, tables, and math.
  6. Keywords: add comma-separated keywords via the dialog.
  7. Metadata: add structured metadata; import from eLabFTW extra fields JSON or create from scratch. Will be exported as eLabFTW compatible extra fields in the final ELN archive.
  8. Attachments: attach files to the archive. Filenames will be automatically sanitized and checked for duplicates. File content is hashed and checked for integrity and possible duplicates.

Markdown Editor

Markdown Logo

  1. Toolbar buttons insert Markdown at the cursor. From left to right:
    • Headings (Dropdown): # H1…# H6
    • Bold: **bold**
    • Italic: *italic*
    • Strikethrough: ~~strikethrough~~
    • Underline: __underline__
    • Code (Dropdown): inline and block code
    • Lists (Dropdown): * list item and 1. numbered list item
    • Links: [link text](url)
    • Blockquote: > blockquote
    • Images: ![alt text](url)
    • Tables: | header | header |…| row | row |
    • Horizontal Rule: ---
    • Math (Dropdown): inline $\math$ and block $$\math$$
  2. Use the editor for the experiment description, steps, and results. The resulting Markdown is by default converted to HTML when exporting the ELN archive.

Tip

  • You can use all features of CommonMark with some additional Markdown extensions like tables and math.
  • Use raw HTML in the Markdown code for more advanced formatting. Keep in mind though that HTML is sanitized when exporting the ELN archive to prevent XSS attacks which may remove potentially unsafe HTML tags (e.g., <script>).

Note

Currently the image insertion feature is ignorant of your file attachments. You can however use it to reference external images by providing their URLs.

Attachments

File Attachment

  1. Click Add files to open the file picker. Select all files you want to attach.
  2. A thumbnail will be shown for each file if possible.
  3. Use the Edit button to rename files directly from the list.
  4. If a file has been automatically renamed, this will be indicated by a warning icon. Hover the icon to see the original name.
  5. To delete files, click the Delete button next to each file.
  6. Beneath the filename, additional information such as file size, MIME type and SHA256 hash are displayed.

Tip

Files are hashed twice: first when adding an attachment, and again when saving the ELN archive. If the hashes do not match, an error message is shown.

This helps ensure that files are not modified in between and that the file saved in the archive is identical to the one you attached.

Keywords

Keywords

  1. Add short search terms (e.g., technique, instrument, sample ID) to make entries easier to find after import.
  2. Delete by clicking the trash icon.
  3. Edit inline by clicking on the keyword.

Tip

  • Comma-separated import is supported by pasting a list: microscopy, TEM, project A.
  • Keywords are automatically deduplicated.

Metadata

Metadata Overview

  1. Add groups and metadata fields by clicking the respective buttons.
  2. Edit existing groups or delete them.
  3. Fill in the fields with appropriate values.
  4. Edit or delete fields. This includes changing the label or options.

Tip

Field types cannot be changed after creation. To change a field type, you must delete the field and recreate it with the desired type.

Edit field properties

Edit metadata field

Here you can change the title (1) and description (2) of a metadata field. You can also choose whether the field is required, read-only and other settings which are specific to the field type (3). In some cases such as selection fields or numeric fields, options can be added or removed (4).

Finally, you can also change the assigned group of the field (5).

Click Save to apply your changes.

Date & Time Picker

Date & Time Picker

  • Pick the calendar date and clock time of the experiment.
  • You can click on the Now button to use the current date and time.
  • The chosen value is stored in the archive metadata.
  • During a later ELN import, this exact timestamp is used as creation date.

Tip

Backfill older experiments by setting the original date and time.

Saving ELN Archives

  1. Click Save ELN archive in the top right corner.
  2. Choose a destination folder for the archive.
  3. Wait for the confirmation message in the bottom status bar.

Tip

If the Save ELN archive button is disabled, ensure you have entered a title, date/time and at least a short description. Also make sure all attachments have unique names (no flagged duplicates).