Skip to main content

Addons Manager Documentation

Installation

Installing the Addon

The installation process is straightforward and identical across all operating systems:

  1. Download the addon ZIP file from your order page.
  2. Open Blender and navigate to Edit › Preferences › Add-ons.
  3. Click the Install button in the top-right corner.
  4. Select the downloaded ZIP file and click Install Add-on.
  5. Enable the addon by checking the box next to "Addons Manager".
  6. The addon panel will appear in the 3D Viewport sidebar (press N) under the "Addons Manager" tab.

Configuring Preferences

After installation, you may want to configure the addon's preferences:

  1. Open Edit › Preferences › Add-ons.
  2. Find Addons Manager in the list and expand its preferences panel.
  3. You'll see thethree options: Show Reload Button, option.Show Preferences Button, and Show Folder Button.

Show Preferences Button

This checkbox controls whether a preferences button appears next to each enabled addon. When clicked, it opens Blender's Preferences window with the addon search filtered to that specific addon, so you can access its settings without navigating there manually.

Why it's enabled by default: Quickly jumping to an addon's preferences is a common action for most users, making it a practical addition to the list for everyday use.

When to disable it: If you prefer a more compact interface and rarely need to access individual addon preferences from this panel, you can turn this off to reduce visual clutter.

Show Folder Button

This checkbox controls whether a folder button appears next to each enabled addon. When clicked, it opens the addon's installation directory in your operating system's file explorer (Windows Explorer, Finder, or the default file manager on Linux).

Why it's disabled by default: Opening an addon's folder is an infrequent, technical operation. Typically only needed when manually editing addon files, checking the installed version, or troubleshooting. Hiding it by default keeps the interface clean for regular users.

When to enable it: If you frequently inspect or edit addon files directly on disk, enable this option for quick access to the installation folder from the panel.

Show Reload Button

This checkbox controls whether the hot reload button appears next to each enabled addon. The reload functionality is primarily designed for addon developers who need to test code changes without restarting Blender.

Why it's disabled by default: For most users, the reload button adds unnecessary UI clutter. End users typically don't need to reload addons during normal Blender usage. Keeping this feature hidden by default provides a cleaner, more focused interface.

When to enable it: If you're developing Blender addons or frequently testing addon modifications, enable this option. The reload button will appear to the left of the addon name in the enabled addons list, allowing you to refresh addon code instantly without restarting Blender.

Interface Reference

The Addons Manager panel is located in the 3D Viewport sidebar (press N) under the "Addons Manager" tab. This section explains each control and feature in detail.

Search & Display Mode

The search box allows you to quickly filter addons by name. Type any part of an addon's name and the list will update to show only matching results.

  • Case-insensitive: Searches work regardless of capitalization.
  • Starts-with matching: Search looks for addons whose names begin with your query.
  • Clear search: Delete text in the search box to show all addons again.

Display Mode

Controls which addons appear in the lists. Two modes are available:

Mode Description
Filtered Shows only addons marked as visible. Provides a clean view of your frequently-used addons.
All Shows every installed addon, including those marked as hidden. Useful when you need to find rarely-used addons or those always on (Cycles, import modules, node wrangler, etc).

Refresh Addons

The Refresh Addons button forces Blender to rescan the addons directories and update the internal addon list.

