Skip to main content

How to Self-Host Grocy: Home Inventory and Household Manager 2026

·OSSAlt Team
grocyhome-inventoryhouseholdself-hostingdocker2026

TL;DR

Grocy (MIT, ~7K GitHub stars, PHP) is a self-hosted household management system. It tracks your pantry inventory (what food you have, what's expiring soon), manages shopping lists (auto-populated from what you're running low on), tracks household chores and tasks, and integrates with recipe managers. There's no commercial equivalent — Pantry Check and other apps are missing Grocy's depth. Scan barcodes with your phone to add items, get notifications before food expires, and never run out of things you need.

Key Takeaways

  • Grocy: MIT, ~7K stars, PHP — pantry inventory, shopping lists, chores, barcode scanning
  • Stock tracking: Know exactly what you have and when it expires
  • Shopping lists: Auto-add items that are below your minimum stock level
  • Barcode scanning: Grocy app scans barcodes to add/remove stock
  • Chore tracking: Schedule household tasks with recurrence and assignment
  • Recipe integration: Sync with Mealie via API — shopping list from meal plans

Part 1: Docker Setup

# docker-compose.yml
services:
  grocy:
    image: lscr.io/linuxserver/grocy:latest
    container_name: grocy
    restart: unless-stopped
    ports:
      - "9283:80"
    volumes:
      - grocy_config:/config
    environment:
      PUID: 1000
      PGID: 1000
      TZ: America/Los_Angeles
      # Grocy config (also configurable via UI):
      GROCY_CURRENCY: "USD"
      GROCY_CULTURE: "en"
      GROCY_DEFAULT_LOCALE: "en"
      GROCY_FEATURE_FLAG_STOCK: "true"
      GROCY_FEATURE_FLAG_SHOPPINGLIST: "true"
      GROCY_FEATURE_FLAG_RECIPES: "true"
      GROCY_FEATURE_FLAG_CHORES: "true"
      GROCY_FEATURE_FLAG_TASKS: "true"
      GROCY_FEATURE_FLAG_BATTERIES: "true"
      GROCY_FEATURE_FLAG_EQUIPMENT: "true"
      GROCY_FEATURE_FLAG_CALENDAR: "true"

volumes:
  grocy_config:

docker compose up -d

Visit http://your-server:9283 — default credentials are admin / admin (change immediately).

Part 2: HTTPS with Caddy

home.yourdomain.com {
    reverse_proxy localhost:9283
}

Part 3: Initial Configuration

  1. Settings → User settings: Change your password
  2. Settings → System settings:
    • Currency symbol and decimal places
    • Default due days for new products
    • Language and locale
  3. Master data → Locations: Add your storage locations:
    • Pantry, Refrigerator, Freezer, Cabinet, Garage
  4. Master data → Quantity units: Add your units:
    • piece, g, kg, ml, L, cup, tbsp, tsp

Part 4: Adding Products

Via web UI

  1. Products → Add product
  2. Name, barcode (optional), default quantity, location
  3. Min. stock amount: Alert when below this
  4. Default due days: How many days after purchase until it expires

Via barcode scanner (Grocy app)

  1. Install Grocy Android app
  2. Connect to your Grocy server
  3. Scanner: tap camera icon → scan barcode → Grocy looks up the product
  4. If not in database: add it first, then scan again

Via Barcode Buddy (auto-lookup)

# Add to docker-compose.yml — auto-looks up barcodes via Open Food Facts:
services:
  barcodebuddy:
    image: f0rc3/barcodebuddy-docker:latest
    container_name: barcodebuddy
    restart: unless-stopped
    ports:
      - "9090:80"
    volumes:
      - barcodebuddy_config:/config
    environment:
      BBUDDY_GROCY_API_URL: "http://grocy:80/api/"
      BBUDDY_GROCY_API_KEY: "${GROCY_API_KEY}"

Part 5: Stock Management

