Grist
Grist is a modern relational spreadsheet. It combines the flexibility of a spreadsheet with the robustness of a database.
grist-core (this repo – also known as Grist Community edition) has what you need to run a powerful server for hosting spreadsheets.grist-desktop is a Linux/macOS/Windows desktop app for viewing and editing spreadsheets stored locally.grist-static is a fully in-browser build of Grist for displaying spreadsheets on a website without back-end support.
Grist is developed by Grist Labs, an NYC-based company 🇺🇸🗽. The French government 🇫🇷 organizations ANCT Données et Territoires and DINUM (Direction Interministérielle du Numérique) have also made significant contributions to the codebase.
The grist-core, grist-desktop, and grist-static repositories are all open-source (Apache License, Version 2.0). Grist Labs sells an edition of Grist with additional features. Grist Labs also offers free and paid hosted services at getgrist.com,
as well as cloud packaging.
Questions? Feedback? Want to share what you're building with Grist? Join our official Discord server or visit our Community forum.
To keep up-to-date with everything that's going on, you can sign up for Grist's monthly newsletter.
https://github.com/user-attachments/assets/fe152f60-3d15-4b11-8cb2-05731a90d273
Features in grist-core
To see exactly what is present in grist-core, you can run the desktop app, or use docker. The absolute fastest way to try Grist out is to visit docs.getgrist.com and play with a spreadsheet there immediately – though if you do, please read the list of additional features that are not in grist-core.
However you try it, you'll quickly see that Grist is a hybrid database/spreadsheet, meaning that:
- Columns work like they do in databases: they are named, and they hold one kind of data.
- Columns can be filled by formula, spreadsheet-style, with automatic updates when referenced cells change.
This difference can confuse people coming directly from Excel or Google Sheets. Give it a chance! There's also a Grist for Spreadsheet Users article to help get you oriented. If you're coming from Airtable, you'll find the model familiar (and there's also our Grist vs Airtable article for a direct comparison).
Here are some specific feature highlights of Grist (🇫🇷 marks heavy French govt. contributions):
- Python formulas.
- A portable, self-contained format.
- Based on SQLite, the most widely deployed database engine.
- Any tool that can read SQLite can read numeric and text data from a Grist file.
- Enables backups that you can confidently restore in full.
- Great for moving between different hosts.
- Can be displayed on a static website with
grist-static – no special server needed.
- A self-contained desktop app for viewing and editing locally:
grist-desktop.
- Convenient editing and formatting features.
- Choices and choice lists, for adding colorful tags to records.
- References and reference lists, for cross-referencing records in other tables.
- Two-way references that automatically synchronize between tables.
- Attachments, to include media or document files in records.
- Dates and times, toggles, and special numerics such as currency all have specialized editors and formatting options.
- Conditional Formatting, letting you control the style of cells with formulas to draw attention to important information.
- Markdown formatting in text cells.
- Drag-and-drop dashboards.
- Charts, card views and a calendar widget for visualization.
- Summary tables for summing and counting across groups.
- Widget linking streamlines filtering and editing data.
Grist has a unique approach to visualization, where you can lay out and link distinct widgets to show together,
without cramming mixed material into a table.
- Filter bar for quick slicing and dicing.
- Duplicate widgets to quickly build variations of a view.
- Compare documents to see what changed.
- Incremental imports.
- Import a CSV of the last three months activity from your bank...
- ...and import new activity a month later without fuss or duplication.
- Native forms. Create forms that feed directly into your spreadsheet without fuss.
- Supports file attachments, hidden fields, and pre-population via URL parameters.
- Integrations.
- Many templates to get you started, from investment research to organizing treasure hunts.
- Access control options.
- Collaboration.
- Comments on cells, with threaded replies and @-mentions.
- See who else is viewing a document in real time.
- Suggest changes for others to review and approve, inspired by source control workflows.
- Self-maintainable.
- Useful for intranet operation and specific compliance requirements.
- Sign in with getgrist.com for easy authentication without running your own auth server.
- Store attachments externally in S3-compatible storage to keep
.grist files small (🇫🇷).
- HTTP long polling as an alternative to WebSockets for restrictive network environments (🇫🇷).
- Sandboxing options for untrusted documents.
- On Linux or with Docker, you can enable gVisor sandboxing at the individual document level.
- On macOS, you can use native sandboxing.
- On any OS, including Windows, you can use a Wasm-based sandbox via Deno and Pyodide.
- Translated to many languages (🇫🇷).
- A high-contrast theme meeting WCAG level AA requirements (🇫🇷).
- Accessibility support, including screen readers and keyboard navigation across grid views, menus, and the page widget picker (🇫🇷).
F1 key brings up some quick help. This used to go without saying, but in general Grist has good keyboard support (🇫🇷).- We post progress on 𝕏 or Twitter or whatever and publish monthly newsletters.
If you are curious about where Grist is heading, see our roadmap, drop a question in our forum, or browse our extensive documentation.
Features not in grist-core
If you evaluate Grist by using the hosted version at getgrist.com, be aware that it includes some features that aren't present in grist-core. To be sure you're seeing exactly what is present in grist-core, you can run the desktop app, or use docker.
Here is a list of features available in the full edition of Grist that are not in grist-core, in chronological order of creation. If self-hosting, you can get access to a free trial of all of them by selecting the full edition of Grist on the Admin Panel. The full edition of Grist is free for individuals and small orgs with less than US $1 million in total annual funding. Learn more about that here.
- GristConnect (2022)
- Any site that has plugins for letting Discourse use its logins (such as WordPress) can also let Grist use its logins.
- GristConnect is a niche feature built for a specific client which you probably don't care about.
- Azure back-end for document storage (2022)
- With
grist-core you can store document versions in anything S3-compatible, which covers a lot of services, but not Azure specifically. The Azure back-end fills that gap.
- Unless you are a Microsoft shop you probably don't care about this.
- Audit log streaming (2024)
- With
grist-core a lot of useful information is logged, but not organized specifically with auditing in mind. Audit log streaming supplies that organization, and a UI for setting things up.
- Enterprises may care about this.
- Advanced Admin Controls (2025)
- This is a special page for a Grist installation administrator to monitor and edit user access to resources.
- It uses a special set of administrative endpoints not present on
grist-core.
- If you're going to be running a large Grist installation, with employees coming and going, you may care about this.
- Grist Assistant (2025)
- An AI Formula Assistant - limited to working with formulas - is present in
grist-core, but the newer Assistant can help with a wider range of tasks like building tables and dashboards, styling and formatting, explaining access rules, and modifying data.
- If you have many users who need help building documents or working with data, you may care about this one.
- Invite Notifications (2025)
- When a user is added to a document, or a workspace, or a site, with email notifications they will get emailed a link to access the resource.
- This link isn't special, with
grist-core you can just send a link yourself or a colleague.
- For a big Grist installation with users who aren't in close communication, emails might be nice? Hard to guess if you'll care about this one.
- Document Change and Comment Notifications (2025)
- You can achieve change notifications in
grist-core using webhooks, but it is less convenient.
- People have been asking for this one for years. If you need an excuse to get your boss to pay for Grist, this might finally be the one that works?
- Automations (2026)
- A tool for document owners to build trigger-driven workflows: set conditions on any table, then send emails (with dynamic recipients and Markdown) or fire webhooks when rows match, and watch the results in a delivery log.
- You can build similar flows in
grist-core with webhooks, but you'd be wiring up the email side and the monitoring yourself.
- OAuth apps (2026)
- Register and authorize OAuth applications, scope them to specific orgs, workspaces, or documents, and review or revoke that access later.
- A way to give external tools connection to Grist with scoped, revocable access instead of handing over a full API key. If you're connecting Grist to other software, you may care about this, as an alternative to API keys.
- MCP server (2026)
- A built-in Model Context Protocol endpoint that lets AI clients such as Claude or ChatGPT read and edit Grist documents over JSON-RPC. Enabled with
GRIST_MCP_ENABLED (see environment variables).
- With
grist-core you can still use one of the many community MCP servers that talks to Grist through its REST API. The built-in server saves you that work.
- Single sign-on (SSO) via OIDC or SAML (2026)
Using Grist
To get the default version of grist-core running on your computer
with Docker, do:
docker pull gristlabs/grist
docker run -p 8484:8484 -it gristlabs/grist
Then visit http://localhost:8484 in your browser.
On a brand new install you'll land on a Quick setup page that walks
you through choosing an admin email, picking how people sign in, and
setting who can use the site. To get past the first screen, look in the
container's startup log for a line containing a generated boot key, and
paste it in when prompted. Once you click Apply and go live! at the
end of Quick setup, the site is open for business and you'll be able to
create, edit, import, and export documents. There's a step-by-step
walkthrough at
First-run setup.
If you'd rather skip Quick setup entirely and start with an open,
single-user setup, set GRIST_IN_SERVICE=true. You can come back to
the same settings later from the Admin Panel.
To preserve your work across docker runs, share a directory as /persist:
docker run -p 8484:8484 -v $PWD/persist:/persist -it gristlabs/grist
Get templates at templates.getgrist.com for payroll,
inventory management, invoicing, D&D encounter tracking, and a lot
more, or use any document you've created on
docs.getgrist.com.
If you need to change the port Grist runs on, set a PORT variable, don't just change the
port mapping:
docker run --env PORT=9999 -p 9999:9999 -v $PWD/persist:/persist -it gristlabs/grist
To enable gVisor sandboxing, set --env GRIST_SANDBOX_FLAVOR=gvisor.
This should work with default docker settings, but may not work in all
environments.
You can find a lot more about configuring Grist, setting up authentication,
and running it on a public server in our
Self-Managed Grist documentation.
Using Grist with OpenRouter for Model Agnostic and Claude Support
(Instructions contributed by @lshalon)
Grist's AI Formula Assistant can be configured to use OpenRouter instead of connecting directly to OpenAI, allowing you to access a wide range of AI models including Anthropic's Claude models. This isn't the only way to use Claude models, but it's a good option if you want to use Claude models with Grist or intend to use other cheaper, faster, or potentially newer models. That's because this configuration gives you more flexibility in choosing the AI model that works best for your formula generation needs.
To set up OpenRouter integration, configure the following environment variables:
Required: Set the endpoint to OpenRouter's API
ASSISTANT_CHAT_COMPLETION_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
Required: Your OpenRouter API key
ASSISTANT_API_KEY=your_openrouter_api_key_here
Sign up for an OpenRouter API key at https://openrouter.ai/
Optional: Specify which model to use (examples below)
ASSISTANT_MODEL=anthropic/claude-3.7-sonnet
or other options like
ASSISTANT_MODEL=deepseek/deepseek-r1-zero:free
ASSISTANT_MODEL=qwen/qwq-32b:free
ASSISTANT_MODEL=mistralai/mistral-saba
Optional: Set a larger context model for fallback
ASSISTANT_LONGER_CONTEXT_MODEL=anthropic/claude-3-opus-20240229
With this configuration, Grist's AI Formula Assistant will route requests through OpenRouter to your specified model. This allows you to:
Access Anthropic's Claude models which excel at understanding context and generating accurate formulas
Switch between different AI models without changing your Grist configuration
Take advantage of OpenRouter's routing capabilities to optimize for cost, speed, or quality
You can find the available models and their identifiers on the OpenRouter website.
Note: Make sure not to set the OPENAI_API_KEY variable when using OpenRouter, as this would override the OpenRouter configuration.
Available Docker images
The default Docker image is gristlabs/grist. This contains all of
the Grist Community edition features, as well as extra source-available
code for the full edition of Grist. This
extra code is not under a free or open-source license, though by default is completely inert
and inactive. This code becomes active only when enabled from th
Grist is an open-source hybrid spreadsheet/database: columns are typed and named like a database, but can also be filled with Python-syntax formulas like a spreadsheet, with automatic recalculation.