When to use it: Addons manager usually refresh itself when you install or uninstall an addon but if you manually install it by extracting its files directly into the scripts folder (rather than using Blender's Install button), the addon won't appear in the list until you click Refresh.

Preset Management

Presets allow you to save and restore complete addon configurations: which addons are enabled, which are disabled, and all their individual preferences. This is one of the most powerful features of Addons Manager.

Preset Dropdown

The dropdown menu shows all saved presets. Select a preset from the list, then click the Load button next to it to apply that configuration.

What happens when you load a preset:

  1. All currently enabled addons (except Addons Manager itself) are disabled, and their preferences are automatically saved.
  2. Addons specified in the preset are enabled.
  3. Each addon's preferences are restored from the preset data.

Save Current as Preset

Click this button to save your current addon configuration as a new preset. A dialog will prompt you for a preset name.

What gets saved:

  • Which addons are currently enabled.
  • Which addons are currently disabled.
  • All preferences for every addon (both enabled and disabled).

Tip: Name your presets descriptively based on your workflow. Examples: "Modeling", "Rendering", "Animation", "UV Unwrapping", "Development".

Saved Presets Panel

This collapsible panel lists all saved presets with management options for each:

  • Load: Apply the preset configuration.
  • Rename: Change the preset's name. A dialog will prompt for the new name with validation to prevent duplicates or empty names.
  • Delete: Permanently remove the preset. This action cannot be undone.

Addon Lists

Addons are organized into two collapsible sections: Enabled Addons and Disabled Addons. Each section can be expanded or collapsed independently.

Enabled Addons

Shows all currently active addons. Each addon entry displays:

  • Visibility toggle button: Eye icon on the left. Click to hide/show the addon in filtered mode.
  • Reload button (optional): Refresh icon, appears only if enabled in preferences. Hot-reloads the addon without restarting Blender.
  • Addon name: The human-readable name from the addon's bl_info.
  • Disable button: Automatically saves the addon's preferences before disabling it.

The disable button shows different icons depending on whether preferences are saved:

  • Disk icon: This addon has saved preferences that will be restored when re-enabled.
  • Minus icon: This addon has no saved preferences (either it has none, or they haven't been saved yet).

Disabled Addons

Shows all currently inactive addons. Each addon entry displays:

  • Visibility toggle button: Eye icon on the left. Click to hide/show the addon in filtered mode.
  • Addon name: The human-readable name from the addon's bl_info.
  • Enable button: Enables the addon and restores any previously saved preferences.

The enable button shows different icons depending on saved preferences:

  • Disk icon: Saved preferences exist and will be restored upon enabling.
  • Minus icon: No saved preferences exist so addon will enable with default settings.

Visibility System

The visibility system allows you to declutter your addon lists without actually disabling addons. This is separate from the enabled/disabled state.

How Visibility Works

Each addon has a visibility toggle button (eye icon) on the left side of its entry:

  • Eye-open icon (visible): The addon appears in Filtered display mode.
  • Eye-closed icon (hidden): The addon only appears in All display mode.

Use case: You have 50 installed addons but only use 10 regularly. Mark those 10 as visible, hide the rest, and switch to Filtered mode. Your list now shows only the addons you actually need, making it much faster to find and toggle them.

Important: Visibility is purely organizational. It doesn't affect whether an addon is enabled or disabled. It only controls whether the addon appears in your filtered view.

Hot Reload (Nerd Developer Feature)

Hot reload allows addon developers to test code changes without restarting Blender. This feature must be enabled in addon preferences (see Installation section above).

How Hot Reload Works

When you click the reload button next to an enabled addon:

  1. Preferences are saved: All current addon preferences are captured.
  2. Unregister is called: The addon's unregister() function runs, cleaning up UI elements and handlers.
  3. Modules are reloaded: All Python modules belonging to the addon are reloaded from disk, including submodules. They're reloaded in dependency order (deepest submodules first).
  4. Register is called: The addon's register() function runs, re-initializing everything.
  5. Preferences are restored: Saved preferences are reapplied.

Requirements

For hot reload to work properly, your addon must:

  • Be currently enabled.
  • Have valid register() and unregister() functions.
  • Be properly structured as a Python package or module.

Limitations

Hot reload works well for most addons but has some limitations:

  • Persistent data: If your addon stores data in Blender's scene or maintains global state outside of properties, that data may not survive a reload.
  • Complex dependencies: Addons with circular imports or unusual module structures may encounter issues.
  • Errors in unregister(): If unregister() raises an exception, the reload continues but the addon may be left in an inconsistent state.

Troubleshooting: If reload fails, check Blender's System Console (Window › Toggle System Console on Windows, or launch from terminal on Linux/macOS). Detailed error messages and stack traces will appear there.

Best Practices

Organizing Your Workflow with Presets

Task-Based Presets

Create presets organized around specific tasks rather than arbitrary groupings:

  • Modeling: Enable mesh tools, hard surface addons, boolean operators, retopology helpers.
  • UV Unwrapping: Enable UV editing tools, texturing addons, seam marking utilities.
  • Sculpting: Enable sculpting addons, remesh tools, detail transfer addons.
  • Rendering: Enable render engines, lighting tools, material libraries, batch rendering utilities.
  • Animation: Enable animation tools, rigging addons, motion graphics utilities.

Performance Optimization

More enabled addons = longer Blender startup time and higher memory usage. Use presets strategically:

  • Don't enable everything at once. Load only what you need for your current task.
  • Create a "Minimal" preset with just essential addons for quick launches.
  • Create a "Full" preset with everything for when you need maximum flexibility.
  • Switch presets as your work progresses through different stages.

Visibility vs. Presets: When to Use Each

Use Visibility When:

  • You want a cleaner UI without changing what's enabled.
  • You have many installed addons but only regularly interact with a few.
  • You need quick access to your core addons without scrolling through long lists.

Use Presets When:

  • You want to actually change which addons are enabled.
  • You need different addon combinations for different projects or tasks.
  • You want to save and restore specific addon configurations with their preferences.
  • You're switching between distinctly different workflows (modeling vs. rendering vs. animation).

Combining Both:

The most efficient workflow uses visibility and presets together:

  1. Mark your most used addons as visible.
  2. Hide rarely used or system (always on) addons.
  3. Create task based presets for different workflows.
  4. Switch to Filtered mode for daily work.
  5. Switch to All mode when you need to find a hidden addon.

Advanced Usage

Understanding the File Structure

Addons Manager stores all its data in the Blender scripts directory under addon_manager_prefs:

~/.config/blender/[version]/scripts/addon_manager_prefs/

On Windows, this is typically:

%APPDATA%\Blender Foundation\Blender\[version]\scripts\addon_manager_prefs\

Directory Contents

File/Folder Purpose
prefs/ Directory containing individual preference files for each addon (one JSON file per addon).
addon_visibility.json Stores visibility state for each addon (visible/hidden in filtered mode).
presets.json Contains all saved presets with addon states and preferences.

Manual Backup and Restoration

Backing Up Your Configuration

To manually backup your entire Addons Manager configuration:

  1. Close Blender.
  2. Navigate to the addon_manager_prefs directory.
  3. Copy the entire directory to a backup location.

What gets backed up:

  • All presets.
  • All saved addon preferences.
  • All visibility settings.

Restoring from Backup

  1. Close Blender.
  2. Navigate to the addon_manager_prefs directory.
  3. Delete or rename the existing directory.
  4. Copy your backup directory in its place.
  5. Restart Blender.

Transferring Configuration Between Blender Versions

When upgrading to a new Blender version, you can transfer your Addons Manager configuration:

  1. Locate the addon_manager_prefs folder in your old Blender version's scripts directory.
  2. Copy the entire folder.
  3. Paste it into the new Blender version's scripts directory at the same relative path.
  4. Open the new Blender version and verify everything loaded correctly.

Note: This transfers your presets and preferences, but it doesn't transfer the addons themselves. You'll still need to install your addons in the new Blender version.

Editing Presets Manually

Advanced users can edit presets.json directly in a text editor. The file structure is straightforward JSON.

Use cases for manual editing:

  • Bulk-renaming multiple presets.
  • Duplicating presets as templates for variations.
  • Removing corrupted preset data.
  • Merging configurations from multiple Blender installations.

Warning: Always backup presets.json before manually editing. Invalid JSON will cause presets to fail loading.

Understanding Preference Files

Each addon's preferences are stored as individual JSON files in the prefs/ subdirectory. File names are sanitized versions of addon module names.

Example: An addon with module name my_addon would have its preferences stored at:

addon_manager_prefs/prefs/my_addon.json

This architecture provides several benefits:

  • Performance: Loading preferences for one addon doesn't require reading data for all addons.
  • Atomic writes: Each addon's preferences are saved independently, preventing corruption.
  • Debugging: You can inspect or modify individual addon preferences without affecting others.

Troubleshooting

Preset Issues

Preset Won't Load

Symptom: Clicking "Load" on a preset does nothing or shows an error.

Causes and solutions:

  • Corrupted preset data: Open presets.json in a text editor and verify it's valid JSON. Look for missing brackets, quotes, or commas.
  • Missing addons: The preset may reference addons that are no longer installed. Check the System Console for messages about addons that couldn't be enabled.
  • Dependency conflicts: Some addons in the preset may have unmet dependencies. Enable them manually to see specific error messages.

Preset Partially Loads

Symptom: Some addons from the preset enable correctly, but others don't.

Solution: Check the System Console (Window › Toggle System Console) for detailed error messages. Addons Manager logs which addons failed to enable and why. Common reasons include missing dependencies or conflicts with other addons.

Hot Reload Issues

Reload Fails with Error

Symptom: Clicking reload shows an error message and the addon stops working.

Common causes:

  • Syntax errors in code: If your recent changes introduced Python syntax errors, the reload will fail. Check the console for the exact error and line number.
  • Import errors: Missing imports or incorrect module paths will cause reload to fail. Verify all your import statements.
  • Errors in register(): If your addon's register() function raises an exception, the addon won't re-initialize. Check the console for the stack trace.

Recovery: If reload breaks your addon, disable it, fix the code issue, then re-enable it normally.

Reload Succeeds but Changes Don't Appear

Symptom: Reload reports success, but your code changes aren't reflected.

Possible causes:

  • Cached .pyc files: Blender may be loading cached bytecode. Delete __pycache__ directories in your addon folder and try again.
  • UI not updating: Force Blender to redraw by hovering over panels or switching areas.
  • Changes in wrong file: Verify you saved changes to the correct file and that Blender is loading from the right addon directory.

Preference Issues

Preferences Not Saving

Symptom: Changes to addon preferences disappear after disabling and re-enabling.

Causes and solutions:

  • Permission issues: Verify you have write permissions to the addon_manager_prefs directory.
  • Disk space: Ensure you have available disk space.
  • File corruption: Check if the addon's preference file in prefs/ exists and contains valid JSON.

Preferences Reset to Defaults

Symptom: Addon preferences spontaneously reset.

Solution: This usually happens if the addon's preference structure changed (e.g., after an addon update). The old saved preferences may no longer match the new preference schema. Configure the addon with your desired settings again and they'll be saved with the new structure.

General Issues

Addons Manager Panel Doesn't Appear

Symptom: After enabling the addon, the panel doesn't show in the sidebar.

Solutions:

  1. Press N to open the sidebar if it's hidden.
  2. Look for the "Addons Manager" tab. You may need to scroll through the tabs.
  3. If the tab still doesn't appear, disable and re-enable the addon.
  4. Check the System Console for any error messages during addon registration.

Viewing Console Messages

Many issues can be diagnosed by checking console output:

  • Windows: Window › Toggle System Console.
  • Linux/macOS: Launch Blender from a terminal to see console output.

Addons Manager prefixes its messages with [Addons Manager] for easy identification.

Changelog

Version 1.9.9 (Current Release)

  • Added preference option to show/hide hot reload button.
  • Relocated reload button to left side of addon entries.

Version 1.9.7

  • Enhanced code documentation.
  • Improved IDE support with inline documentation.

Version 1.9.6

  • Fixed UTF-8 encoding for international character support.
  • Added defensive validation for addon preferences.
  • Improved cross-platform compatibility.

Version 1.9.5

  • Critical fix: Corrected submodule reload order for hot reload.
  • Fixed race condition in file saves.
  • Added preset name validation.
  • Enhanced rename preset operator with duplicate detection.

Version 1.9.4

  • Simplified EnumProperty implementation for presets.
  • Optimized preference extraction with reduced function calls.
  • Code cleanup: removed unused constants and dev comments.

Version 1.9.3

  • Added module validation before reload operations.

Version 1.9.0

  • Major performance upgrade: individual preference files system.
  • New optimized code for preference management.
  • Huge performance improvement for enable/disable operations.

Version 1.8.5

  • Added hot reload functionality for enabled addons.
  • Implemented preference preservation during reload.
  • Added reload button to UI.

Version 1.8.0

  • Implemented addon visibility filtering system.
  • Added display mode selector (All/Filtered).
  • Toggle visibility button for each addon.

Version 1.7.0

  • Introduced preset system for saving/loading configurations.
  • Save, load, rename, and delete preset operations.
  • Preset management UI panel.

Version 1.6.0

  • Added search functionality.
  • Case-insensitive search implementation.

Version 1.5.0

  • Separated enabled and disabled addon lists.
  • Added collapsible sections with visual indicators.

Version 1.4.0

  • Implemented automatic preference preservation system.
  • Preferences saved on disable, restored on enable.
  • Visual indicators for saved preferences.

Version 1.0.0

  • Initial release with core addon management functionality.
  • Basic enable/disable operations.
  • Foundation for future features.

Contact and Support

Email

For technical support, bug reports, or feature requests:

support@yatima.xyz

When Reporting Bugs

Please include the following information to help diagnose issues quickly:

  • Your Blender version.
  • Your operating system.
  • A description of what you were trying to do.
  • What happened instead of the expected result.
  • Any error messages from the System Console.
  • Steps to reproduce the issue.
💡 Tip: Detailed information helps provide effective solutions faster. The more context you provide, the better we can assist you!

Back to top