marimo sur VPS : des notebooks Python réactifs en self-hosted

Pourquoi un notebook réactif sur votre propre serveur

Dans Jupyter, l'ordre d'exécution dépend de vos clics : une variable redéfinie plus bas, une cellule oubliée, et les résultats affichés ne correspondent plus au code. Le fichier .ipynb, du JSON chargé de sorties, se relit mal en revue de code et produit des conflits Git à chaque exécution.

marimo analyse les dépendances entre cellules. Quand une cellule change, toutes celles qui en dépendent sont recalculées, et seulement elles. Le notebook est un fichier Python ordinaire : git diff le lit, python notebook.py l'exécute.

L'héberger sur votre VPS, c'est garder les données sur un serveur que vous contrôlez, donner à toute l'équipe le même environnement depuis un navigateur et choisir la mémoire et le processeur dont vos calculs ont besoin.

Ce que marimo apporte

Exécution réactive — une cellule modifiée recalcule celles qui en dépendent, sans état caché.
Fichiers .py — des notebooks lisibles, versionnables dans Git et exécutables comme scripts.
Éléments d'interface — curseurs, menus, tableaux et graphiques reliés aux variables Python.
Notebook vers application — marimo run sert un notebook en lecture seule, code masqué.
Migration depuis Jupyter — marimo convert transforme un fichier .ipynb.
Image « data » officielle — pandas, polars, numpy et altair préinstallés.

marimo, Jupyter et code-server

Faites défiler le tableau

	marimo	JupyterLab	code-server
Format du notebook	Fichier .py	Fichier .ipynb (JSON)	Fichiers du projet
Ordre d'exécution	Réactif, par dépendances	Manuel, au clic	Selon le script lancé
Relecture dans Git	Diff Python lisible	Diff JSON avec les sorties	Diff du code
Publier en application	Oui, `marimo run`	Extensions tierces	Non
Usage idéal	Analyse et outils internes en Python	Écosystème de noyaux varié	Développement logiciel complet

Prérequis

Un VPS Ubuntu 24.04 avec 2 Go de RAM et 20 Go de disque (prévoyez davantage de mémoire si vous chargez de gros jeux de données), Docker et le plugin Compose installés, et un accès root en SSH. Un sous-domaine (par exemple notebooks.example.com) pointant vers le VPS est utile pour l'accès HTTPS, mais pas indispensable : un tunnel SSH suffit pour travailler seul.

Installer marimo avec Docker Compose

01
Préparer le répertoire et le mot de passe
Créez le répertoire de l'application et un fichier .env qui porte le mot de passe de l'éditeur.
```
mkdir -p /opt/marimo && cd /opt/marimo
echo "ADMIN_PASSWORD=$(openssl rand -base64 24 | tr -d '/+=')" > .env
chmod 600 .env
```

Écrire le fichier compose

Créez compose.yaml. L'image officielle « data » contient déjà les bibliothèques d'analyse. Le port n'est publié que sur la boucle locale, et le mot de passe est transmis par un fichier plutôt que par la ligne de commande.

services:
  marimo:
    image: ghcr.io/marimo-team/marimo:0.25.2-data
    restart: unless-stopped
    ports:
      - "127.0.0.1:2718:8080"
    environment:
      ADMIN_PASSWORD: ${ADMIN_PASSWORD:?ADMIN_PASSWORD requis}
    command:
      - sh
      - -c
      - umask 077 && printf %s "$$ADMIN_PASSWORD" > /tmp/marimo-password && exec marimo edit --headless --skip-update-check --host 0.0.0.0 -p 8080 --token-password-file /tmp/marimo-password /app
    volumes:
      - marimo-data:/app
volumes:
  marimo-data: {}

Démarrer et vérifier

Lancez la pile, puis interrogez la sonde de santé : elle doit répondre 200.

docker compose up -d
docker compose ps
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:2718/health

Publier l'éditeur en HTTPS

marimo dialogue avec le navigateur par WebSocket : le vhost nginx doit transmettre les en-têtes Upgrade et Connection, sinon l'éditeur s'affiche mais les cellules ne s'exécutent jamais.

server {
    server_name notebooks.example.com;
    location / {
        proxy_pass http://127.0.0.1:2718;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
    }
}

certbot --nginx -d notebooks.example.com

Pas de domaine ? Passez par un tunnel SSH

L'éditeur exécute du code Python avec les droits du conteneur : ne l'exposez jamais sans mot de passe. Pour travailler seul, inutile de le publier — un tunnel SSH ouvre l'éditeur sur http://localhost:2718 depuis votre poste.

ssh -L 2718:127.0.0.1:2718 root@<vps-ip>

Sécuriser l'éditeur

Un éditeur marimo ouvert donne à quiconque y entre la possibilité d'exécuter du Python sur votre serveur : c'est sa raison d'être, et c'est ce qui impose quelques règles simples.

Un mot de passe long et unique. Celui du fichier .env est tiré au hasard ; ne le remplacez pas par un mot de passe que vous utilisez ailleurs, et changez-le si vous le communiquez à un collaborateur qui quitte le projet (modifiez .env, puis docker compose up -d).

