https://github.com/tagspaces/tagspaces
TagSpaces is an offline, open source, document manager with tagging support
https://github.com/tagspaces/tagspaces
electron javascript note-taking offline-first open-source self-hosting tagspaces
Last synced: 26 days ago
JSON representation
TagSpaces is an offline, open source, document manager with tagging support
- Host: GitHub
- URL: https://github.com/tagspaces/tagspaces
- Owner: tagspaces
- License: agpl-3.0
- Created: 2012-11-23T17:25:20.000Z (over 12 years ago)
- Default Branch: develop
- Last Pushed: 2025-05-08T08:05:00.000Z (about 1 month ago)
- Last Synced: 2025-05-08T09:22:41.027Z (about 1 month ago)
- Topics: electron, javascript, note-taking, offline-first, open-source, self-hosting, tagspaces
- Language: TypeScript
- Homepage: https://www.tagspaces.org
- Size: 122 MB
- Stars: 4,253
- Watchers: 97
- Forks: 438
- Open Issues: 90
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-homelab - TagSpaces
- definitive-opensource - TagSpaces
- stars - tagspaces/tagspaces - TagSpaces is an offline, open source, document manager with tagging support (TypeScript)
- my-awesome - tagspaces/tagspaces - taking,offline-first,open-source,self-hosting,tagspaces pushed_at:2025-04 star:4.1k fork:0.4k TagSpaces is an offline, open source, document manager with tagging support (TypeScript)
- awesome-starred - tagspaces/tagspaces - TagSpaces is an offline, open source, document manager with tagging support (javascript)
README

[](https://github.com/tagspaces/tagspaces/releases)
[](https://gurubase.io/g/tagspaces)# 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](https://github.com/tagspaces/browser-extensions) (Web Clipper) for Firefox, Edge, and Chrome to capture online content as local files.

## ๐ Learn More
- ๐ [Website](https://www.tagspaces.org/)
- ๐ฐ [Blog](https://www.tagspaces.org/blog/)
- ๐ [Documentation](https://docs.tagspaces.org/)
- ๐ฌ [Community Forum](https://tagspaces.discourse.group/)
- ๐ [GitHub Issues](https://github.com/tagspaces/tagspaces/issues)---
## ๐ฆ Downloads
Grab the latest release from the [GitHub Releases Page](https://github.com/tagspaces/tagspaces/releases).
Check out the full [changelog](https://www.tagspaces.org/whatsnew/) 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](https://reactjs.org/)
- **User Interface Styling:** [MUI](https://mui.com/)
- **Desktop App Framework:** [Electron](https://electron.atom.io/)
- **Boilerplate:** [Electron React Boilerplate](https://github.com/chentsulin/electron-react-boilerplate)### ๐ Project Structure
```text
src/
renderer/ # Core application logic
main/ # Electron main process
locales/ # Language translation files
node_modules/ # TagSpaces extension modulescordova/ # Deprecated Android 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:
- [Node.js](https://nodejs.org/)
- [npm](https://www.npmjs.com/)
- [Git](http://git-scm.org/)#### 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:
```bash
npm run test-unit
npm run test-playwright
npm run test-playwright-web```
### ๐ป Packaging the Desktop App
Build native apps for each platform:
```bash
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.
### ๐ฑ Android Build (Deprecated)
```bash
npm run version-meta
npm run prepare-cordova
npm run package-android
```### ๐ 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](https://www.tagspaces.org/extensions/).
### ๐ค Contributing
We welcome contributions! Please review and sign the [Contributor License Agreement (CLA)](https://www.tagspaces.org/contribute/) before submitting PRs.
## ๐ Localization
TagSpaces is available in over 20 languages. Help us translate the app by joining our team on [Transifex](https://www.transifex.com/tagspaces/tagspaces/).
## ๐ก Ideas & Suggestions
Have an idea or a feature request? Share it on our [community forum](https://tagspaces.discourse.group/c/feature-requests/6) and join the discussion.
## ๐ Support & Bug Reports
If you encounter a bug or need help, [open an issue](https://github.com/tagspaces/tagspaces/issues) on GitHub.
## โ ๏ธ Known Limitations
TagSpaces is not optimized for locations with more than 100,000 files.
## ๐ก Feeds
- [Blog RSS Feed](http://www.tagspaces.org/blog/rss.xml)
- [GitHub Commits (master)](https://github.com/tagspaces/tagspaces/commits/master.atom)## ๐ License
TagSpaces is dual-licensed under the [AGPL](LICENSE.txt) (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.