Install and Run Cherry Studio on Linux / Ubuntu (2026 Guide: DEB, AppImage, Flatpak, Ollama, MCP)

Last updated April 2026 — refreshed for Cherry Studio 1.9.x, current Linux packaging (DEB / AppImage / RPM / Flatpak), Ubuntu 24.04 / 25.04 FUSE fixes, and the new MCP and Agent features.

Cherry Studio is an open-source, AGPL-3.0 desktop client that puts OpenAI, Anthropic, Google Gemini, DeepSeek, Qwen, Ollama, LM Studio and 300+ pre-built assistants behind a single interface. This guide is the install-and-run path for Ubuntu users in 2026 — covering the recommended .deb install, AppImage and Flatpak alternatives, the FUSE 3 issue that breaks AppImages on Ubuntu 24.04+, the Ollama and MCP setup, and the practical pitfalls people hit on Reddit.

What changed in 2026The repo moved. The current canonical GitHub is github.com/CherryHQ/cherry-studio (the older kangfenmao/cherry-studio repo is now an archive). Use the CherryHQ release page for downloads.Latest stable is 1.9.3 (released 24 April 2026). The repo ships AMD64 and ARM64 .deb, ARM64 .AppImage, and AArch64 .rpm assets. The community Flatpak (com.cherry_ai.CherryStudio) is the cleanest install path on Ubuntu.DEB is the new default for Ubuntu, not AppImage. Ubuntu 24.04 and 25.04 ship with FUSE 3, which AppImages don't speak natively — you either install libfuse2t64 or pick the .deb.Plugins were renamed to Skills in v1.9, the marketplace was rebuilt around MCPWorld, and a new CherryClaw autonomous agent ships with Telegram / Slack / Discord / Feishu integrations.MCP (Model Context Protocol) is now first-class. Cherry Studio acts as an MCP client and ships flomo as a built-in MCP server; agents are built on the Claude Agent SDK.An Enterprise Edition exists for teams that need centralized model access, shared knowledge bases and access control. Community Edition stays 100% free under AGPL-3.0.

Want the full picture? Read our continuously-updated GPT-5.5 Complete Guide (2026) — benchmarks, pricing, agent capabilities, and migration notes.

TL;DR — the fastest path on Ubuntu

What Cherry Studio actually is in 2026

Cherry Studio is a TypeScript + Electron desktop client that gives you one chat surface for every major LLM provider. As of late April 2026 the project sits at roughly 44.8k GitHub stars and ships several releases per month. Pre-configured providers include OpenAI, Anthropic (Claude), Google Gemini, DeepSeek, Qwen, Mistral, Azure OpenAI, Perplexity, Groq, Together, OpenRouter, Cohere, MiniMax, Zhipu and dozens more. Local models work through Ollama, LM Studio and any OpenAI-compatible endpoint.

What makes it a category leader rather than just another wrapper:

• Multi-model side-by-side. Run the same prompt across, say, Claude 4.7 Sonnet, GPT-5.5 and DeepSeek V4 in parallel and compare answers in one window.
• Built-in RAG knowledge base. Drop PDFs, Word, PowerPoint, Excel, Markdown or URLs in. Cherry Studio chunks, embeds and indexes them; queries are routed through the embedding model you pick.
• MCP client. Connect filesystem, GitHub, Slack, Notion, flomo and any MCPWorld marketplace server. Tool calls are visible in-chat with diff viewer, line numbers and syntax highlighting (added in v1.9.1).
• CherryClaw autonomous agent. A persistent agent with personality, scheduled tasks, sandboxed filesystem and direct integrations with Telegram, Discord, Feishu, Slack, WeChat and QQ. Built on the Claude Agent SDK.
• Skills (renamed from "Plugins" in v1.9.1) — Agent Plugins, Command Plugins and Skill Plugins, managed per-agent with workspace symlinks (added in v1.9.2).

It is a GUI client, not a model runner. If you want to host the actual weights, you still need Ollama or LM Studio behind it.

Prerequisites

• OS: Ubuntu 22.04 LTS or newer (24.04 LTS recommended; 25.04 works). 20.04 still works via AppImage but is two LTS cycles behind.
• Architecture: x86_64 or ARM64. Both are first-class.
• RAM: 4 GB minimum for cloud-only use. If you'll run local models via Ollama, follow the model's own VRAM/RAM requirements (8 GB+ for 8B models, 32 GB+ for 70B quants).
• Disk: ~600 MB for the app itself; the v1.9.3 AMD64 .deb is 162 MB and unpacks to ~500 MB.
• Permissions: sudo for the .deb install, none for AppImage or Flatpak user installs.
• Network: outbound HTTPS to your provider endpoints. Local Ollama doesn't need internet after the first model pull.
• API keys for whichever cloud providers you want to wire up.

