Repository files navigation

Grist is a modern relational spreadsheet. It combines the flexibility of a spreadsheet with the robustness of a database.

• grist-core (this repo) 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 byGrist Labs, an NYC-based company 🇺🇸🗽. The French government 🇫🇷 organizationsANCT Données et Territoires andDINUM (Direction Interministérielle du Numérique) have also made significant contributions to the codebase.

Thegrist-core,grist-desktop, andgrist-static repositories are all open source (Apache License, Version 2.0).Grist Labs offers free and paid hosted services atgetgrist.com, sells an Enterprise product,and offerscloud packaging.

Questions? Feedback? Want to share what you're building with Grist? Join ourofficial Discord server or visit ourCommunity forum.

To see exactly what is present ingrist-core, you can run thedesktop app, or usedocker. The absolute fastest way to try Grist out is to visitdocs.getgrist.com and play with a spreadsheet there immediately – though if you do, please read the list ofextra extensions that are not ingrist-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 aGrist 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 ourGrist vs Airtable article for a direct comparison).

Here are some specific feature highlights of Grist:

• Python formulas.
  • FullPython syntax is supported, including the standard library.
  • ManyExcel functions also available.
  • AnAI Assistant specifically tuned for formula generation (using OpenAI gpt-3.5-turbo orLlama viallama-cpp-python).
• 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.
  • Enablesbackups that you can confidently restore in full.
  • Great for moving between different hosts.
• Can be displayed on a static website withgrist-static – no special server needed.
• A self-contained desktop app for viewing and editing locally:grist-desktop.
• Convenient editing and formatting features.
  • Choices andchoice lists, for adding colorful tags to records.
  • References and reference lists, for cross-referencing records in other 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.
• Drag-and-drop dashboards.
  • Charts,card views and acalendar 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.
• 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.
• Integrations.
  • AREST API,Zapier actions/triggers, and support from similarintegrators.
  • Import/export to Google drive, Excel format, CSV.
  • Link data withcustom widgets, hosted externally.
  • Configurable outgoing webhooks.
• Many templates to get you started, from investment research to organizing treasure hunts.
• Access control options.
  • (You'll need SSO logins set up to make use of these options;grist-omnibus has a prepackaged solution if configuring this feels daunting)
  • Shareindividual documents, workspaces, orteam sites.
  • Control access toindividual rows, columns, and tables.
  • Control access based on cell values and user attributes.
• Self-maintainable.
  • Useful for intranet operation and specific compliance requirements.
• Sandboxing options for untrusted documents.
  • On Linux or with Docker, you can enablegVisor 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.
• Translated to many languages.
• 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 publishmonthly newsletters.

If you are curious about where Grist is heading, seeour roadmap, drop a question inour forum, or browseour extensive documentation.

If you evaluate Grist by using the hosted version atgetgrist.com, be aware that it includes some extensions to Grist that aren't present ingrist-core. To be sure you're seeing exactly what is present ingrist-core, you can run thedesktop app, or usedocker. Here is a list of features you may see in Grist Labs' hosting or Enterprise offerings that are not ingrist-core, in chronological order of creation. If self-hosting, you can get access to a free trial of all of them using the Enterprise toggle on theAdmin Panel.

• 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 –OIDC andSAML supportis part ofgrist-core and covers most authentication use cases.
• Azure back-end for document storage (2022)
  • Withgrist-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)
  • Withgrist-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 ongrist-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 ingrist-core, but the newer Assistant can help with a wider range of tasks like building tables and dashboards 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, withgrist-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 ingrist-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?

To get the default version ofgrist-core running on your computerwithDocker, do:

docker pull gristlabs/gristdocker run -p 8484:8484 -it gristlabs/grist

Then visithttp://localhost:8484 in your browser. You'll be able to create, edit, import,and export documents. 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 attemplates.getgrist.com for payroll,inventory management, invoicing, D&D encounter tracking, and a lotmore, or use any document you've created ondocs.getgrist.com.

If you need to change the port Grist runs on, set aPORT variable, don't just change theport 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 allenvironments.

You can find a lot more about configuring Grist, setting up authentication,and running it on a public server in ourSelf-Managed Grist handbook.

