Features

The Blender Development for PyCharm plugin offers a rich set of features designed to make extension development as smooth as possible.

Automated Environment Management

See Environment Management for more details.

  • UI Modernization: Provides a Tool Window, Settings, and Run Configuration editors built with modern Kotlin DSL components for a clean and responsive user experience.

  • Blender Discovery: Reliable detection of system-wide Blender installations across Linux and macOS, including support for custom paths via BlenderScanner and BlenderPathUtil.

  • One-Click Downloads: Automatically download and manage multiple Blender versions (4.2, to 5.1) directly from the IDE.

  • Robust Downloader: Reliable extraction and handling of Unix execution permissions post-download via BlenderDownloader and ArchiveUtil.

  • Execution Validation: Proactive and reactive detection of filesystem execution restrictions (e.g., noexec on Linux). The plugin identifies when a partition prevents binary execution and provides user-friendly error messages with direct links to troubleshooting guides.

  • Improved Scanner: Scanning for Blender installations is fast due to version metadata caching. Includes macOS and Linux detection using the which command and clear custom path labeling.

  • Automatic Python Interpreter Setup: When a managed Blender version is downloaded, the plugin automatically locates and configures the bundled Python interpreter for stubs and linting. Streamlined environment configuration for new projects.

  • System Version Detection: Automatically scans your system for existing Blender installations (e.g., in Program Files or /Applications) and lets you use them instantly. Refined cross-platform path handling using Kotlin NIO.2.

  • Add Other System Installs for Blender: Gives you the ability to add a Blender Install not detected by the IDE (I.E if an install is in ~/Apps)

  • Version Switching: Easily switch between managed, system-wide, or custom Blender versions for testing and validation, and making use of the Python Interpreter Setup to ensure .

  • Inline Download Buttons: The Run Configuration editor features a “Download” button next to the Blender version dropdown if the selected version is missing. Starting a Run Configuration with a missing managed version will now trigger an automatic, synchronous download with progress feedback.

  • Global Management: A dedicated tool window on the right sidebar allows you to see what’s installed, delete managed versions, or view discovered system versions.

  • UI Improvements: Optimized Tool Window layout with scrollable tables and dedicated action buttons for easier Blender version management.

  • Connection Status: The Blender Management tool window displays a “Status” label indicating whether PyCharm is actively connected to a running Blender instance.

  • Unix Permission Handling: Automatically ensures that the Blender binary has the required execution permissions on Linux and macOS before startup.

Sandboxed Development

See ../usage/development-testing for more details on sandboxing and isolation.

  • Isolation: Launch Blender in a project-local environment (.blender_sandbox) to prevent conflicts with your main Blender installation.

  • Multiple Source Folders: The “Addon source directory” field supports multiple, comma-separated paths. The plugin creates separate symlinks/junctions for each folder.

  • Project-Specific Config: Each project can have its own user preferences and startup files.

  • User Config Import: Optionally import your system Blender’s user preferences, startup files, and bookmarks into the sandbox.

Real-time Hot-Reloading

See ../usage/hot-reloading for detailed instructions on the hot-reloading workflow.

  • Auto-Reload: Automatically trigger a reload in Blender whenever you save a file in PyCharm.

  • Manual Reload: Use Ctrl+Alt+R (or the Blender menu) to trigger a reload at any time.

  • Robust Cache Purging: The plugin uses a deep purging logic to ensure that Python’s sys.modules cache is cleared, making sure your changes are always reflected.

  • Blender Status Indicator: A real-time status bar widget allows you to monitor Blender connection states (Connected, Disconnected, Not Running) at a glance.

  • Bidirectional Heartbeat: A robust TCP client with bidirectional heartbeat and automatic retry logic ensures connection stability.

Smart Project Templates

See Project Lifecycle for a complete guide on the project creation process.

  • New Project Wizard: Quickly bootstrap new extensions with a structure that mirrors PyCharm’s Pure Python setup. Improved validation and error reporting.

  • Specialized Project Type: A dedicated “Blender Development” project type is available in the New Project dialog.

  • Manifest Configuration: Configure your blender_manifest.toml (metadata, permissions, compatibility) directly during project creation. Uses snake_case for Manifest IDs to comply with Blender’s requirements.

  • Simple Add-on & Module Templates: Quickly create a single-script Blender add-on (legacy bl_info support) or a boilerplate Blender module with standard imports from the New menu.

  • Auto-load Support: Optionally include an auto_load.py helper to handle complex module structures automatically.

  • Automatic Run Configs: Gets you up and running immediately with pre-configured Testing, Build, and Validate profiles.

  • Source Folder Marking: Automatically sets the src folder as the Addon Source root

Integrated CLI Tools

See ../usage/cli-tools for more information on command-line integration.

  • Build: One-click building of your extension into a ZIP distribution.

  • Validate: Ensure your extension meets Blender’s manifest requirements.

  • Custom Commands: Run any blender --command directly from the IDE.

  • Sandbox Management: New tool window for clearing and managing Blender sandboxed environments.

Integrated Testing & Diagnostics

See ../usage/development-testing for more information on testing and telemetry.

  • Unit & Integration Testing: A comprehensive test suite, including headless integration tests for TCP heartbeat and reload logic.

  • Offline Telemetry: Local-only telemetry for debugging and error reporting.

  • Logging: Includes log rotation for efficient disk usage management and expanded debug output for connection handshakes.

Smart UI Integration

  • Blender File Icons: .blend and .blend1 files are automatically marked with a custom Blender color icon.

  • Integrated Logging: A dedicated blender_plugin.log in your project root tracks all operations for easy troubleshooting. See Troubleshooting for details.