Miniflux: The Minimalist RSS Reader That Does One Thing Well

Most software accumulates features until it becomes bloated. Miniflux goes the opposite direction — it's an RSS reader that deliberately does less. Written in Go by a developer who believes software should be fast, focused, and free of unnecessary complexity.

Photo by Gabriel Heinzer on Unsplash

Miniflux is a self-hosted RSS and Atom feed reader with an opinionated minimalist philosophy. It checks feeds, displays articles, tracks what you've read, and lets you save favorites. No plugins. No themes. No customization beyond light/dark mode. It runs in about 20 MB of RAM and feels instant even on a Raspberry Pi.

Why Miniflux Instead of FreshRSS

Both are excellent self-hosted RSS readers, but they have different philosophies:

Choose Miniflux if you:

• Want the absolute minimum resource footprint
• Prefer keyboard-driven interfaces
• Value simplicity over customization
• Like opinionated software that makes decisions for you
• Want a single statically-compiled binary with no runtime dependencies (besides PostgreSQL)
• Read articles on the original website and just need a feed tracker
• Appreciate Go's performance and reliability

Choose FreshRSS if you:

• Want extensive customization options
• Need specific extensions (YouTube integration, advanced filters)
• Prefer visual customization (themes, CSS)
• Want maximum mobile app compatibility via Google Reader API
• Like exploring features and tweaking settings
• Are comfortable with PHP stacks

For most people who value speed and simplicity, Miniflux is the better choice. For power users who want maximum flexibility, FreshRSS wins.

Docker Compose Setup

Miniflux requires PostgreSQL (it doesn't support SQLite). This is intentional — the developer chose PostgreSQL for reliability and performance.

services:
  miniflux:
    image: miniflux/miniflux:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgres://miniflux:${DB_PASSWORD}@miniflux-db/miniflux?sslmode=disable
      RUN_MIGRATIONS: "1"
      CREATE_ADMIN: "1"
      ADMIN_USERNAME: admin
      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      BASE_URL: https://miniflux.yourdomain.com
      POLLING_FREQUENCY: "30"  # Check feeds every 30 minutes
      BATCH_SIZE: "25"         # Fetch 25 feeds per batch
    depends_on:
      miniflux-db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "/usr/bin/miniflux", "-healthcheck", "auto"]
      interval: 30s
      timeout: 5s
      retries: 3

  miniflux-db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - miniflux_db:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: miniflux
      POSTGRES_USER: miniflux
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U miniflux"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  miniflux_db:

Create a .env file with your passwords:

DB_PASSWORD=your-secure-db-password
ADMIN_PASSWORD=your-admin-password

Start it:

docker compose up -d

Visit http://your-server:8080 and log in with the admin credentials from your .env.

First-Time Setup

On first login:

1. Settings → Integrations — configure any third-party services
2. Settings → Sessions — set session lifetime (default: 2 days)
3. Add your first feed — click the "+" icon in the sidebar

That's it. Miniflux has almost no configuration. This is intentional.

Adding and Organizing Feeds

Subscribe to feeds

Click the + button in the sidebar, paste a feed URL:

• Blog: https://example.com/feed.xml
• YouTube: https://www.youtube.com/feeds/videos.xml?channel_id=CHANNEL_ID
• Reddit: https://reddit.com/r/selfhosted/.rss
• GitHub releases: https://github.com/user/repo/releases.atom
• Substack: https://newsletter.substack.com/feed

Miniflux auto-detects the feed format and starts fetching articles.

Categories

Organize feeds into categories (News, Tech, Personal, etc.):

1. Settings → Categories — create categories
2. When subscribing to a feed, assign it to a category
3. Click a category in the sidebar to view only those feeds

Categories are simple folders. No nested hierarchies. No tags. Just flat organization.

Feed discovery

If a website doesn't advertise its feed, Miniflux can auto-detect it:

• Enter the homepage URL when subscribing
• Miniflux scans for common feed URLs
• If multiple feeds exist, it prompts you to choose

Feed rules

Miniflux supports rules to filter articles:

• Block articles with specific keywords in the title
• Keep only articles matching certain keywords
• Automatically mark articles as read based on patterns

