Getting Started#

Welcome to NexusLIMS! This guide will help you get up and running quickly.

Upgrading from v1.x?

See the Migration Guide guide for step-by-step instructions on migrating from NexusLIMS v1.4.3 to v2.0+.

Installation#

Prerequisites#

  • Python 3.11 or 3.12

  • Linux or macOS (Windows is not officially supported)

  • uv (recommended) or pip

Throughout the following sections, instructions are given for using uv, pip, and for a “from source” development installation. Most users will want to use the uv approach, as it will automatically use the correct python version and provides the most system integration and ease of use.

Install NexusLIMS#

Using uv tool, you can install NexusLIMS as an isolated command-line tool:

uv tool install nexuslims

This will install the nexuslims command directly onto your path, meaning it can be run from your terminal without needing to activate a virtual environment. Use nexuslims --help to see all available subcommands (e.g. nexuslims config edit, nexuslims build-records)

For more information on tools in uv, please see their documentation.

NexusLIMS can also be installed using the traditional pip approach. If using this method, it is recommended to install in an isolated virtual enviroment:

# 1. create a new virtual environment
python -m venv nexuslims-venv

# 2. activate the environment
source nexuslims-venv/bin/activate

# 3. install NexusLIMS:
pip install nexuslims

Using virtual environments

If you use the virtual environment approach, you will need to “source” the environment every time (step 2, above) before you will be able to run any NexusLIMS command line tools.

For contributors who want to modify NexusLIMS source code:

# Clone the repository
git clone https://github.com/datasophos/NexusLIMS.git
cd NexusLIMS

# Install with uv (includes dev dependencies)
uv sync

Using uv run

For development installs, you will need to prefix all NexusLIMS commands with uv run, from the project directory, since they will not be installed onto the path by default (e.g. uv run nexuslims config edit).

Verify Installation#

Check that NexusLIMS is installed correctly:

nexuslims --help

source nexuslims-venv/bin/activate
nexuslims --help

cd NexusLIMS
uv run nexuslims --help

You should see the help output for the NexusLIMS command-line interface:

Usage: nexuslims [OPTIONS] COMMAND [ARGS]...

  NexusLIMS command-line interface.

  Manage records, configuration, database migrations, and instruments.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  build-records  Process new NexusLIMS records with logging and email...
  config         Manage NexusLIMS configuration files.
  instruments    Manage NexusLIMS instruments.
  db             Manage NexusLIMS database.

Configuration#

Note

In all of the following examples, the nexuslims command is installed as part of the NexusLIMS package. How you invoke it depends on your installation type:

  • uv tool install: you can use the command as written, since uv puts it on your executable path during installation

  • pip install: activate your virtual environment first (source .venv/bin/activate), then run commands directly (e.g. nexuslims config edit)

  • uv source install: run the commands from the cloned NexusLIMS directory and prefix each command with uv run (e.g. uv run nexuslims config edit)

NexusLIMS requires configuration through environment variables, which are typically stored in a .env file.

Quick Start#

  1. Launch the interactive configuration editor, which provides an interactive way to customize your configuration, and will automatically save a .env file with your selected values:

    nexuslims config edit

    Tip

    For development installs from source, you can also copy the example file directly: cp .env.example .env and then edit it manually.

  2. At minimum, you’ll need to set:

    • NX_INSTRUMENT_DATA_PATH - Path to instrument data

    • NX_DATA_PATH - Path for NexusLIMS data

    • NX_DB_PATH - Path to SQLite database

    • NX_CDCS_URL, NX_CDCS_TOKEN - CDCS API credentials

    • NX_NEMO_ADDRESS_N, NX_NEMO_TOKEN_N - NEMO integration

  3. (Optional) Verify your configuration was loaded correctly:

    # Dump current config to see what NexusLIMS sees
# WARNING: Output contains live credentials - don't share publicly
nexuslims config dump

See also

For complete configuration documentation including all available settings, validation rules, and troubleshooting, see the Configuration guide.

For config management tools (dump/load) and debugging configuration issues, see Configuration Management.

Database Setup#

Initialize the Database#

NexusLIMS uses a managed SQLite databse to track instruments, sessions, and users. Before running the NexusLIMS record builder, you will need to initialize the database and add some instruments. The database tool will use whatever value you have set in the NX_DB_PATH varuable as the active database:

# Initialize new database with schema and migrations
nexuslims db init

This creates an appropriately-formatted database file at NX_DB_PATH. It will not have any instruments configured, but will have the correct structure.

Using a custom database path

If for some reason you would like to use a different database file than specified in your .env, you can do so by setting the NX_DB_PATH environment variable directly on the command line:

$ NX_DB_PATH=/path/to/other/database.db nexuslims db init

Configure Instruments#

For NexusLIMS to start building records, it needs to know about your instruments and where their data is stored. This is information is kept in the database created in the previous step.

To add, edit, and delete instruments, use the NexusLIMS interactive instrument manager:

nexuslims instruments manage

This launches a terminal UI with a table of all/any configured instruments. Use arrow keys to navigate, and the a key to add an instrument by filling out the interactive form.

See also

For complete documentation on configuring instruments, see the Instrument Management guide.

Quick Start#

Run the Record Builder#

Once configured, run the record builder:

# Full orchestration (recommended)
# Includes file locking, timestamped logging, email notifications
# by default, will only search for usage events that occurred in the past week
nexuslims build-records

# Dry-run mode (find files without building records)
nexuslims build-records -n

# Verbose output
nexuslims build-records -vv

For a detailed explanation of the record building workflow and session states, see Record building workflow and NexusLIMS Database.

Updating NexusLIMS#

Release notifications

To be notified of new NexusLIMS releases, watch the repository on GitHub (requires a GitHub account): go to github.com/datasophos/NexusLIMS, click Watch → Custom, and enable Releases.

Upgrade to the latest version with:

uv tool upgrade nexuslims

Activate your virtual environment, then upgrade with pip:

source nexuslims-venv/bin/activate
pip install --upgrade nexuslims

Pull the latest changes with git and sync dependencies:

cd NexusLIMS
git pull
uv sync

After upgrading, you may need to upgrade the database structure (check each version’s release notes for details). If necessary, run the folllowing to apply any pending database migrations to make your database compatible with the new version:

nexuslims db upgrade

To check whether migrations are needed without applying them, use:

nexuslims db check

Getting Help#