The community-maintained guide to building plugins for Unraid OS
📚 The full documentation is available at: mstrhakr.github.io/unraid-plugin-docs
This is the unofficial, community-driven documentation for developing plugins for Unraid OS. The Unraid plugin system is powerful but has historically lacked comprehensive documentation. This project aims to fill that gap by providing clear, well-organized, and up-to-date resources for plugin developers.
⚠️ Disclaimer: This is not official Lime Technology documentation. While every effort is made to ensure accuracy, please verify critical information against official sources and existing plugins.
New to Unraid plugin development? Start here:
- Introduction to Plugins - What are plugins and how do they work?
- Plugin File Structure - Anatomy of a
.plgfile - Your First Plugin - Step-by-step tutorial
- Web UI Pages - Creating
.pagefiles for the web GUI
| Topic | Description |
|---|---|
| Introduction | Overview of the Unraid plugin system |
| PLG File Reference | Complete reference for .plg XML structure |
| Page Files | Creating web UI pages (.page files) |
| Plugin Lifecycle | Installation, updates, and removal |
| File System Layout | Where files go and why |
| Topic | Description |
|---|---|
| Page Headers | Menu, Title, Type, Icon, and more |
| Dynamix Markdown | The form syntax used in Unraid UI |
| PHP Integration | Using PHP in your pages |
| JavaScript & AJAX | Client-side scripting |
| CSS & Theming | Styling your plugin UI |
| Topic | Description |
|---|---|
| Event System | Responding to array start/stop, Docker, etc. |
| Configuration Files | Storing and reading plugin settings |
| Shell Scripts | Background tasks and automation |
| Docker Integration | Working with Docker containers |
| Topic | Description |
|---|---|
| Package Building | Creating .txz packages |
| Versioning | Version strategies and update checking |
| Community Applications | Publishing to the CA App Store |
| Best Practices | Tips from experienced developers |
| Topic | Description |
|---|---|
| Plugin Command | Using the plugin CLI tool |
| API Reference | Available PHP functions and variables |
| Example Plugins | Links to well-documented plugins |
| Troubleshooting | Common issues and solutions |
At a high level, an Unraid plugin consists of:
┌─────────────────────────────────────────────────────────────────┐
│ myplugin.plg │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ XML-based installer that: │ │
│ │ • Downloads and extracts packages │ │
│ │ • Runs install/remove scripts │ │
│ │ • Defines plugin metadata (name, version, author) │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ myplugin-package.txz │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Slackware package containing: │ │
│ │ /usr/local/emhttp/plugins/myplugin/ │ │
│ │ ├── myplugin.page (Web UI) │ │
│ │ ├── myplugin.settings.page │ │
│ │ ├── default.cfg │ │
│ │ ├── php/ │ │
│ │ ├── scripts/ │ │
│ │ ├── javascript/ │ │
│ │ └── event/ │ │
│ │ ├── started │ │
│ │ └── stopping_docker │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
| Path | Purpose | Persistence |
|---|---|---|
/boot/config/plugins/ |
Plugin files stored on USB flash | ✅ Survives reboot |
/boot/config/plugins/myplugin/ |
Plugin config and cached files | ✅ Survives reboot |
/usr/local/emhttp/plugins/myplugin/ |
Active plugin files (web UI) | ❌ RAM disk |
/var/log/plugins/ |
Symlinks indicating installed plugins | ❌ RAM disk |
/tmp/plugins/ |
Downloaded plugin files for updates | ❌ Temporary |
Plugins can respond to system events by placing executable scripts in their event/ directory:
| Event | Triggered When |
|---|---|
driver_loaded |
Early in emhttp initialization |
starting |
Array start begins |
array_started |
Array devices are valid |
disks_mounted |
Disks and shares are mounted |
docker_started |
Docker service starts |
libvirt_started |
VM service starts |
started |
Array start completes |
stopping |
Array stop begins |
stopping_docker |
About to stop Docker |
stopping_libvirt |
About to stop VMs |
unmounting_disks |
About to unmount disks |
stopped |
Array has stopped |
poll_attributes |
SMART data polled |
See Event System for full details.
- Edit files directly in
/usr/local/emhttp/plugins/myplugin/on your server - Refresh the browser to see changes (PHP/HTML changes are instant)
- A reboot will restore original files from the package, so copy changes back to your source!
# Install a plugin
plugin install /path/to/myplugin.plg
# Check for plugin updates
plugin check myplugin.plg
# Update a plugin
plugin update myplugin.plg
# Remove a plugin
plugin remove myplugin.plg
# Get plugin version
plugin version /var/log/plugins/myplugin.plg
This documentation is a community effort! Contributions are welcome:
- Found an error? Open an issue
- Want to add content? Submit a pull request
- Have questions? Start a discussion
See CONTRIBUTING.md for guidelines.
- Unraid Forums - The primary community hub
- Unraid Documentation - Official docs
- Plugin Support Forum
- Programming Forum
- Community Applications Plugin - The app store for plugins
- Dynamix Plugins - Reference implementations by @bonienl
- Plugin Template Discussions
- How does the plugin system work? - Original documentation (partially outdated)
This documentation is licensed under CC BY-SA 4.0. Code examples are provided under the MIT License.
Made with ❤️ by the Unraid community
unraid.net