Go to a feed's settings and configure rules:

EntryTitle contains "sponsored"   → block
EntryTitle contains "giveaway"    → block
EntryContent matches "(?i)crypto" → mark as read

Rules use simple pattern matching or regex.

Keyboard Shortcuts

Miniflux is designed for keyboard-driven reading:

These shortcuts make reading hundreds of articles fast. No mouse needed.

Full-Text Article Extraction

Many feeds only provide article summaries. Miniflux includes a built-in scraper to fetch the full content:

1. Open an article
2. Press d (or click "Fetch original content")
3. Miniflux scrapes the original page and displays the full article

This works surprisingly well for most sites. When it fails (JavaScript-heavy sites, paywalls), you can configure custom scraping rules.

Custom scraping rules

Edit a feed's settings and add CSS selectors:

Scraper rules: article.content, .post-body

Miniflux uses these selectors to extract content from the original page.

User-Agent spoofing

Some sites block feed readers. Miniflux can spoof a browser User-Agent per feed:

User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)...

This bypasses basic blocking (though paywalls and bot detection are harder).

Integrations

Miniflux integrates with several third-party services:

Pocket

Save articles to Pocket for later reading:

1. Settings → Integrations → Pocket
2. Connect your Pocket account
3. Press s on any article to save it to Pocket

Wallabag / Instapaper / Notion

Similar to Pocket — save articles to your preferred read-later service:

• Wallabag: Self-hosted read-later service
• Instapaper: Cloud read-later service
• Notion: Save articles as Notion pages

Webhooks

Send article data to custom webhooks when new articles arrive:

1. Settings → Integrations → Webhook
2. Enter your webhook URL
3. Miniflux POSTs article JSON on new entries

Use this to trigger automation (send to Discord, archive to S3, run custom scripts).

Matrix / Telegram / Discord

Send notifications when new articles arrive in specific feeds:

1. Configure a webhook integration
2. Set the feed to trigger the webhook
3. Receive notifications in your chat platform

API Access

Miniflux has a clean REST API for building custom clients or automation:

Enable API access

1. Settings → API Keys
2. Generate a new API key
3. Use it in API requests

Example: Fetch unread articles:

curl -u "admin:YOUR_API_KEY" \
  https://miniflux.yourdomain.com/v1/entries?status=unread

The API returns JSON and supports full CRUD operations on feeds, categories, and entries.

Fever API

For compatibility with third-party mobile apps, Miniflux implements the Fever API:

1. Settings → Integrations → Fever API
2. Enable Fever and set a password
3. Configure your mobile app:
   • Server: https://miniflux.yourdomain.com/fever/
   • Username: Your Miniflux username
   • Password: Your Fever password

Compatible apps: Reeder (iOS), Unread (iOS), FeedMe (Android).

Google Reader API (limited)

Miniflux has partial Google Reader API support, but it's less complete than FreshRSS. Use the native API or Fever API for best compatibility.

Mobile Apps

Miniflux doesn't have an official mobile app, but you can use:

1. Web UI: Miniflux is responsive and works well on mobile browsers
2. Fever API apps: Reeder, Unread, FeedMe
3. Third-party native clients: Some community apps support Miniflux's API

Most users just use the web interface — it's fast and mobile-friendly.

Performance and Resource Usage

Miniflux is exceptionally lightweight:

| Component | RAM | CPU | Storage | |---|---|---| | Miniflux (Go binary) | 20-30 MB | Minimal (< 0.1 cores) | 10 MB | | PostgreSQL | 50-100 MB | Minimal | 100-500 MB | | Total | **70-130 MB** | < 0.5 cores | < 1 GB |

This runs flawlessly on a Raspberry Pi Zero 2 W. Startup is instant — the Go binary launches in milliseconds.

Storage depends on feed count and retention:

• 100 feeds, 90 days retention: ~200 MB database
• 500 feeds, 30 days retention: ~300 MB database

Database maintenance

Miniflux automatically cleans up old entries based on retention rules:

1. Settings → Feeds → select a feed
2. Set Keep entries: 90 days, 500 entries, or forever
3. Miniflux purges old entries during the next cleanup cycle

