Skip to main content
Every Obsidian plugin requires a manifest.json file that defines the plugin’s metadata, version information, and requirements. This file is essential for plugin distribution and compatibility.

​
Manifest Structure

The manifest is a JSON file located at the root of your plugin directory: 
{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "minAppVersion": "0.15.0",
  "description": "This is a sample plugin for Obsidian.",
  "author": "Your Name",
  "authorUrl": "https://yourwebsite.com",
  "fundingUrl": "https://github.com/sponsors/yourusername",
  "isDesktopOnly": false
}

​
Required Fields

These fields must be present in every manifest:

​
id

The unique identifier for your plugin. Must be globally unique across all Obsidian plugins. 
{
  "id": "my-unique-plugin-id"
}
Once published, the plugin ID cannot be changed. Choose carefully!
Rules:
  • Use lowercase letters, numbers, and hyphens
  • No spaces or special characters
  • Should be descriptive but concise
  • Must be unique in the Obsidian plugin ecosystem
Examples:
  • calendar
  • dataview
  • obsidian-git
  • tasks

​
name

The display name shown to users in the Community Plugins browser and settings: 
{
  "name": "My Awesome Plugin"
}
Guidelines:
  • Use proper capitalization
  • Keep it clear and concise
  • Avoid redundant terms like “Obsidian” or “Plugin”

​
version

The current version of your plugin, following Semantic Versioning (semver): 
{
  "version": "1.2.3"
}
Use Semantic Versioning: MAJOR.MINOR.PATCH
  • MAJOR: Breaking changes
  • MINOR: New features (backwards compatible)
  • PATCH: Bug fixes (backwards compatible)

​
minAppVersion

The minimum Obsidian version required to run your plugin: 
{
  "minAppVersion": "0.15.0"
}
Choosing the right version:
  • Use the oldest version that supports all APIs you use
  • Check the API documentation for @since tags
  • Consider your target audience (desktop vs. mobile)
You can check the current Obsidian API version using the apiVersion constant exported from the Obsidian module.

​
description

A brief description of what your plugin does: 
{
  "description": "Adds calendar functionality to Obsidian, allowing you to visualize and manage your daily notes."
}
Guidelines:
  • Keep it concise (1-2 sentences)
  • Focus on the main functionality
  • Avoid marketing language
  • Be clear about what the plugin does

​
author

Your name or username: 
{
  "author": "Jane Developer"
}

​
Optional Fields

These fields are optional but recommended:

​
authorUrl

A URL to your website or profile: 
{
  "authorUrl": "https://github.com/username"
}
Common options:
  • Personal website
  • GitHub profile
  • Twitter/X profile
  • Professional portfolio

​
fundingUrl

A URL where users can support your work: 
{
  "fundingUrl": "https://github.com/sponsors/username"
}

GitHub Sponsors

https://github.com/sponsors/username

Buy Me a Coffee

https://www.buymeacoffee.com/username

PayPal

https://paypal.me/username

Patreon

https://www.patreon.com/username

​
isDesktopOnly

Indicates whether the plugin requires desktop-only APIs: 
{
  "isDesktopOnly": true
}
Set to true if your plugin:
  • Uses Node.js APIs (fs, path, child_process, etc.)
  • Uses Electron APIs
  • Interacts with the local file system directly
  • Requires features not available on mobile
Set to false or omit if your plugin:
  • Uses only web APIs
  • Uses only the Obsidian API
  • Should work on both desktop and mobile
If you set isDesktopOnly: false, thoroughly test your plugin on mobile before publishing.

​
TypeScript Interface

The manifest structure is defined in the Obsidian API: 
export interface PluginManifest {
  dir?: string;           // Set automatically by Obsidian
  id: string;
  name: string;
  author: string;
  version: string;
  minAppVersion: string;
  description: string;
  authorUrl?: string;
  isDesktopOnly?: boolean;
}
You can access your plugin’s manifest at runtime: 
export default class MyPlugin extends Plugin {
  async onload() {
    console.log('Plugin ID:', this.manifest.id);
    console.log('Plugin version:', this.manifest.version);
    console.log('Min app version:', this.manifest.minAppVersion);
  }
}

​
Version Compatibility

​
Checking API Features

Use the @since tags in the API documentation to determine which version introduced a feature: 
// This feature requires 0.15.0 or higher
if (this.manifest.minAppVersion >= '0.15.0') {
  // Use the feature
}

​
Supporting Multiple Versions

For maximum compatibility, check feature availability at runtime: 
async onload() {
  // Feature available since 0.15.0
  if (this.app.workspace.getActiveViewOfType) {
    const view = this.app.workspace.getActiveViewOfType(MarkdownView);
  } else {
    // Fallback for older versions
    console.log('Feature not available in this Obsidian version');
  }
}

​
Complete Examples

​
Simple Plugin

{
  "id": "word-counter",
  "name": "Word Counter",
  "version": "1.0.0",
  "minAppVersion": "0.15.0",
  "description": "Displays word count in the status bar.",
  "author": "Jane Developer"
}

​
Feature-Rich Plugin

{
  "id": "advanced-tables",
  "name": "Advanced Tables",
  "version": "2.1.0",
  "minAppVersion": "1.0.0",
  "description": "Improved table navigation, formatting, and manipulation in Markdown.",
  "author": "Jane Developer",
  "authorUrl": "https://github.com/janedeveloper",
  "fundingUrl": "https://github.com/sponsors/janedeveloper",
  "isDesktopOnly": false
}

​
Desktop-Only Plugin

{
  "id": "local-file-sync",
  "name": "Local File Sync",
  "version": "0.5.0",
  "minAppVersion": "0.15.0",
  "description": "Synchronizes your vault with a local directory using file system watchers.",
  "author": "John Developer",
  "authorUrl": "https://johndeveloper.com",
  "fundingUrl": "https://buymeacoffee.com/johndeveloper",
  "isDesktopOnly": true
}

​
Best Practices

Unique ID

Choose a unique, descriptive ID that won’t conflict with other plugins.

Semantic Versioning

Follow semver strictly for predictable version updates.

Conservative minAppVersion

Set the minimum version as low as possible for maximum compatibility.

Clear Description

Write a concise, accurate description of your plugin’s purpose.

Test Mobile

If not desktop-only, thoroughly test on mobile before publishing.

Provide Funding

Include a funding URL to enable user support.

​
Validation

Obsidian validates the manifest when loading plugins. Common errors: 
Error: manifest.json missing required field 'id'
Ensure all required fields are present: id, name, version, minAppVersion, description, author.
Error: Invalid version format in manifest.json
Version must follow semver format: MAJOR.MINOR.PATCH (e.g., 1.0.0, 2.1.3).
Error: Invalid plugin ID format
ID must contain only lowercase letters, numbers, and hyphens. No spaces or special characters.

Plugin Lifecycle

Learn how the manifest is used during plugin loading

Obsidian Manifest Reference

Official Obsidian manifest documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us