---
title: "Install a plugin ZIP"
description: "Install an AI-created plugin manually and check its behavior in smabar."
canonical: "https://smabar.com/docs/install-plugin-zip/"
lang: en
---

# Install a plugin ZIP

> Install an AI-created plugin manually and check its behavior in smabar.

Canonical HTML version: https://smabar.com/docs/install-plugin-zip/ · Language: en · Publisher: smabar (https://smabar.com)

---

[Build with ChatGPT or Claude](https://smabar.com/build-my-plugin.md) explains how an AI creates the archive. Local plugin code runs with your user permissions. Read the files before installation.

## Expected ZIP structure

```text
my-plugin/
  smabar.json
  plugin.py
  views.py             (if imported)
  locales/
    en.json
    de.json
  README.md
  LICENSE              (when required by reused source)
  ...other imported modules and required assets
```

The manifest's `id` must be `my-plugin` in this example. The entry script named by the manifest must exist. Choose a new ID for a new plugin; simply renaming a bundled example's folder does not change its manifest or tile IDs.

## Install

1. Extract the ZIP into a temporary folder outside `.smabar`. Inspect the complete plugin folder and its README. Check for missing files, secrets, unexpected executables or links outside the folder.
2. Quit smabar so it cannot observe a partially copied plugin. Open the plugins directory: on Linux/macOS, `~/.smabar/plugins/`; on Windows, `%USERPROFILE%\.smabar\plugins\` in File Explorer. Create the `plugins` directory if it does not exist.
3. Check that no folder with the same ID exists. If it does, stop and ask for a new plugin ID or make an explicit update with a backup. Do not merge extracted files into an existing plugin.
4. Move the whole `my-plugin` folder into the plugins directory. The result must be `plugins/my-plugin/smabar.json`, not an extra nested `my-plugin/my-plugin` folder.
5. Start smabar and check the plugin in its settings. Allow any documented Python dependency preparation to finish. smabar provides the runtime and SDK; follow the plugin README for additional local configuration.

## Verify in the app

- Check the tile and every provided flyout, hover or popup: no clipped text, raw translation keys, missing icons or inaccessible controls.
- Try actions and settings; check loading, empty and failure states. If the plugin uses a provider or external service, check it on your own operating system.
- Restart smabar and confirm that intended settings and stored data remain available.
- Review `~/.smabar/logs/plugin-my-plugin.log` (Windows: `%USERPROFILE%\.smabar\logs\plugin-my-plugin.log`) for errors and markup warnings. The [debugging reference](https://smabar.com/docs/plugin-ref-guide-debugging.md) explains them. Remove secrets and personal data before sharing excerpts.

The archive's syntax and file checks do not prove its appearance or behavior in the running app. Give your AI the actual error or a screenshot for a correction. Keep backups outside `.smabar/plugins/`; a backup inside that directory may itself be discovered as a plugin.