Installation

MSNoise requires Python ≥ 3.10 and a database backend (SQLite for quick starts, PostgreSQL or MariaDB for production use). This page covers the recommended path — conda-forge + MSNoiseDB — and optional notes for advanced users who prefer to manage their own database server.

Step 1 — Install MSNoise 

We recommend Miniconda and a dedicated conda environment. All dependencies are available on conda-forge.

Create the environment 

Save the following as environment.yml — this is the exact file used by MSNoise’s own GitHub CI:

name: msnoise
channels:
  - conda-forge
dependencies:
  - numpy
  - scipy
  - obspy>=1.4.1
  - sqlalchemy
  - sqlalchemy-utils
  - flask
  - flask-admin<2
  - flask-wtf
  - flask-babel
  - markdown
  - wtforms<3.2
  - logbook
  - pytables
  - click
  - click-plugins
  - pandas
  - folium
  - pymysql
  - xarray
  - netCDF4
  - pooch
  - pip
  - pip:
      - git+https://github.com/regeirk/pycwt

Then create and activate it:

conda env create -f environment.yml
conda activate msnoise

Install MSNoise 

The latest stable release from conda-forge:

conda install -c conda-forge msnoise

Or directly from GitHub (development version, not recommended for production):

pip install git+https://github.com/ROBelgium/MSNoise.git

Verify the installation:

msnoise --version
msnoise utils bugreport -s -m

Step 2 — Set up a database with MSNoiseDB 

Setting up MySQL or PostgreSQL from scratch has always been a friction point for new users. MSNoiseDB eliminates that: it bundles a self-contained, user-run PostgreSQL server that requires no system privileges, no passwords, and no server administration.

Note

MSNoiseDB is the recommended database backend for all new MSNoise projects. SQLite remains available for quick local tests (see Advanced — SQLite (quick local tests only) below) but has limitations when running many parallel workers.

Install MSNoiseDB 

pip install msnoisedb

or via conda-forge (once available):

conda install -c conda-forge msnoisedb

See github.com/ROBelgium/msnoise-db for the full documentation.

Start the database server 

Important

MSNoiseDB creates its database files in the current working directory the first time it starts. Always run it from the same dedicated folder every time. If you start it from a different directory, it will create a new, empty database there instead.

Choose or create a permanent home for MSNoiseDB — separate from your MSNoise projects:

mkdir ~/msnoisedb
cd ~/msnoisedb
msnoisedb start

The first run initialises the PostgreSQL cluster inside ~/msnoisedb/. Subsequent runs just start the server. The command prints the connection details, for example:

MSNoiseDB started.
Host : localhost
Port : 5099

Keep this terminal open (or run it in the background) while MSNoise is processing. To stop the server:

cd ~/msnoisedb
msnoisedb stop

You can list or create databases at any time with:

msnoisedb list-db
msnoisedb create-db msnoise_myproject

Creating the database and initialising the project folder are covered in Initialize a Project.

Step 3 — Verify the installation 

Check that all required packages are present:

msnoise utils bugreport -s -m

No project folder is needed for this — it runs wherever you are.

Once satisfied, head to Initialize a Project to create your first MSNoise project and connect it to MSNoiseDB.

Advanced — SQLite (quick local tests only)

SQLite requires no server setup and is useful for exploring MSNoise on a laptop or running the test suite without MSNoiseDB:

mkdir ~/msnoise_sqlite_test
cd ~/msnoise_sqlite_test
msnoise db init   # choose sqlite when prompted

Warning

SQLite does not support concurrent writes. Running more than one worker (msnoise -t 2 cc compute) on an SQLite project will cause database lock errors. Use PostgreSQL via MSNoiseDB for any real processing.

Advanced — Self-managed MariaDB / PostgreSQL 

If your institution already runs a database server, or you need multi-user access to a shared MSNoise database, you can connect directly.

MariaDB / MySQL 

Create a database and user on your server:

CREATE DATABASE msnoise;
CREATE USER 'msnoise'@'localhost' IDENTIFIED BY 'secret';
GRANT ALL PRIVILEGES ON msnoise.* TO 'msnoise'@'localhost';
FLUSH PRIVILEGES;

Run msnoise db init and choose mysql with your server’s host, port, user and password.

PostgreSQL 

createdb msnoise

Then run msnoise db init and choose postgresql.

See About Databases and Performances for guidance on when a dedicated server pays off over MSNoiseDB.

Building this documentation 

conda install -c conda-forge sphinx sphinx-rtd-theme numpydoc sphinx-gallery
cd doc/
make html

The built documentation appears in doc/_build/html/.

To include the gallery examples, define:

export MSNOISE_DOC=/path/to/example/data