Install method 1 — DEB package (recommended for Ubuntu)

This is what the project tells modern Ubuntu users to use. It installs to /opt/Cherry Studio, registers a desktop launcher, and updates cleanly through apt when you replace the file.

# 1. Pick the right architecture
ARCH=$(dpkg --print-architecture)   # amd64 or arm64

# 2. Grab the latest release (1.9.3 at time of writing)
cd ~/Downloads
wget "https://github.com/CherryHQ/cherry-studio/releases/download/v1.9.3/Cherry-Studio-1.9.3-${ARCH}.deb"

# 3. Install
sudo apt install "./Cherry-Studio-1.9.3-${ARCH}.deb"

# 4. Launch
cherry-studio   # or click the launcher in your app grid

sudo apt install ./file.deb is preferred over sudo dpkg -i because apt resolves transitive dependencies in one shot. If you do go with dpkg, follow it with sudo apt-get install -f to fix any missing libs.

Install method 2 — AppImage (portable)

AppImage is still useful for Ubuntu 20.04 / 22.04, sandboxed test boxes, or systems where you can't use sudo. On Ubuntu 24.04 and newer it needs one extra step because the system ships FUSE 3 and AppImage tooling expects FUSE 2.

# Ubuntu 22.04 and earlier
sudo apt install libfuse2

# Ubuntu 24.04 / 25.04 — the package was renamed for the t64 ABI bump
sudo apt install libfuse2t64

# Now run the AppImage
cd ~/Downloads
chmod +x Cherry-Studio-1.9.3-arm64.AppImage   # or x86_64 build
./Cherry-Studio-1.9.3-arm64.AppImage

libfuse2t64 coexists with libfuse3 — installing it doesn't break anything else on the system. Do not install the bare libfuse package; that's a different shim and can leave the system in a broken state.

For desktop integration (a menu entry, icon, double-click-to-run), drop the AppImage into ~/Applications/ and install AppImageLauncher — it'll catch the first launch and offer to register it.

Install method 3 — Flatpak (sandboxed)

FOSS Force's 2026 review recommends the Flatpak path because it's distro-agnostic and updates with the rest of your Flathub apps. If your Ubuntu install doesn't already have Flatpak:

sudo apt install flatpak gnome-software-plugin-flatpak
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

flatpak install flathub com.cherry_ai.CherryStudio
flatpak run com.cherry_ai.CherryStudio

Trade-off: the Flatpak sandbox restricts filesystem access. If you plan to point Cherry Studio at a local folder of PDFs for the knowledge base, grant the path with Flatseal or run flatpak override --user --filesystem=~/Documents com.cherry_ai.CherryStudio.

First launch and provider setup

1. Pick a language and theme

The first-run wizard sets language and dark/light mode. These are changeable later under Settings → General.

2. Add a cloud provider (example: Anthropic Claude 4.7 Sonnet)

1. Click the gear icon → Model Services.
2. Pick the provider from the pre-configured list (Anthropic, OpenAI, Google, DeepSeek, Qwen, OpenRouter, etc.).
3. Paste your API key.
4. Leave API Host on the default unless you're routing through a proxy or a self-hosted gateway like LiteLLM. For Anthropic that's https://api.anthropic.com; for OpenAI it's https://api.openai.com.
5. Click Check — Cherry Studio fetches the available model list from the provider. Toggle on the models you want to expose in the chat picker.

3. Add Ollama for local models

# On the same machine
curl -fsSL https://ollama.com/install.sh | sh
sudo systemctl enable --now ollama
ollama pull llama3.3:8b
ollama pull qwen2.5-coder:7b

In Cherry Studio: Settings → Model Services → Ollama. The default API Host is http://localhost:11434/; the API key field can be left blank. Click + Add and enter the exact tag you pulled (e.g. llama3.3:8b). Repeat for each model.

Hosting Ollama on a different machine? Set OLLAMA_HOST=0.0.0.0:11434 on that box (via systemctl edit ollama), open the firewall port, then point Cherry Studio at http://<host-ip>:11434/.

4. Wire up the knowledge base

1. Settings → Knowledge Base → + Add.
2. Pick an embedding model. Good 2026 defaults: nomic-embed-text via Ollama (free, local), OpenAI text-embedding-3-large (cloud), or Voyage voyage-3-large (best on MTEB English benchmarks at the time of writing — verify on the MTEB leaderboard).
3. Drag PDFs, .docx, .pptx, .xlsx, .md or URLs in. Cherry Studio chunks, embeds and stores vectors in a local DB.
4. Run a retrieval test from the same panel — it shows you the chunks that would be passed to the LLM. Use this to debug bad answers before you blame the model.

