tagspaces: Open Source Note Taking & Knowledge Management

What is tagspaces?

TagSpaces is a free, open source, offline document manager with tagging support for Windows, Linux and macOS, built for people who want to organise local files and notes without cloud services, internet access or vendor lock-in.

What it is

TagSpaces is a TypeScript desktop application built on Electron, with a renderer and main process split, a React.js and MUI user interface, and a structure derived from Electron React Boilerplate. It belongs to the offline-first, local-first productivity ecosystem: the application browses, tags and manages files that already live in the user's own filesystem, and it ships no server component that must be hosted for the desktop use case. Alongside the desktop builds, the project maintains a browser extension and a Capacitor directory for Android and iOS builds, plus a Docker container setup and web assets in the repository.

The concrete problem it solves is metadata ownership. Conventional document managers and note-taking services keep tags, notebooks and search indexes inside a proprietary cloud database, so the organisation disappears the moment a file leaves the service. TagSpaces stores tags either directly in filenames or in sidecar files, which means the taxonomy travels with the files and stays readable on any machine. Search runs against a local index rather than a remote API, and the desktop application talks to a local web service process that builds the search index and generates thumbnails for most image formats. Nothing about that workflow requires a network connection.

Key capabilities

Tagging system that writes tags into filenames or into sidecar files for metadata storage.
Flexible search that filters files by name or by tag, with fuzzy matching.
Note taking in TXT, Markdown and HTML formats.
To-do list management through the built-in HTML editor.
Media player for common audio and video formats, playing files in place.
Web Clipper browser extension for Firefox, Edge and Chrome, saving web pages or screenshots as local files.
File and folder management interface for browsing and organising local directories.

Who uses it and how

Privacy-focused individuals and air-gapped environments, since the application is fully offline and serverless by design.
Self-hosters and offline-first users who keep large personal document collections on their own disks and want tags to survive moves between machines.
Writers and researchers working in Markdown, who keep notes in the same folder tree as the source documents they annotate.
Web researchers who rely on the Web Clipper to capture pages and screenshots into a local folder instead of a bookmark service.
Developers building from source with Node.js, npm and Git, using npm run dev for a development server that watches for source changes and refreshes the application automatically.

Getting started

Prebuilt releases are downloaded from the GitHub Releases page. Building from source means cloning the repository, running npm install, creating a .env file in release/app containing a custom KEY, then running npm run build and npm run start.

How it compares

The facts provided here name no paid products that TagSpaces replaces, and they name no comparable tools in the same category. On the evidence available, TagSpaces stands alone in this registry, and any comparison with hosted document managers or note-taking services would have to be made outside these facts.

When to use it — and when not to

A self-hoster still has to manage a local web service process that runs on a fixed port, and must generate a custom KEY in release/app/.env so that two TagSpaces instances on the same machine do not communicate with each other's service. Anyone building from source needs a working Node.js, npm and Git toolchain, and the README excerpt is aimed at developers rather than end users, with the fuller documentation hosted separately at docs.tagspaces.org. The AGPL-3.0 licence is copyleft, which constrains redistribution inside proprietary products, and the facts describe no cloud sync, multi-user or collaboration features, so teams needing shared hosted workspaces should look elsewhere.

project readme (upstream, from github) — read inline

TagSpaces

TagSpaces is a free and open-source platform for organizing, tagging, and managing your local files. It runs completely offline, with no need for cloud services, internet connection, or vendor lock-in. Available for Windows, Linux, and macOS, it also includes a browser extension (Web Clipper) for Firefox, Edge, and Chrome to capture online content as local files.

TagSpaces with the Markdown Editor

🌐 Learn More

📦 Downloads

Grab the latest release from the GitHub Releases Page.
Check out the full changelog for recent updates.

🚀 Features at a Glance

