Skip to content

Installation

Quick install

For users familiar with Python, neptoon can be installed directly using pip:

pip install neptoon

Optional dependency extras

The base install is kept small. Install extras when you need optional interfaces or data backends:

Extra Install command Use case
GUI pip install "neptoon[gui]" Streamlit graphical user interface.
SFTP pip install "neptoon[sftp]" Download raw logger files from SFTP before parsing.
NetCDF pip install "neptoon[netcdf]" NetCDF/xarray support for external gridded data where required.
Geospatial pip install "neptoon[geo]" Read local/remote raster products through neptoon.geo and write geographic calibration-sample HTML maps.
Spatial calibration pip install "neptoon[calibration-interpolation]" Interpolated station groundtruthing with vector/raster geo backends; ordinary kriging is implemented internally.
Roving geospatial pip install "neptoon[roving-geo]" Vector/OSM road data, building providers, and extended local grid backends for mobile CRNS.
Roving interpolation pip install "neptoon[roving-interpolation]" Optional kriging interpolation for roving products.
Roving maps pip install "neptoon[roving-maps]" Interactive Folium maps, static plots and notebook display helpers.
Roving WebGL pip install "neptoon[roving-webgl]" deck.gl WebGL 3D terrain without installing Plotly.
Roving terrain pip install "neptoon[roving-terrain]" Legacy Plotly 3D terrain renderer.
Complete roving pip install "neptoon[roving]" All optional roving geo/interpolation/map/terrain and NetCDF dependencies.
All extras pip install "neptoon[all]" GUI, SFTP, NetCDF, geospatial and roving optional dependencies.

With pipx, use the same extras in the package spec, for example pipx install "neptoon[gui]" or pipx install "neptoon[sftp]".

The GUI is currently maintained in neptoon tools GUI

The graphical user interface is currently maintained as a separate application, neptoon tools GUI. Use it online at https://neptoon.web.app.ufz.de/ without installing anything, or install it on your own computer as described in the README of the neptoon-tools-gui repository. Installing this GUI directly through the gui extra of neptoon will follow here soon.

We recommend installing neptoon in a dedicated environment to ensure reproducibility and prevent package conflicts. Below we show example environments with Python 3.11. You do not need to use exactly this version as long as you use Python >= 3.11.

Here are some example scripts to do this using mamba or conda:

# Create a new environment with Python 3.11
uv venv neptoon --python 3.11
# Activate the environment
source neptoon/bin/activate      # Unix/macOS
# or
neptoon\Scripts\activate       # Windows PowerShell/cmd
# Install neptoon
uv pip install neptoon

# Create a new environment with Python 3.11
mamba create -n neptoon python=3.11 ipykernel
# Activate the environment
mamba activate neptoon
# Install neptoon
pip install neptoon

# Create a new environment with Python 3.11
conda create -n neptoon python=3.11 ipykernel
# Activate the environment
conda activate neptoon
# Install neptoon
pip install neptoon

Jupyter integration

The Conda and Mamba commands above install ipykernel explicitly; it is not part of Neptoon's base dependencies. For a source checkout, launch the bundled notebooks without changing pyproject.toml with uv run --with jupyterlab jupyter lab examples/notebooks. See the examples for the available workflows.

Using pipx to install neptoon

For users who mainly use the CLI or GUI, pipx is a practical way to install Python command-line applications without managing a project environment manually.

Install pipx on your system

Here is how we can install pipx on your system.

# Install pipx
python -m pip install --user pipx
python -m pipx ensurepath

# Install pipx
python3 -m pip install --user pipx
python3 -m pipx ensurepath

Important

After installation, you'll need to restart your terminal/PowerShell for the changes to take effect.

CLI Installation Guide

If you want to use the command line interface to process your sites it is recommended to install neptoon using pipx. This means you have access to CLI commands in your terminal/shell.

pipx install neptoon

Update neptoon with pipx

When new versions of neptoon are pushed to pip (you can see what the latest version on pip is here), you might want to update your CLI version on your host machine. To do that run:

pipx install neptoon --force

Uninstall neptoon with pipx

If you need to remove neptoon from your system:

pipx uninstall neptoon

GUI Installation Guide

Neptoon includes a graphical user interface (GUI) for processing Cosmic-Ray Neutron Sensor data without writing Python code. This section covers installation and first setup for GUI users.

The GUI is currently maintained in neptoon tools GUI

The graphical user interface is currently maintained as a separate application, neptoon tools GUI. Use it online at https://neptoon.web.app.ufz.de/ without installing anything, or install it on your own computer as described in the README of the neptoon-tools-gui repository. Installing this GUI directly through the gui extra of neptoon will follow here soon.

1. Install neptoon

Once pipx is installed and your terminal has been restarted, install neptoon using:

pipx install "neptoon[gui]"

This command will:

  • Download the latest stable version of neptoon
  • Create an isolated environment for the application
  • Install all necessary dependencies

Same as above - if you want to update neptoon within pipx you just need to run:

pipx install "neptoon[gui]" --force

2. Launch the GUI

neptoon-gui

When you execute this command:

  • A local server will start automatically
  • The launcher should automatically start in a browser window
  • Your terminal will also display a URL (typically http://localhost:8501)
  • You can copy this URL and open it in your web browser

Development Version Installation

If you want to install the latest features (before they have been fully tested and integrated) you might want to install the development version of neptoon using:

pip install git+https://codebase.helmholtz.cloud/cosmos/neptoon.git@development

For a source checkout used to run tests or regenerate documentation SVG files, install the pip-compatible developer extra:

pip install -e ".[dev]"
python tools/documentation/generate_visual_workflow_figures.py

Warning

This option is mainly for testing unreleased changes. The development branch changes frequently and may contain bugs.