diff --git a/README.md b/README.md
index ac4a64e8619de0dbe88b28d9eb99f32b921ff8dc..a9f7b11ef3e837f7dff91a07161548855be57b71 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,28 @@
-Detector geometry tools
-----------------------------------
+# Detector geometry tools
+
+This package is a collection of tools implementing different small operations related to detector geometry, like reading Crystfel stream file, read motors data, plot some metrics, etc.
+
+This also contains the script to make report on geometry quality and push geometry to SPB repository. To use this script, try:
+```shell
+geomtools-push -h
+```
+
+
+## Installation
+
+If you are installing on Maxwell it may be convenient to start by loading `exfel_anaconda3` module:
+
+```
+module load exfel exfel_anaconda3
+```
+
+or you can use your own installation of python version 3.7 or later. Next:
+
+```
+git clone ssh://git@git.xfel.eu:10022/esobolev/geomtools.git
+cd geomtools
+python -m venv myenv
+source myenv/bin/activate
+pip install -U pip
+pip install .
+```