Add stock (purchase)

  1. Stock overview → [Product] → Purchase
  2. Amount, price, due date, location, store
  3. Or scan barcode in app → "Purchase"

Consume stock

  1. Stock overview → [Product] → Consume
  2. Amount consumed
  3. Or scan barcode in app → "Consume"

Stock overview

The main dashboard shows:

  • Due soon: Items expiring in the next 5 days
  • Overdue: Items past their due date
  • Below min. stock: Items you need to buy
  • Never opened: Sealed items

Part 6: Shopping Lists

Manual shopping list

  1. Shopping list → Add item
  2. Product + amount + where to buy

Auto-populate from stock

  1. Shopping list → + → Add missing products
  2. Grocy adds everything below minimum stock level
  3. Sort by location/store for efficient shopping

Check off while shopping

Use the Grocy mobile app:

  1. Open shopping list
  2. Check off items as you add them to your cart
  3. When done: Mark all as done → automatically added to your stock

Part 7: Chores

Track and schedule household chores:

  1. Chores → Add chore
  2. Name: Clean bathroom, Vacuum living room, Change furnace filter
  3. Period type: Daily, Weekly, Monthly, or specific interval
  4. Next estimated due date
  5. Assigned to: Which household member

Chore dashboard: See what's due today, overdue, and upcoming.

# Create a chore via API:
curl -X POST "${GROCY_URL}/api/objects/chores" \
  -H "GROCY-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Change AC filter", "period_type": "monthly", "period_days": 30}'

# Mark a chore as done:
curl -X POST "${GROCY_URL}/api/chores/1/execute" \
  -H "GROCY-API-KEY: $API_KEY" \
  -d '{"tracked_time": "2026-03-10 10:00:00", "done_by": 1}'

Part 8: API Integration

# Get Grocy API key:
# Settings → Manage API keys → + Create

GROCY_URL="https://home.yourdomain.com"
API_KEY="your-api-key"

# Get current stock:
curl "${GROCY_URL}/api/stock" \
  -H "GROCY-API-KEY: $API_KEY" | jq '.[] | select(.amount < .product.min_stock_amount) | .product.name'

# Get items expiring in next 5 days:
curl "${GROCY_URL}/api/stock/volatile?due_soon_days=5" \
  -H "GROCY-API-KEY: $API_KEY" | jq '.due_products[].product.name'

# Add to shopping list:
curl -X POST "${GROCY_URL}/api/stock/shoppinglist/add-missing-products" \
  -H "GROCY-API-KEY: $API_KEY"

# Get shopping list:
curl "${GROCY_URL}/api/objects/shopping_list" \
  -H "GROCY-API-KEY: $API_KEY" | jq '.[].product.name'

Part 9: Home Assistant Integration

Grocy integrates directly with Home Assistant via the official integration:

  1. Home Assistant → Settings → Integrations → + Add → Grocy
  2. URL: https://home.yourdomain.com
  3. API Key: your Grocy API key

This creates sensors for:

  • sensor.grocy_due_products — items due/expiring soon
  • sensor.grocy_overdue_products — items past due date
  • sensor.grocy_missing_products — items below minimum stock
  • sensor.grocy_chores_due — chores due today/overdue

Use in automations:

# Notify when fridge items expire tomorrow:
automation:
  trigger:
    platform: state
    entity_id: sensor.grocy_due_products
  condition:
    condition: template
    value_template: "{{ states('sensor.grocy_due_products') | int > 0 }}"
  action:
    service: notify.mobile_app_phone
    data:
      message: "{{ states('sensor.grocy_due_products') }} items expiring soon!"

Maintenance

# Update Grocy:
docker compose pull
docker compose up -d

# Backup:
tar -czf grocy-backup-$(date +%Y%m%d).tar.gz \
  $(docker volume inspect grocy_grocy_config --format '{{.Mountpoint}}')

# Logs:
docker compose logs -f grocy

See all open source home management tools at OSSAlt.com/categories/home.

Comments