Un port qui reste local. Le compose publie le port sur 127.0.0.1 uniquement : depuis Internet, seul nginx en HTTPS y donne accès. Ne remplacez jamais cette adresse par 0.0.0.0.

Pas de secrets en clair dans les notebooks. Un notebook est un fichier Python versionné : une clé d'API écrite dans une cellule finit dans l'historique Git. Lisez-la plutôt dans une variable d'environnement ajoutée au compose, ou dans un fichier hors du dépôt.

Des journaux à surveiller. Au démarrage, marimo affiche son adresse d'accès dans docker compose logs, mot de passe compris : ce journal reste sur votre VPS, mais ne le collez pas tel quel dans un ticket ou une discussion.

Votre premier notebook réactif

Connectez-vous avec le mot de passe du fichier .env. L'éditeur ouvre le dossier /app, qui contient déjà les tutoriels officiels. Créez un notebook, puis deux cellules : la première définit un curseur, la seconde filtre un fichier CSV avec sa valeur. Déplacez le curseur : la seconde cellule se recalcule seule.

import marimo as mo
import polars as pl

seuil = mo.ui.slider(0, 1000, value=100, label="Montant minimum")
seuil

ventes = pl.read_csv("data/ventes.csv")
ventes.filter(pl.col("montant") >= seuil.value)

Lire vos données : CSV, Parquet et API

L'image « data » couvre l'essentiel d'une analyse sans rien installer. pandas lit les fichiers CSV, Excel et JSON ; polars lit CSV et Parquet très rapidement et sait traiter des fichiers plus gros que la mémoire en mode paresseux ; altair trace des graphiques interactifs qui s'affichent directement sous la cellule.

Déposez vos fichiers dans le dossier /app/data du volume, par scp vers le VPS puis docker compose cp, ou téléversez-les depuis le panneau de fichiers de l'éditeur. Pour une API, la bibliothèque standard de Python suffit à télécharger un JSON, que pandas ou polars transforment ensuite en tableau.

Chaque résultat de cellule est un objet vivant : un DataFrame s'affiche en tableau triable et filtrable, et la sélection faite dans un tableau ou un graphique peut alimenter la cellule suivante. C'est ce mécanisme qui transforme une exploration en outil réutilisable.

Transformer un notebook en application

Un notebook muni d'éléments d'interface est déjà une application. La commande marimo run le sert en lecture seule : les visiteurs manipulent les curseurs et les menus, sans voir ni modifier le code. Publiez ce second port derrière son propre vhost, protégé comme l'éditeur.

docker compose exec marimo marimo run /app/rapport.py --host 0.0.0.0 -p 8081

Vos notebooks Jupyter existants se convertissent en une commande ; relisez ensuite les cellules qui redéfinissaient une même variable, que marimo refuse par conception.

docker compose exec marimo marimo convert /app/ancien.ipynb -o /app/nouveau.py

Travailler à plusieurs sur les mêmes notebooks

Un serveur marimo est un éditeur partagé : toutes les personnes qui ont le mot de passe voient les mêmes fichiers. Pour une petite équipe, la règle la plus simple est un notebook par personne et par sujet, et un dépôt Git dans /app pour garder l'historique.

Parce que chaque notebook est un fichier .py, les outils habituels du développeur s'appliquent : git diff montre exactement quelle cellule a changé, une demande de fusion se relit comme du code, et un linter ou un formateur Python s'exécute dessus sans adaptation. Un notebook peut même être importé comme module ou lancé en script dans une tâche planifiée, pour produire chaque nuit le même rapport.

Dimensionner le VPS

marimo lui-même est léger ; ce sont vos données qui fixent la taille du serveur. Comptez 2 Go de RAM pour explorer des fichiers de quelques centaines de mégaoctets avec pandas, et montez à 4 ou 8 Go si vous chargez des jeux de données plus volumineux ou si plusieurs personnes travaillent en même temps. Le processeur compte surtout pour les calculs lourds : polars exploite tous les cœurs disponibles. Prévoyez enfin assez de disque pour l'image (environ 400 Mo) et pour vos fichiers de données, qui grossissent plus vite que les notebooks.

Sauvegarde et mise à jour

Les notebooks vivent dans le volume marimo-data. Le plus sûr est de versionner /app dans un dépôt Git ; à défaut, archivez le volume régulièrement.

docker run --rm -v marimo_marimo-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/marimo-$(date +%F).tar.gz -C /data .

Pour mettre à jour, changez l'étiquette de l'image dans compose.yaml en lisant d'abord les notes de version du projet, puis lancez docker compose pull && docker compose up -d. Les notebooks, simples fichiers .py, ne sont pas touchés.

Installation en un clic depuis le Marketplace ServOrbit

Sur un VPS ServOrbit, marimo s'installe depuis le Marketplace de votre espace client : le script déploie le conteneur officiel, génère le mot de passe de l'éditeur et crée le volume des notebooks. Le mot de passe s'affiche dans votre espace client. Attachez un sous-domaine de l'un de vos domaines, ou le sous-domaine gratuit du VPS, pour ouvrir l'éditeur en HTTPS ; sans domaine, le tunnel SSH décrit plus haut fonctionne tel quel, avec le port affiché dans votre espace client.