![TagSpaces Logo](https://www.tagspaces.org/img/tagspaces-logo.svg) [![GitHub All Releases](https://img.shields.io/github/downloads/tagspaces/tagspaces/total.svg)](https://github.com/tagspaces/tagspaces/releases) # 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. ![TagSpaces with the Markdown Editor](https://www.tagspaces.org/content/v6/tagspaces-lite-demo.avif) ## ๐ŸŒ 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 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: - [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. ### ๐Ÿ“ฑ Mobile Build (Capacitor) Build and run the Android or iOS app via Capacitor: ```bash 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](https://www.tagspaces.org/extensions/). ### ๐Ÿค Contributing We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md), and review and sign the [Contributor License Agreement (CLA)](https://www.tagspaces.org/content/tagspaces-cla-v2.pdf) before submitting PRs. ## ๐ŸŒ Localization TagSpaces is available in over 20 languages. Help us translate the app by joining our team on [Transifex](https://explore.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. 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](LICENSING.md).