The community-maintained guide to building plugins for Unraid® OS
Unraid® is a registered trademark of Lime Technology, Inc. This project is not affiliated with, endorsed by, or sponsored by Lime Technology, Inc.
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. Unraid® is a registered trademark of Lime Technology, Inc. This project is not affiliated with, endorsed by, or sponsored by Lime Technology, Inc. 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 |
| Your First Plugin | Step-by-step tutorial |
| Example Plugins | Real-world plugin references |
| Topic | Description |
|---|---|
| PLG File Reference | .plg installer format & metadata |
| Page Files | Creating web UI pages (.page files) |
| File System Layout | Where plugin files live |
| Event System | Responding to array and system events |
| Plugin Command | Using the plugin CLI tool |
| Topic | Description |
|---|---|
| UI Development | Overview of UI-related docs |
| JavaScript Patterns | Common jQuery patterns & AJAX |
| Form Controls | Standard input elements and styling |
| Tab Pages | Multi-tab settings pages |
| Icons & Styling | FontAwesome, themes, and CSS |
| Topic | Description |
|---|---|
| Advanced Topics | Advanced plugin development guidance |
| Docker Integration | Docker API & container management |
| Update Mechanisms | Version checks and auto-updates |
| Debugging Techniques | Logging, error handling, dev tools |
| Testing | Testing strategies and tools |
| Topic | Description |
|---|---|
| Distribution & Publishing | How to ship and support your plugin |
| Community Applications | Publishing to CA |
| Hosting | Hosting plugin files |
| Support | Supporting users |
| Topic | Description |
|---|---|
| Plugin Command | Using the plugin CLI tool |
| Example Plugins | Links to well-documented plugins |
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