PostgreSQL handles vacuuming automatically with the default autovacuum settings.

Multi-User Support

Miniflux supports multiple users with isolated feed lists:

1. Settings → Users
2. Create a new user with username/password
3. Each user has separate feeds, categories, and read states

Users share the same Miniflux instance but see completely independent content.

OIDC authentication

For single sign-on with Authentik, Keycloak, or similar:

environment:
  OAUTH2_PROVIDER: oidc
  OAUTH2_CLIENT_ID: miniflux
  OAUTH2_CLIENT_SECRET: your-secret
  OAUTH2_REDIRECT_URL: https://miniflux.yourdomain.com/oauth2/oidc/callback
  OAUTH2_OIDC_DISCOVERY_ENDPOINT: https://auth.yourdomain.com/.well-known/openid-configuration

Users log in via your identity provider instead of Miniflux's local auth.

OPML Import and Export

Migrate from another RSS reader:

1. Settings → Import
2. Upload your .opml file
3. Miniflux imports all feeds and categories

Export your feeds:

1. Settings → Export
2. Download your OPML file

Regularly export OPML as a backup. It's a simple XML file with your full feed list.

Advanced Configuration

Miniflux is configured entirely via environment variables. No config files.

Polling frequency

environment:
  POLLING_FREQUENCY: "60"  # Check feeds every 60 minutes
  BATCH_SIZE: "50"         # Fetch 50 feeds per batch

Shorter intervals mean fresher content but more server load and feed provider requests. 30-60 minutes is reasonable for most use cases.

Proxy support

Route feed requests through a proxy:

environment:
  PROXY_URL: "socks5://proxy.example.com:1080"

Useful for bypassing geo-restrictions or accessing feeds through a VPN.

Custom HTTP client settings

environment:
  HTTP_CLIENT_TIMEOUT: "20"        # Request timeout in seconds
  HTTP_CLIENT_MAX_BODY_SIZE: "20"  # Max download size in MB
  HTTP_CLIENT_USER_AGENT: "Mozilla/5.0..."

These settings apply globally to all feed fetches.

Metrics endpoint

Miniflux exposes Prometheus-compatible metrics:

environment:
  METRICS_COLLECTOR: "1"
  METRICS_ALLOWED_NETWORKS: "192.168.1.0/24"

Scrape /metrics for monitoring feed fetch latency, error rates, database stats, etc.

Honest Limitations

• No extensions or plugins: Miniflux is intentionally inflexible. If you want features it doesn't have, you're out of luck.
• PostgreSQL required: No SQLite support. You must run a PostgreSQL container.
• Minimal UI customization: Light/dark theme only. No custom CSS or themes.
• Limited mobile app ecosystem: Fewer compatible apps than FreshRSS (which implements a more complete Google Reader API).
• Opinionated design: The developer rejects feature requests that conflict with the minimalist philosophy. This is intentional, but it frustrates some users.
• No automatic full-text extraction: You must manually press d per article. FreshRSS can auto-fetch full text via extension.

If you value simplicity and speed over flexibility, these aren't limitations — they're features.

Backup Strategy

1. OPML export: The most important backup. Export regularly.
2. PostgreSQL backup: pg_dump the database or back up the Docker volume.
3. Docker volume: docker compose down && tar czf miniflux-backup.tar.gz /var/lib/docker/volumes/miniflux_db

Restoring from OPML is trivial — deploy a fresh Miniflux instance and import.

The Bottom Line

Miniflux is for people who want an RSS reader that feels like a unix tool: fast, focused, and minimal. It doesn't try to be everything to everyone. It reads feeds, displays articles, and stays out of your way.

If you run other Go-based self-hosted services (Caddy, Traefik, Gitea), you'll appreciate the single-binary simplicity. If you've ever felt overwhelmed by software with too many options, Miniflux will feel refreshing.

FreshRSS is objectively more feature-rich. Miniflux is objectively faster and lighter. Choose based on whether you value flexibility or simplicity.

For what it's worth, the developer uses Miniflux daily and has been refining it for over a decade. It shows.

Resources

• Miniflux documentation
• Miniflux GitHub
• API documentation
• Miniflux demo — try it without installing (username: demo, password: demo)