Frappe Insights reads the database Frappe apps already filled up

The problem started inside the Frappe ecosystem

Frappe Insights is described as a 100% open-source BI tool designed to make data analysis and reporting more accessible to technical as well as non-technical users, and the motivation section explains why that was worth building.

Building custom apps or creating structured data has been very easy with the Frappe Framework. Extracting information from those apps was not a good experience. Users needed to know how to write SQL queries to create reports to gain valuable information from the data. The stated aim was to improve the experience of building reports and dashboards for everyone in the team.

That is a narrow, specific problem, and it explains the shape of the product better than any generic positioning would. This is not a BI tool that expects to sit on top of a dozen data warehouses. It is a reporting layer for applications where the database is full of business records that the people using those applications would like to see, and where the only route to that data today is a SQL query written by someone else.

The audience is therefore two groups at once. The developer who currently writes the SQL by hand gets a faster way to build the report, and the colleague who could not write SQL gets a tool that lets them build one. The query builder is the piece that serves the second group, and the chart builder and dashboards serve both.

Ibis composes the SQL and DuckDB does the work

The under the hood section lists four projects, and they are the architecture.

Frappe Framework is the full-stack web application framework, which is the host application and the source of the data being reported on. Frappe UI is a Vue-based UI library for the interface. Ibis is described as a powerful library to compose SQL queries with dataframe APIs, which is the query layer. And eCharts is the interactive charting and data visualisation library behind the chart builder.

The Ibis choice is the interesting one, because it is what makes a single query builder work across different databases. A query written through a dataframe style API is expressed once and compiled to whatever SQL the target engine needs, which is what allows the same query builder to sit on top of MySQL, PostgreSQL, DuckDB and BigQuery without four implementations. The dependency list shows this concretely: ibis-framework is pinned at about 11.0.0 with extras for duckdb, mysql, sqlite, clickhouse and postgres, plus psycopg with the binary extra, and sqlglot at 30.12 or later for the SQL translation itself.

The local analysis engine is DuckDB, pinned at about 1.4.3, and pandas at about 2.3.3 is there for the dataframe side. SQLAlchemy is pinned exactly at 2.0.41, which is the kind of exact pin that tells you the maintainers have hit a version difference in that library before.

One dependency deserves a flag rather than a mention. python-telegram-bot is a runtime dependency of a business intelligence tool, which is unexpected on its face, and the README does not explain what it is for. It is worth asking about before deploying.

The query builder removes the SQL, the chart builder removes the guesswork

Three features carry the product.

The query builder lets you create queries without any SQL knowledge, and the interface is described as a step-by-step approach: select tables, add joins, apply filters, perform calculations, and more. The join editor has its own screen in the screenshots, which suggests joins are treated as a first class step rather than an afterthought.

The chart builder visualises query results with a variety of charts and graphs, and Frappe Insights also suggests the best chart for a given result set. That suggestion is a small feature with a large effect on non-technical users, because the hard part of a BI tool for someone who does not write SQL is not the query, it is the decision about what shape the answer should take. Offering a default that the user can accept removes the last question.

Dashboards are built with a drag-and-drop interface, and you can add filters on the dashboard that apply to the charts. The dashboard filter is the feature that turns a report into a tool, because a single dashboard with a date range or a customer filter replaces a request to the person who writes the SQL.

The sources are broader than a database connection. You can integrate data from multiple databases, files and spreadsheets, and the stated rationale is that getting all your data into one place helps you analyse interconnected data. That is a real capability for a Frappe shop, where a sales order in the database, a spreadsheet of targets and a CSV of shipping data belong in the same analysis.

The supported database list and the installed extras do not match

The README says Frappe Insights currently supports MySQL, PostgreSQL, DuckDB and BigQuery databases, with more integrations planned for the future. The dependency configuration tells a slightly different story.

In the pyproject, the ibis extras that are enabled are duckdb, mysql, sqlite, clickhouse and postgres. The Microsoft SQL Server extra is commented out, and so is the BigQuery extra. ClickHouse and SQLite are enabled even though the README does not list them among the supported databases.

So there are three ways the documented surface and the installed surface disagree: BigQuery is advertised but its extra is not installed by default, Microsoft SQL Server is not advertised and not installed, and ClickHouse and SQLite are installed without being advertised. There is a comment in the file about ibis moving to version 12 and what would have to be deleted, which shows the author maintains these pins deliberately, so the commented lines are probably waiting for a fix rather than forgotten.

The practical reading is that a supported backend needs its extra installed, and that the README's list is a statement of intent rather than a statement of what is in the box. Before planning a deployment on BigQuery, check whether the extra is present, because the dependency list in the repository is the authoritative document.