File & Folder Management – Browse, organize, and manage local files in a powerful interface.
Tagging System – Add tags directly into filenames or use sidecar files for metadata storage.
Flexible Search – Filter and find files by name or tags using fuzzy search.
Offline First – 100% offline, serverless, and privacy-focused.
Cross-platform – Runs seamlessly on Windows, Linux, and macOS.
Note Taking – Create notes in TXT, Markdown, or HTML.
To-Do Support – Manage task lists using the built-in HTML editor.
Media Player – Play common audio and video formats directly within the app.
Web Clipper – Save web pages or screenshots locally using our browser extension.

👩‍💻 Developer Guide

🛠️ Technologies

Javascript Framework: React.js
User Interface Styling: MUI
Desktop App Framework: Electron
Boilerplate: Electron React Boilerplate

📁 Project Structure

src/
  renderer/         # Core application logic
  main/             # Electron main process
  locales/          # Language translation files
  node_modules/     # TagSpaces extension modules

capacitor/          # Mobile (Android/iOS) build
dll/                # Live reload support for development
docker/             # Docker container setup
internals/          # Flow and ESLint configurations
resources/          # Images and build resources
scripts/            # NPM task-related scripts
test/               # Unit and E2E tests
web/                # Assets for web version

▶️ Running from Source

Prerequisites

Install the following tools:

Setup Steps

git clone https://github.com/tagspaces/tagspaces.git
cd tagspaces
git checkout develop  # or 'master' for stable release
npm install

Set Up Local Web Service

Create a .env file in release/app/ with a custom key to avoid conflicts:

The desktop version of the application uses a web service which is running locally as a separate process. The web service is responsible for the search index creation and the generation of the thumbnails for most of the images formats. A key is required in order for the main application to communicate with the web server. It should be generated from webpack script in the .env file located in release/app folder. This is an example for an .env file.

KEY=a_custom_key

Having a custom key, ensures that another instance of TagSpaces will not communicate with the web service of the initial instance, since it is always running on the same port.

Build & Start

npm run build
npm run start

Start in Development Mode

npm run dev

This will start a development server in background, which watches for changes in background and refreshes the application automatically once you have done some changes in the source code.

🧪 Testing

Run unit and integration tests:

npm run test-unit
npm run test-playwright
npm run test-playwright-web

💻 Packaging the Desktop App

Build native apps for each platform:

npm run package-win
npm run package-linux
npm run package-mac
npm run package-mac-arm64

The commands will create packages for Windows, Linux, Mac OS and Mac OS with the M1 processor respectively.

⚠️ Run npm run build before packaging.

📱 Mobile Build (Capacitor)

Build and run the Android or iOS app via Capacitor:

npm run run-android-cap
npm run run-ios-cap

🌐 Web Version

Start the web version locally:

npm run run-web

🔌 Extend with Custom Viewers & Editors

TagSpaces supports extension modules for opening and editing different file types. Learn more on our Extensions Page.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md, and review and sign the Contributor License Agreement (CLA) before submitting PRs.

🌍 Localization

TagSpaces is available in over 20 languages. Help us translate the app by joining our team on Transifex.

💡 Ideas & Suggestions

Have an idea or a feature request? Share it on our community forum and join the discussion.

🐞 Support & Bug Reports

If you encounter a bug or need help, open an issue on GitHub.

⚠️ Known Limitations

TagSpaces is not optimized for locations with more than 100,000 files.

📡 Feeds

📄 License

TagSpaces is dual-licensed under the AGPL (GNU Affero General Public License) v3 for open-source projects and a commercial license for vendors or resellers. Contact us if you're interested in using TagSpaces under different terms.

The TagSpaces Pro components (tagspacespro/) are proprietary and governed by a separate EULA. For the full picture — the open-source/proprietary boundary, how the combined builds are distributed, and third-party notices — see LICENSING.md.

Frequently asked questions

Is tagspaces free to use?

tagspaces is open source under the AGPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does tagspaces do?

TagSpaces is an offline, open source, document manager with tagging support

What is tagspaces written in?

tagspaces is primarily written in TypeScript. Its source is publicly available at https://github.com/tagspaces/tagspaces, and it has 5,286 GitHub stars.