(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:

ASSISTANT_CHAT_COMPLETION_ENDPOINT=https://openrouter.ai/api/v1/chat/completions

ASSISTANT_API_KEY=your_openrouter_api_key_here

Sign up for an OpenRouter API key athttps://openrouter.ai/

ASSISTANT_MODEL=anthropic/claude-3.7-sonnet

ASSISTANT_MODEL=deepseek/deepseek-r1-zero:free

ASSISTANT_MODEL=qwen/qwq-32b:free

ASSISTANT_MODEL=mistralai/mistral-saba

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 formulasSwitch between different AI models without changing your Grist configurationTake 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.

The default Docker image isgristlabs/grist. This contains all ofthe standard Grist functionality, as well as extra source-availablecode for enterprise customers taken from thegrist-ee repository. Thisextra code is not under a free or open source license. By default,however, the code from thegrist-ee repository is completely inertand inactive. This code becomes active only when enabled from theadministrator panel.

If you would rather use an image that contains exclusively free andopen source code, thegristlabs/grist-oss Docker image is availablefor this purpose. It is by default functionally equivalent to thegristlabs/grist image.

You can turn on a special admininistrator panel to inspect the statusof your installation. Just visit/admin on your Grist server forinstructions. Since it is useful for the admin panel to beavailable even when authentication isn't set up, you can give it aspecial access key by settingGRIST_BOOT_KEY.

docker run -p 8484:8484 -e GRIST_BOOT_KEY=secret -it gristlabs/grist

The boot page should then be available at/admin?boot-key=<GRIST_BOOT_KEY>. We are collecting probes forcommon problems there. If you hit a problem that isn't covered, itwould be great if you could add a probe for it inBootProbes.You may instead file an issue so someone else can add it.

To build Grist from source, follow these steps:

yarn installyarn run buildyarn run install:pythonyarn start# Grist will be available at http://localhost:8484/

Grist formulas in documents will be run using Python executed directly on yourmachine. You can configure sandboxing using aGRIST_SANDBOX_FLAVORenvironment variable.

• On macOS,export GRIST_SANDBOX_FLAVOR=macSandboxExecuses the nativesandbox-exec command for sandboxing.
• On Linux withgVisor's runscinstalled,export GRIST_SANDBOX_FLAVOR=gvisor is an option.
• On any OS including Windows,export GRIST_SANDBOX_FLAVOR=pyodide is available.

These sandboxing methods have been written for our own use at Grist Labs andmay need tweaking to work in your own environment - pull requestsvery welcome here!

If you wish to include Grist Labs enterprise extensions in your build,the steps are as follows. Note that this will add non-OSS code to yourbuild. It will also place a directory callednode_modules one levelup, at the same level as the Grist repo. If that is a problem for you,just move everything into a subdirectory first.

yarn install./buildtools/checkout-ext-directory.sh grist-eeyarn install --cwd ext --modules-folder ../../node_modules/WEBPACK_EXTRA_MODULE_PATHS=../node_modules yarn buildyarn run install:pythonWEBPACK_EXTRA_MODULE_PATHS=../node_modules yarn start# Grist will be available at http://localhost:8484/

The enterprise code will by default not be used. You need to explicitly enableit in theAdmin Panel.

Like git, Grist has features to track document revision history. So for full operation,Grist expects to know who the user modifying a document is. Until it does, it operatesin a limited anonymous mode. To get you going, the docker image is configured so thatwhen you click on the "sign in" button Grist will attribute your work toyou@example.com.Change this by settingGRIST_DEFAULT_EMAIL:

docker run --env GRIST_DEFAULT_EMAIL=my@email -p 8484:8484 -v $PWD/persist:/persist -it gristlabs/grist

You can change your name inProfile Settings intheUser Menu.

For multi-user operation, or if you wish to access Grist across thepublic internet, you'll want to connect it to your own Single Sign-On service.There are a lot of ways to do this, includingSAML and forward authentication.Grist has been tested withAuthentik,Auth0,and Google/Microsoft sign-ins viaDex.

We useWeblate to manage translations.Thanks to everyone who is pitching in. Thanks especially to the ANCT developers whodid the hard work of making a good chunk of the application localizable. Merci beaucoup !

This repository,grist-core, is maintained by Grist Labs. Our flagship product available atgetgrist.com is built from the code you see here, combined with business-specific software designed to scale to many users, handle billing, etc.

Grist Labs is an open-core company. We offer Grist hosting as a service, with free and paid plans. We also develop and sell features related to Grist using a proprietary license, targeted at the needs of enterprises with large self-managed installations.

We see data portability and autonomy as a key value, andgrist-core is an essential part of that. We are committed to maintaining and improving thegrist-core codebase, and to be thoughtful about how proprietary offerings impact data portability and autonomy.

By opening its source code and offering anOSI-approved free license, Grist benefits its users:

• Developer community. The freedom to examine source code, make bug fixes, and developnew features is a big deal for a general-purpose spreadsheet-like product, where there is avery long tail of features vital to someone somewhere.
• Increased trust. Because anyone can examine the source code, “security by obscurity” is notan option. Vulnerabilities in the code can be found by others and reported before they causedamage.
• Independence. Grist is available to you regardless of the fortunes of the Grist Labs business,since it is open source and can be self-hosted. Using our hosted solution is convenient, but youare not locked in.
• Price flexibility. If you are low on funds but have time to invest, self-hosting is a greatoption to have. And DIY users may have the technical savvy and motivation to delve in and make improvements,which can benefit all users of Grist.
• Extensibility. For developers, having the source open makes it easier to build extensions (such asCustom Widgets). You can more easily include Grist in your pipeline. And if a feature is missing, you can just take the source code and build on top of it.

For more on Grist Labs' history and principles, see ourAbout Us page.

• Grist on ProductHunt
• Grist on AppSumo (life-time deal is sold out)
• Capterra,G2,TrustRadius

Grist can be configured in many ways. Here are the main environment variables it is sensitive to:

At the time of writing, the AI Assistant is known to function against OpenAI chat completion endpoints (those ending in/v1/chat/completions).It is also known to function against the chat completion endpoint provided byllama-cpp-python and byLM Studio. For useful results, the LLM should be on par with GPT 3.5 or above.

Forward authentication supports two modes, distinguished byGRIST_IGNORE_SESSION:

1. With sessions, and forward-auth on login endpoints.

   For example, using traefik reverse proxy withtraefik-forward-auth middleware:

   • GRIST_IGNORE_SESSION: do NOT set, or set to a falsy value.
   • Make sure your reverse proxy applies the forward auth middleware toGRIST_FORWARD_AUTH_LOGIN_PATH andGRIST_FORWARD_AUTH_LOGOUT_PATH.
   • If you want to allow anonymous access in some cases, make sure all other paths are free ofthe forward auth middleware. Grist will trigger it as needed by redirecting toGRIST_FORWARD_AUTH_LOGIN_PATH. Once the user is logged in, Grist will use sessions toidentify the user until logout.

2. With no sessions, and forward-auth on all endpoints.

   For example, using HTTP Basic Auth and server configuration that sets the header (specified inGRIST_FORWARD_AUTH_HEADER) to the logged-in user.

• GRIST_IGNORE_SESSION: set totrue. Grist sessions will not be used.
• Make sure your reverse proxy sets the header you specified for all requests that may needlogin information. It is imperative that this header cannot be spoofed by the user, sinceGrist will trust whatever is in it.

When using forward authentication, you may wish to also set the following variables:

• GRIST_FORCE_LOGIN=true to disable anonymous access.

Grist has a plugin system, used internally. One useful thing you cando with it is include custom widgets in a build of Grist. Custom widgetsare usually made available just by settingGRIST_WIDGET_LIST_URL,but that has the downside of being an external dependency, which canbe awkward for offline use or for archiving. Plugins offer an alternative.

To "bundle" custom widgets as a plugin:

• Add a subdirectory ofplugins, e.g.plugins/my-widgets.Alternatively, you can set theGRIST_USER_ROOT environmentvariable to any path you want, and then createplugins/my-widgetswithin that.
• Add amanifest.yml file in that subdirectory that looks likethis:

name: My Widgetscomponents:  widgets: widgets.json

• Thewidgets.json file should be in the format produced bythegrist-widgetrepository, and should be placed in the same directory asmanifest.yml. Any material inplugins/my-widgetswill be served by Grist, and relative URLs can be used inwidgets.json.
• Once all files are in place, restart Grist. Your widgets shouldnow be available in the custom widgets dropdown, along withany others fromGRIST_WIDGET_LIST_URL.
• If you like, you can add multiple plugin subdirectories, withmultiple sets of widgets, and they'll all be made available.

Tests are run automatically as part of CI when a PR is opened. However, it can be helpful to run tests locallybefore pushing your changes to GitHub. First, you'll want to make sure you've installed all dependencies:

yarn installyarn install:python

Then, you can run the main test suite like so:

yarn test

Python tests may also be run locally. (Note: currently requires Python 3.10 - 3.11.)

yarn test:python

For running specific tests, you can specify a pattern with theGREP_TESTS variable:

env GREP_TESTS=ChoiceList yarn testenv GREP_TESTS=summary yarn test:python

This repository,grist-core, is released under theApache License, Version 2.0, which is anOSI-approved free software license. See LICENSE.txt and NOTICE.txt for more information.