wiki/Catalogue-Self-Hosted/apps/app-pyshelf.md

---
title: pyShelf
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, books, ebook, server, terminal, python, self-hosted, calibre-alternative]
confidence: medium
contested: false
sources: [https://selfh.st/apps/?tag=books, https://github.com/th3r00t/pyShelf, https://noted.lol/3-self-hosted-ebook-hosts-and-readers/]
---

# 🐍 pyShelf

> **Serveur d'ebooks léger et terminal-first, sans dépendance X** : hébergez votre bibliothèque EPUB/MOBI, scannez récursivement vos dossiers, cherchez par fuzzy matching, téléchargez. Idéal pour les serveurs headless.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | [github.com/th3r00t/pyShelf](https://github.com/th3r00t/pyShelf) |
| **GitHub** | [th3r00t/pyShelf](https://github.com/th3r00t/pyShelf) |
| **Licence** | GPL-3.0 |
| **Langage** | Python 3, JavaScript (UI web) |
| **Étoiles GitHub** | 525 ⭐ |
| **Dernière MAJ** | 2025-08 (v0.8.0) |
| **Catégorie** | [[cat-books]] |

## 📝 Description

**pyShelf** est né d'une frustration exprimée dès le README : « Vous n'avez pas besoin d'un serveur X pour héberger un site web, des films ou des séries, alors pourquoi devriez-vous en avoir un pour héberger des ebooks ? ». L'auteur venait de Calibre, qu'il trouvait lourd à administrer sur un serveur sans interface graphique, et a décidé d'écrire un serveur de livres numériques **100% headless, sans dépendance X11**.

Concrètement, pyShelf propose un **scan récursif** de votre dossier `/mnt/books` (ou n'importe quel chemin configurable), extrait les **métadonnées** des fichiers EPUB/MOBI, **agrège les couvertures**, et expose une **interface web** minimaliste avec **recherche fuzzy** (par titre, auteur, tag) et **système de téléchargement**. Les **collections automatiques** sont générées à partir de la structure de dossiers (pratique si vous organisez déjà vos ebooks par auteur/série/genre).

L'installation se fait **en une ligne** : `curl -fsSL https://raw.githubusercontent.com/th3r00t/pyShelf/.../install.sh | sudo bash`, et pyShelf s'installe comme **service systemd** (`pyshelf.service`) avec activation automatique. Pas de Docker obligatoire, pas de base de données externe, pas de runtime exotique. C'est du **Python pur avec SQLite** : ça tourne sur n'importe quel Linux, même un Pi Zero.

**Points forts** : extrêmement léger, pas de Docker requis, pas de X11, installation one-liner, systemd natif, search fuzzy, collections auto par arborescence.

**Points faibles** : formats limités (EPUB/MOBI, pas de PDF/AZW3/CBR), pas d'OPDS, pas de lecteur intégré (uniquement téléchargement), pas de gestion de prêts/lecteurs multiples, pas d'auth utilisateur (mono-utilisateur), UI web très spartiate, roadmap (auth, OPDS, plus de formats) en suspens.

## 🚀 Installation

### Option recommandée : install one-liner + systemd

```bash
curl -fsSL https://raw.githubusercontent.com/th3r00t/pyShelf/refs/heads/master/install.sh | sudo bash
systemctl status pyshelf
```

Le script crée `/etc/pyShelf/config.json`, installe le service systemd et démarre pyShelf.

### Option Docker (manuelle)

Il n'existe **pas d'image officielle** sur Docker Hub, mais un `Dockerfile` maison se construit facilement :

```dockerfile
FROM python:3.12-slim
RUN apt-get update && apt-get install -y git curl && rm -rf /var/lib/apt/lists/*
RUN git clone https://github.com/th3r00t/pyShelf.git /app
WORKDIR /app
RUN pip install --no-cache-dir -r requirements.txt
EXPOSE 8000
CMD ["python", "-m", "pyShelf"]
```

```yaml
# docker-compose.yml
services:
  pyshelf:
    build: .
    container_name: pyshelf
    restart: unless-stopped
    volumes:
      - /mnt/books:/books:ro
      - pyshelf_data:/data
    ports:
      - "8000:8000"
    environment:
      - PYSHELF_BOOK_PATH=/books
      - PYSHELF_DATA_PATH=/data

volumes:
  pyshelf_data:
```

### Configuration

Le fichier `/etc/pyShelf/config.json` (ou `/app/config.json` en Docker) contrôle le chemin des livres, le port et la base SQLite.

## ⚙️ Configuration Initiale

1. **Modifier** `/etc/pyShelf/config.json` pour pointer sur votre dossier d'ebooks (`/mnt/books` par défaut).
2. **Redémarrer** : `sudo systemctl restart pyshelf`.
3. **Accéder à l'UI** : `http://IP_DU_SERVEUR:8000`.
4. **Tester la recherche** : `author:Tolkien`, `tag:fiction`, `title:"Hunt for Red October"`.
5. **Ajouter un reverse proxy HTTPS** (Caddy/Nginx) si accès distant.
6. **Sauvegarder** le volume `pyshelf_data` (SQLite + cache couvertures).

## 🔄 Alternatives

### Open Source
- **Calibre + Calibre-Web** — référence, plus complet, mais demande X pour l'admin
- [[app-kavita]] — moderne, multi-formats, lecteur intégré
- [[app-teemii]] — orienté manga, scraper intégré
- **COPS** (Calibre OPDS PHP Server) — léger, OPDS seulement
- **BicBucStriim** — Calibre sans Calibre, interface web minimale

### Propriétaires
- **Calibre (desktop)** — la référence, mais lourd
- **Kindle Cloud / Kobo** — clouds fermés
- **Google Play Livres** — écosystème Google
- **Apple Books** — écosystème Apple

## 🔐 Sécurité

- ⚠️ **Pas d'authentification native** : prévoir un reverse proxy avec Authelia/Basic Auth
- ✅ **Volume `books` monté en lecture seule** dans le conteneur
- ✅ **Pas de télémétrie**, projet 100% local
- ✅ **HTTPS obligatoire** si exposition WAN
- ⚠️ **Service systemd root** : à harden si multi-utilisateurs sur l'hôte
- ⚠️ **Mono-utilisateur** par conception
- ✅ SQLite local, pas de base réseau à sécuriser

## 📚 Ressources

- [GitHub th3r00t/pyShelf](https://github.com/th3r00t/pyShelf)
- [Reddit r/selfhosted — v0.6.0 Docker release](https://www.reddit.com/r/selfhosted/comments/ivjshf/)
- [Discord pyShelf](https://discord.gg/H9TbNJS)
- [Sponsor th3r00t sur GitHub](https://github.com/sponsors/th3r00t)

## Pages Liées

- [[cat-books]] — Catégorie Books
- [[app-calibre-web]] — Interface web Calibre
- [[app-kavita]] — Lecteur moderne multi-formats
- [[app-caddy]] — Reverse proxy HTTPS
- [[app-authelia]] — SSO pour ajouter de l'auth
- [[recettes-docker-compose]] — Templates Docker