5. Connect MCP servers

Settings → MCP Servers. Stock entries cover filesystem, GitHub, fetch, time, sqlite and (since v1.9.1) flomo. Browse the MCPWorld marketplace for community servers; for everything else paste a JSON config of the form {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]}.

How to choose: Cherry Studio vs the alternatives

Decision tree:

• Want one desktop app to talk to every provider plus your local Ollama, with a real knowledge base and tool use? → Cherry Studio.
• Mostly running local GGUFs and want the slickest model browser? → LM Studio.
• Need a multi-user web UI for a team behind a VPN? → Open WebUI.
• Want minimum surface area, just chat with a few APIs? → Chatbox.

Performance and benchmark notes

Cherry Studio is a thin Electron client; the wall-clock latency you see is dominated by the upstream model, not by the UI. A few useful 2026 reference points when you're deciding which provider to wire up:

• Frontier closed models (Claude 4.7 Sonnet, GPT-5.5, Gemini 2.5 Pro): top of LMArena on coding and reasoning categories. Use these for production-grade tasks.
• Open-weight frontier (DeepSeek V4, Qwen 3.5 / 3.6, Llama 4): close to the closed frontier on most benchmarks; cheaper or runnable locally on a single H100/MI300X. Cherry Studio can hit them via DeepSeek's API, Together, Groq or your own Ollama install.
• Local 7B–8B (Llama 3.3 8B, Qwen 2.5 Coder 7B, Gemma 4 9B): fine on a 16 GB MacBook or a 12 GB GPU. Useful for the knowledge-base summarization loop where latency matters more than peak quality.
• Embeddings: pick from the MTEB leaderboard. voyage-3-large and text-embedding-3-large are strong cloud choices; nomic-embed-text is the leading free local option.

The Electron startup cost on a modern Ubuntu desktop is around 1.5–3 seconds cold and under a second warm. The knowledge-base ingest speed is bottlenecked by the embedding model — local nomic-embed-text on a CPU embeds roughly 10–30 chunks per second; the OpenAI cloud endpoint is faster but rate-limited.

Common pitfalls and troubleshooting

AppImage refuses to launch on Ubuntu 24.04 / 25.04

The error is some form of error loading libfuse.so.2. Fix:

sudo apt install libfuse2t64

Or switch to the .deb. This is the single most common open issue on the project's tracker for Ubuntu users.

"Permission denied" running the AppImage

chmod +x Cherry-Studio-1.9.3-*.AppImage

Files downloaded via a browser don't carry the executable bit by default.

Provider connection fails with 401 / 403

• Re-paste the key — invisible whitespace from a clipboard manager is the usual culprit.
• Confirm the API host. Some Anthropic enterprise tenants use a custom endpoint; some Azure OpenAI deployments use a regional URL.
• Behind a corporate proxy: Settings → General → Network → set HTTP/HTTPS proxy.

Ollama model not appearing in the picker

Ollama doesn't auto-publish a model list; you have to add the tag manually under the Ollama provider. Run ollama list in a terminal and copy the NAME column verbatim (case sensitive, including the :tag).

Knowledge base returns irrelevant chunks

• Try a stronger embedding model. Switching from a 384-dim multilingual MiniLM to text-embedding-3-large or voyage-3-large usually moves retrieval quality up a tier.
• Re-chunk: shorter chunks (300–500 tokens) help precision; longer chunks (800–1200) help recall.
• Use the built-in retrieval test panel before blaming the model.

Flatpak version can't read your files

flatpak override --user --filesystem=~/Documents com.cherry_ai.CherryStudio
flatpak override --user --filesystem=~/Projects com.cherry_ai.CherryStudio

Or use Flatseal if you prefer a GUI.

High GPU memory usage on Wayland / NVIDIA

Electron apps on NVIDIA + Wayland sometimes run with software rendering and chew CPU. Force hardware acceleration:

cherry-studio --enable-features=UseOzonePlatform --ozone-platform=wayland

If artifacts appear, fall back to X11: --ozone-platform=x11.

What was removed and why

• Wine instructions for the Windows build. Native Linux DEB and AppImage cover x86_64 and ARM64; the Windows build under Wine added zero value and broke on every Wine release. If you've ended up here from a 2024 tutorial telling you to wine CherryStudio-Setup.exe, ignore it.
• The kangfenmao/cherry-studio repo. The project moved to the CherryHQ org in mid-2025; the old URL still resolves but is no longer the source of truth for releases.
• The "Plugins" name. Renamed to "Skills" in v1.9.1 with a unified Skills management interface. If you see "plugins" in older guides, mentally substitute "skills."
• Standalone marketplace. Replaced by MCPWorld for MCP servers and a Skills marketplace for in-app extensions.

Extending Cherry Studio: agents, MCP and the Codersera angle

The 2026 release line turned Cherry Studio from "chat client with knowledge base" into "lightweight agent host." If you're a solo developer or a small team, that's enough to replace several SaaS tools. If you're a hiring manager who'd rather have an experienced engineer wire this into a production workflow than spend two weeks on it yourself, Codersera helps companies hire vetted remote developers who do exactly this kind of integration work — MCP servers, RAG pipelines, agent orchestration.

Two patterns worth knowing:

1. Local-first RAG. Ollama for embeddings + Cherry Studio's knowledge base + MCP filesystem server pointed at a docs directory. Zero cloud cost, all data stays on the machine. The same shape as the Ollama-on-Ubuntu setup but with Cherry Studio handling chunking and retrieval.
2. Hybrid agent. CherryClaw routed to Claude 4.7 Sonnet for planning, with the filesystem MCP server scoped to a sandbox directory and a GitHub MCP server for PR review. The agent runs unattended on a schedule.

Cross-platform setup notes: the Windows guide and macOS guide cover the same workflow on those OSes.

Uninstalling Cherry Studio

# DEB
sudo apt remove cherry-studio

# AppImage — just delete the file
rm ~/Applications/Cherry-Studio-*.AppImage
rm ~/.local/share/applications/cherry-studio.desktop  # if AppImageLauncher registered it

# Flatpak
flatpak uninstall com.cherry_ai.CherryStudio

# User data (chats, knowledge base, settings) — only if you really want to nuke it
rm -rf ~/.config/CherryStudio

FAQ

Is Cherry Studio free?

Yes. Community Edition is AGPL-3.0 and has no paywall, no trial, no feature gates. Commercial use is permitted as long as you respect AGPL-3.0. The separate Enterprise Edition (bd@cherry-ai.com for pricing) adds centralized model management, SSO and on-prem deployment for teams.

Does Cherry Studio run models locally, or do I still need API keys?

Both options work. Cherry Studio is a client — it doesn't run weights itself. For local inference, install Ollama or LM Studio and point Cherry Studio at it. For cloud models, paste an API key from OpenAI, Anthropic, Google, DeepSeek, etc.

Should I use the DEB or the AppImage?

On Ubuntu 22.04+ use the DEB. It's the smallest install, integrates with your app menu, and avoids the FUSE situation entirely. AppImage is a portable fallback; Flatpak is best for sandboxed setups.

Does it support Claude 4.7, GPT-5.5, DeepSeek V4 and Llama 4?

Yes. The provider list refreshes from each vendor's API on demand, so any model your API key can reach shows up in the picker. Local Llama 4 quants run via Ollama.

Will it work with MCP servers I already have configured for Claude Desktop?

Mostly yes. Cherry Studio reads the standard MCP JSON config; copy the relevant mcpServers entries into Settings → MCP Servers. A handful of Claude-specific paths may need adjusting.

Can I run it on a Raspberry Pi 5?

Yes — use the ARM64 .deb. Performance for cloud calls is fine. Local inference on the Pi itself is tight; offload to a beefier machine and connect via Ollama remote.

Does Cherry Studio store my API keys safely?

Keys are stored encrypted in the local config directory under ~/.config/CherryStudio. They never leave your machine except in the outbound API calls you trigger.

Is there a CLI or headless mode?

No. It's an Electron desktop app. For headless / scripted access, talk to the underlying provider APIs directly or run an MCP server that exposes the same workflow.

References and further reading

1. CherryHQ/cherry-studio on GitHub — canonical repo, README, and source.
2. Cherry Studio releases page — every version, every Linux asset (DEB / AppImage / RPM).
3. v1.9.1 release notes — CherryClaw agent, Plugins → Skills rename, MCP additions.
4. Cherry Studio docs — Ollama provider setup.
5. Cherry Studio docs — Knowledge Base tutorial.
6. FOSS Force (Feb 2026): Run your favorite LLMs on Linux with Cherry Studio — independent Linux-focused review.
7. AppImage docs — FUSE troubleshooting.
8. It's FOSS — Can't Run AppImage on Ubuntu 24.04? Here's How to Fix it.
9. MTEB leaderboard on Hugging Face — pick an embedding model with current numbers.
10. LMArena leaderboard — current LLM rankings to inform which provider to wire up first.