⚠️ Beta: This app is under active development. While stable, please backup your data regularly and report any issues you encounter.
A comprehensive financial management app for Nextcloud. Track spending habits, manage multiple accounts, and forecast future balances through intelligent analysis of your financial history.
- Quick Add Standalone Page - Minimal mobile page for adding transactions without exposing balances. Bookmark it or add to your home screen (#235)
- Shared Account Support - Reports, forecasts, net worth, and dashboard now include data from shared accounts. Shared users can delete, update, and split transactions (#215, #245)
- Dismissed Imports - Deleted bank sync transactions won't be re-imported. Force re-sync button available when needed (#230)
- Transaction Type Rule Criteria - Rules can now filter by Income or Expense, with Auto-Link as Transfer action (#229)
- Semi-Monthly Frequency - Twice-per-month option for bills, income, and transfers (Discussion #239)
- System Info Diagnostics - Settings panel with data stats, server info, and logs for troubleshooting (#228)
- CI Pipeline - Automated linting, tests, and migration name validation on every push
See the full changelog for details.
Full user documentation is available in the docs/ directory:
- Quick Start Guide — Set up in 10 minutes
- Full Documentation Index — All features documented
Popular topics:
- Importing bank statements
- Setting up auto-categorization rules
- Budget tracking
- Dashboard customization
- Bills & recurring payments
- Settings reference
- Customizable Dashboard - Gridstack.js-powered drag-and-drop with lock/unlock editing, column picker, and per-tile sizing (S/M/L)
- Duplicate Tiles - Add multiple instances of chart and transaction tiles, each with independent account/period settings
- 28+ Dashboard Tiles - Hero metrics, spending insights, forecasting, budget tracking, and more
- Interactive Charts - Cash flow forecasts, year-over-year comparisons, net worth history with Chart.js
- Auto-Updating Tiles - Dashboard refreshes automatically when transactions or budgets change
- Multi-Account Management - Track bank accounts, credit cards, cash, and cryptocurrency across 45+ currencies
- Transaction Tracking - Add, edit, categorize, and search transactions with advanced filtering
- Bulk Operations - Delete, reconcile, or edit multiple transactions at once
- Configurable Table Columns - Show/hide columns to customize your transaction view
- Split Transactions - Allocate single transactions across multiple categories
- Transaction Matching - Automatic transfer detection and linking between accounts
- Transfer Creation - Create linked transfer transactions directly from transaction form
- Pending Transactions - Future-dated transactions shown with visual indicators and filterable status (All / Cleared / Pending)
- Bank Sync (Beta) - Connect external bank accounts for automatic transaction imports
- GoCardless provider for UK/Europe banks with guided setup wizard and bank selection
- SimpleFIN provider for US banks
- Daily background sync with duplicate detection
- Re-authorization flow when bank consent expires (PSD2 90-day limit)
- Sync all connections at once with aggregated results
- Encrypted credential storage
- Admin-enabled with experimental feature warnings
- Smart Import - Import bank statements from CSV, OFX, and QIF formats
- Auto-detection of CSV delimiters (comma, semicolon, tab)
- Dual-column amount mapping for separate income/expense columns
- European number format support (1.234,56)
- Automatic vendor matching and duplicate detection
- Advanced Rules Engine - Powerful auto-categorization with visual query builder
- Complex boolean expressions with AND/OR/NOT operators
- Nested criteria groups with unlimited depth
- Multiple actions: category, vendor, notes, tags, account, type, reference
- Preview matches before saving, run rules on existing transactions anytime
- Priority-based execution with behavior settings (always, if_empty, append, merge)
- Hierarchical Categories - Organize spending with nested categories and drag-and-drop reordering
- Tag Sets - Multi-dimensional transaction categorization with custom tag sets per category
- Budget Tracking - Set spending limits by category with alerts when approaching or exceeding budgets
- Per-month budget adjustments — change budgets from any month forward without affecting historical data
- Dynamic period switching (weekly, monthly, quarterly, yearly)
- Automatic pro-rating when changing budget periods
- Parent category aggregation — parent budgets show combined totals with children
- Real-time progress tracking with visual indicators
- Balance Forecasting - Predict future balances using trend analysis and scenario modeling
- Recurring Bills - Detect and track recurring payments
- Auto-pay option to automatically mark bills as paid on due date
- Create future transactions for cash flow planning
- Bill reminders via Nextcloud notifications
- Custom frequency patterns (select specific months for irregular bills)
- Bills Calendar - Annual overview showing which months bills are due
- Interactive heatmap visualization
- Monthly totals with bar chart
- Filter by status and include/exclude transfers
- Recurring Income - Track expected income sources (salary, dividends, etc.) with receipt tracking
- Recurring Transfers - Track and automate transfers between accounts
- Monthly equivalent calculations for different frequencies
- Integration with bills system for unified tracking
- Asset Tracking - Track non-liquid assets (real estate, vehicles, jewelry, collectibles)
- Value history with snapshots over time
- Appreciation/depreciation projections with interactive charts
- Integrated into net worth calculations
- Debt Payoff Planner - Plan debt repayment using avalanche or snowball strategies
- Repayment charts with stacked area / individual line toggle
- Named scenarios with extra payments, lump sums, debt selection, and rate overrides
- Strategy comparison with side-by-side metrics and recommendation
- Progress tracking against active scenario (ahead/behind/on track)
- Dashboard widgets: chart sparkline, progress countdown, days until debt free
- Savings Goals - Set financial targets with progress tracking and achievement forecasting
- Link goals to tags for automatic amount calculation from tagged transactions
- Pension Tracker - Track retirement accounts with growth projections and combined forecasts
- Shared Expenses - Share expenses with roommates, partners, or friends and track who owes whom
- Settlement tracking with payment history
- Contact integration with Nextcloud
- Net Worth History - Track assets, liabilities, and non-liquid assets over time with interactive charts
- Daily automatic snapshots with manual recording option
- Multi-currency conversion to default currency via ECB and CoinGecko rates
- Status indicators showing last snapshot timing
- Bills Calendar - Visualize when bills are due throughout the year
- Year-over-Year Reports - Compare spending across multiple years side-by-side
- Reports & Charts - Visualize spending patterns, income, and cash flow over time
- Password Protection - Optional secondary password layer for enhanced app security
- Session management with configurable timeout (15/30/60 minutes)
- Auto-lock on inactivity with manual lock option
- Failed attempt protection (5 attempts = 5-minute lockout)
- Data Export/Import - Full data migration support for moving between Nextcloud instances
- Factory Reset - Restore app to empty state with one-click data deletion (preserves audit logs)
- Audit Logging - Complete trail of all financial actions
- Nextcloud 30 - 35
- PHP 8.1+
- MySQL/MariaDB, PostgreSQL, or SQLite
- Log in to your Nextcloud instance as admin
- Go to Apps > Office & text
- Search for "Budget"
- Click Download and enable
cd /path/to/nextcloud/apps
git clone https://github.com/otherworld-dev/Budget.git budget
cd budget/budget
# Install dependencies
composer install --no-dev --optimize-autoloader
npm install
# Build frontend
npm run buildEnable the app:
php occ app:enable budgetcd /path/to/nextcloud/apps
git clone https://github.com/otherworld-dev/Budget.git budget
cd budget/budget
# Install all dependencies
composer install
npm install
# Build for development
npm run dev
# Watch for changes
npm run watch| Command | Description |
|---|---|
npm run build | Production build |
npm run dev | Development build with source maps |
npm run watch | Auto-rebuild on file changes |
npm run lint | Run ESLint |
npm run lint:fix | Auto-fix linting issues |
budget/
├── appinfo/ # App metadata and routing
├── lib/
│ ├── Controller/ # API endpoints
│ ├── Service/ # Business logic
│ ├── Db/ # Database models and mappers
│ ├── Enum/ # Type definitions
│ └── Migration/ # Database schema versions
├── src/ # Frontend source (ES6+)
│ ├── modules/ # Feature-based modules (17 modules)
│ ├── core/ # Router and infrastructure
│ ├── utils/ # Shared utilities
│ └── config/ # Dashboard widgets configuration
├── js/ # Compiled JavaScript
├── css/ # Compiled styles
├── templates/ # PHP templates
└── tests/ # PHPUnit test suites
See the full documentation for detailed guides on every feature.
- Add Accounts - Navigate to the Accounts section and add your bank accounts
- Import Transactions - Use the Import feature to upload your bank statements
- Set Up Categories - Create categories that match your spending patterns
- Configure Import Rules - Set up rules to automatically categorize future imports
- Track Bills - Add recurring bills to monitor upcoming payments
- Set Goals - Create savings goals to track progress toward financial targets
The app supports the following formats:
- CSV - Most banks provide CSV exports (supports European formats)
- OFX - Open Financial Exchange format
- QIF - Quicken Interchange Format
- The first row should contain column headers
- Common columns: Date, Description, Amount, Balance
- Use the column mapping feature to match your bank's format
- For European banks with separate income/expense columns, use dual-column amount mapping
- The app auto-detects delimiters (comma, semicolon, tab)
The advanced rules engine uses a visual query builder for complex patterns:
- Go to Rules in the navigation menu
- Click Add Rule
- Build criteria using the visual query builder:
- Add conditions (field, match type, pattern)
- Group conditions with AND/OR operators
- Use NOT operator for negation
- Create nested groups for complex logic
- Configure actions (category, vendor, notes, etc.)
- Set priority and behavior (always, if_empty, append, merge)
- Preview to test matches before saving
- Run Now to apply to existing transactions
Bills:
- Add recurring bills with custom frequency patterns
- Enable auto-pay to automatically mark bills as paid on due date
- Create future transactions for cash flow planning
- View annual bills calendar to see when bills are due throughout the year
Transfers:
- Track recurring transfers between accounts (e.g., monthly savings transfers)
- Enable auto-pay for automatic execution
- Set transaction description patterns for import matching
The forecast feature analyzes historical spending to predict future balances:
- Select the account(s) to forecast
- Choose the historical period to analyze (3, 6, or 12 months)
- Select the forecast horizon
- Generate the forecast
The forecast considers:
- Regular income patterns
- Recurring expenses
- Seasonal variations
- Average spending by category
To move your data between Nextcloud instances:
- Export - Go to Settings > Data Migration > Export to download all your data
- Import - On the new instance, go to Settings > Data Migration > Import and upload the export file
The app provides a REST API for all functionality:
| Endpoint | Description |
|---|---|
/api/accounts | Account management |
/api/transactions | Transaction CRUD and search |
/api/categories | Category hierarchy |
/api/budget-snapshots | Per-month budget adjustments |
/api/bank-sync | External bank sync (Beta) |
/api/admin/settings | Admin settings (bank sync toggle) |
/api/tag-sets | Tag set management |
/api/import | Bank statement import |
/api/import-rules | Advanced auto-categorization rules |
/api/forecast | Balance predictions |
/api/bills | Recurring bill tracking with auto-pay |
/api/transfers | Recurring transfers between accounts |
/api/goals | Savings goal management |
/api/assets | Non-liquid asset tracking |
/api/pensions | Pension account tracking |
/api/debts | Debt payoff planning |
/api/debt-scenarios | Debt scenario management |
/api/reports | Financial reports |
/api/migration | Data export/import |
/api/auth | Password protection |
- Ensure your CSV has headers in the first row
- Check that date format matches your locale settings
- Verify the file encoding is UTF-8
- For European formats, the app will auto-detect delimiters and number formats
- Check that import rules are active
- Use the Preview feature to test rule matching before saving
- Verify rule patterns match transaction descriptions
- Review rule priority order (higher priority rules execute first)
- Ensure you have at least 3 months of transaction history
- Check for unusual one-time transactions that might skew averages
- Verify all regular transactions are properly categorized
- Verify categories were imported successfully via Settings > Data Migration
- Check browser console for JavaScript errors
- Try refreshing browser cache (Ctrl+F5 / Cmd+Shift+R)
Nextcloud Budget is fully translatable with 2,177+ strings. We'd love your help making it available in more languages!
Translate on Weblate — translate directly in your browser, no coding required. Just sign in, pick your language, and start. Your translations are automatically merged into the app.
Currently available in: English, German, Spanish, French, Russian, Portuguese (Brazil), and Czech.
Special thanks to our translators: @SGiersch (German), @T0mFi and Pavel Borecki (Czech).
Note: Strings containing
{placeholders}(e.g.{amount},{bill}) must keep the placeholder names exactly as-is — only translate the surrounding text.
Alternative: translate via pull request
If you prefer working with .po files directly:
- Copy
budget/translationfiles/templates/budget.pottobudget/translationfiles/<lang>/budget.po - Translate the strings using Poedit or any
.poeditor - Submit a pull request
See the translation guide for detailed instructions.
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/my-feature) - Make your changes
- Run tests (
make test) and linting (make lint) - Submit a pull request
This app is shaped by its community. Thanks to everyone who reports bugs, suggests features, and contributes translations:
- @SGiersch — Top contributor: dozens of bug reports, feature discussions, and German translation
- @TerjeTM — Thorough testing and detailed bug reports that led to major improvements in the bills system and data repair tools
- @JaviAZ — Code contributions and bug reports around category spending and transfers
- @H2Oufoe — Extensive bug reporting and testing across multiple releases
- @st33vil — Identified the pagination balance calculation bug
- @T0mFi, Pavel Borecki — Czech translation
- @raduberbece, @MrTCAJ, @mschur — Bug reports and feedback
This project is licensed under the AGPL-3.0-or-later license.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Forum: Nextcloud Community