Install Obsidian on Linux

Obsidian is a Markdown-based knowledge management app that stores notes as plain files on disk—no proprietary format, no lock-in. On Linux you have two practical installation paths: the official AppImage and the Flatpak from Flathub. Each has real trade-offs. This guide covers both, helps you pick a sensible vault location, and sets up Git-based sync as a free alternative to Obsidian Sync.

AppImage vs Flatpak: Which to Choose

The AppImage is the format Obsidian's developers ship directly. It runs on any reasonably modern x86-64 Linux without any container layer, integrates cleanly with your system fonts and themes, and is the first to receive new versions. The downside is that you manage updates yourself unless you add a helper tool.

The Flatpak from Flathub is sandboxed, updates automatically through any Flatpak-aware software center, and works identically across distros. The sandbox restricts filesystem access by default, which matters when you point Obsidian at vaults in non-standard locations.

• Choose AppImage if you want the latest release quickly and don't mind a manual update step.
• Choose Flatpak if you want automatic updates and are comfortable granting extra filesystem permissions once.

Option A: Install via AppImage

1. Download the AppImage

Go to obsidian.md/download and grab the .AppImage file, or pull it directly from GitHub Releases:

wget https://github.com/obsidianmd/obsidian-releases/releases/download/v1.6.7/Obsidian-1.6.7.AppImage \
  -O ~/Applications/Obsidian.AppImage

Replace the version number with the current release shown on the download page.

2. Make It Executable and Run It

chmod +x ~/Applications/Obsidian.AppImage
~/Applications/Obsidian.AppImage

On first launch, Obsidian asks to set up FUSE integration; agree to it for the desktop entry to work automatically. If FUSE isn't installed, install it first:

# Debian/Ubuntu
sudo apt install libfuse2

# Fedora
sudo dnf install fuse

# Arch
sudo pacman -S fuse2

3. Create a Persistent Desktop Entry

Without a .desktop file, Obsidian won't appear in your application launcher. Create one:

cat > ~/.local/share/applications/obsidian.desktop <<EOF
[Desktop Entry]
Name=Obsidian
Exec=/home/$USER/Applications/Obsidian.AppImage --no-sandbox %u
Icon=obsidian
Type=Application
Categories=Office;TextEditor;
MimeType=x-scheme-handler/obsidian;
EOF

update-desktop-database ~/.local/share/applications

4. Keeping the AppImage Updated

Install appimageupdate or simply re-download when a new release lands. A lightweight approach using a small script in a systemd user timer is practical for servers or headless machines, but on a desktop the manual check once a month is usually fine.

Option B: Install via Flatpak

1. Ensure Flatpak Is Installed and Flathub Is Added

# Debian/Ubuntu
sudo apt install flatpak
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

# Fedora (Flatpak is pre-installed; Flathub may need enabling)
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

# Arch
sudo pacman -S flatpak
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

2. Install Obsidian

flatpak install flathub md.obsidian.Obsidian

3. Grant Access to Your Vault Location

By default the Flatpak sandbox only sees ~/Documents and a few other standard paths. If your vault lives elsewhere—say ~/Notes—grant access explicitly:

flatpak override --user md.obsidian.Obsidian --filesystem=~/Notes

To allow access to any path under your home directory (less secure but convenient):

flatpak override --user md.obsidian.Obsidian --filesystem=home

4. Launch and Update

flatpak run md.obsidian.Obsidian

# Update all Flatpaks including Obsidian
flatpak update

Most desktop environments auto-run flatpak update on login via a background service; no manual step needed on GNOME or KDE.

Choosing a Vault Location

A vault is just a directory. Obsidian creates a hidden .obsidian/ folder inside it to store settings and plugin configs. Pick a location that matches how you intend to sync or back up your notes:

• ~/Notes — simple, easy to remember, works well with Git or rsync.
• Inside a cloud-synced folder (Nextcloud, Dropbox) — convenient but can cause conflicts if Obsidian is open on two machines simultaneously.
• An encrypted volume — good for sensitive notes; mount it before launching Obsidian.

Avoid paths with spaces; some plugins and shell scripts will break. Create your vault directory before opening Obsidian:

mkdir -p ~/Notes/personal

Then in Obsidian's welcome screen choose Open folder as vault and point it at ~/Notes/personal.

Git Sync: Free Alternative to Obsidian Sync

Obsidian Sync costs $4–$10/month. If you have access to any Git remote (GitHub, GitLab, a self-hosted Gitea instance) you can replicate most of its functionality for free using the Obsidian Git community plugin combined with a normal Git repository.

1. Initialize a Git Repo in Your Vault

cd ~/Notes/personal
git init
git checkout -b main

2. Add a .gitignore

Exclude Obsidian's cache and workspace state to avoid noisy diffs:

cat > .gitignore <<EOF
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/
.DS_Store
EOF

3. Push to a Remote

git add -A
git commit -m "Initial vault commit"
git remote add origin [email protected]:youruser/my-vault.git
git push -u origin main

Use SSH keys, not HTTPS with a password, so the Obsidian Git plugin can push without prompting you.

4. Install and Configure the Obsidian Git Plugin

1. In Obsidian open Settings → Community plugins → Browse, search for Obsidian Git, and install it.
2. Enable the plugin, then go to its settings.
3. Set Auto backup interval to something like 10 minutes and enable Auto pull on startup.
4. Optionally enable Push on auto backup so commits go to remote automatically.

The plugin calls the system git binary. For the AppImage this is your normal system Git. For the Flatpak you must also grant access to the Git binary location:

flatpak override --user md.obsidian.Obsidian --talk-name=org.freedesktop.Flatpak

Alternatively, use the isomorphic-git mode in the plugin settings, which bundles its own Git implementation and avoids this issue entirely.

Verification

After installation, confirm Obsidian launches, opens your vault, and that Git is working:

# Check Obsidian process is running after launch
pgrep -a obsidian

# Verify git status inside vault
cd ~/Notes/personal && git status

git status should report nothing to commit, working tree clean after the initial push. Create a test note in Obsidian, save it, then check again—you should see the new .md file listed as untracked or staged depending on plugin timing.

Troubleshooting

• AppImage won't launch / "FUSE not available" — Install libfuse2 (Debian/Ubuntu) or fuse2 (Arch). On kernels 5.15+ with FUSE 3, you may need to run the AppImage with --appimage-extract-and-run as a workaround while the upstream catches up.
• Flatpak can't see vault directory — Run flatpak override --user md.obsidian.Obsidian --filesystem=~/your/path and restart Obsidian.
• Obsidian Git plugin says "git: command not found" inside Flatpak — Switch to isomorphic-git mode in the plugin settings, or use the --talk-name override shown above.
• Wayland: blurry text or scaling issues — Add --enable-features=UseOzonePlatform --ozone-platform=wayland to the Exec line in your .desktop file or the Flatpak launch command. Obsidian is an Electron app and Electron's Wayland support has improved significantly since version 28.
• SSH key not found by Git plugin — Ensure ssh-agent is running in your session and your key is added with ssh-add ~/.ssh/id_ed25519. On GNOME, the keyring handles this automatically once the key is unlocked once per session.