Self hosting is a script, a container image and one config flag

The production path is short, and it is a container image on a Frappe Cloud style stack.

The first step is to download the easy install script:

wget https://frappe.io/easy-install.py

And the second is to deploy it, with the parameters you need to fill in:

python3 ./easy-install.py deploy \
    --project=insights_prod_setup \
    --email=your_email.example.com \
    --image=ghcr.io/frappe/insights \
    --version=stable \
    --app=insights \
    --sitename subdomain.domain.tld

The two placeholders are your email and the domain the site will be served on. The image comes from the GitHub container registry, so the deployment is a standard Frappe bench layout with the Insights app on it.

The third step is a configuration change, and it is not optional in the flow as written. Server scripts have to be enabled:

docker compose -p insights_prod_setup exec backend bench set-config -g server_script_enabled 1

That step tells you something about the product, since the ability to run server side scripts is a Frappe feature with a good deal of power behind it, and the deploy script does not turn it on for you.

The fourth step is to open the site and log in with the administrator credentials, which the console prints after the deployment, and which are also written to an insights_prod_setup-passwords.txt file.

Local development runs a Frappe bench, a Vite server and two shells

The development setup has two routes, and the Docker one is the quickest way to see the product.

You need Docker, docker-compose and git, then you download two files from the develop branch, the docker-compose file and the init script:

mkdir frappe-insights
cd frappe-insights

wget -O docker-compose.yml https://raw.githubusercontent.com/frappe/insights/develop/docker/docker-compose.yml
wget -O init.sh https://raw.githubusercontent.com/frappe/insights/develop/docker/init.sh

Then bring the stack up, and the site is available at http://insights.localhost:8000/insights with the default credentials, Administrator and admin:

docker compose up -d

Stopping is either docker compose stop, which keeps the data, or docker compose down, which removes the whole setup.

The local route needs a working bench, and it is the route to take if you intend to change the code. You start the server, then in a second terminal you fetch the app and create a site with it installed:

bench get-app insights
bench new-site insights.test --install-app insights
bench --site insights.test add-to-hosts
bench --site insights.test browse --user Administrator

In a third terminal, inside the app directory, you run yarn and yarn dev, and the site appears on the Vite dev server at http://insights.test:8080. The two server ports are a source of confusion the first time, since the bench site and the frontend dev server are different services on different ports.

The front end is a Yarn workspace with two members, frontend and frappe-ui, and the build script compiles the main bundle and then an islands build, which is the pattern used for partially interactive pages in the Frappe UI stack.

The compatibility matrix is the real maintenance story

Frappe Insights is versioned in step with the Frappe Framework it runs on, and that coupling is the thing to understand before adopting it.

The dependency declaration pins the framework to a range of 17.0.0-dev and above but below 18.0.0, so Insights on its current line targets the next Frappe major. The compatibility matrix is enforced by a nightly workflow that installs each branch and runs the test suite on the Node and Python versions each Frappe branch supports, and pull requests into version-3 run it as well. The matrix table in the README lists each Insights branch against the versions of the Frappe Framework, Node and Python it is tested with.

That nightly matrix is a real commitment, and it is the best available evidence about how this project is maintained, more informative than any release note. The default branch is develop, the recent releases are v3.15.0 on 2026-10-15 with v3.14.3 and v3.14.4 two days before, and the last push was on 2026-10-19, so the branch and the tags are close together.

The licence is AGPL-3.0, and that is the one thing to settle early. Insights is a web application, so running it as a service for your own users is the normal deployment, and AGPL is the copyleft licence that reaches into network use, which is a different conversation from the MIT licence of a typical library. The repository also carries the tooling of a carefully run project, with a.pre-commit-config.yaml, a Semgrep configuration, commitlint, a.mergify.yml for merge automation, a.releaserc for releases, a crowdin.yml for translations, a codecov configuration, and both AGENTS.md and CLAUDE.md for automated agents working on the code.

Editorial conclusion

Frappe Insights suits a team running Frappe or ERPNext who has data in a database and reports built by hand in SQL, and who wants non-technical colleagues to build their own dashboards. It does not suit an organisation that needs a general purpose BI tool across many heterogeneous data warehouses, since its connectors are aimed at the databases a Frappe deployment actually has, and its AGPL-3.0 licence is a decision to make before it goes anywhere near a product. Verify first that your source database is in the list of supported backends, and check the installed extras for that backend, because the dependency list shows the BigQuery and Microsoft SQL Server extras commented out while the README lists BigQuery as supported.

Frequently asked questions

Official sources

1. frappe/insights on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases