nTop 6.2 - External Custom Blocks

Jack Walles

October 01, 2026 15:12

Learn more about the changes happening in nTop 6.20, where we introduce our new External Custom Blocks capability.

External vs. Embedded Custom Blocks

How Paths Work for Custom Blocks

Working with External Custom Blocks

Editing and Hot Reloading an External Custom Block

Replacing a Custom Block Reference

Replacing an Embedded Custom Block

Embedding and Exporting Custom Blocks

Exporting a Custom Block to a File

Collaborating with External Custom Blocks

Overview

Starting in nTop 6.2, Custom Blocks are defined externally to the notebook by default. Instead of being embedded inside your notebook upon import, a Custom Block lives in its own .ntop file on disk. Your notebook holds a reference to that file, much like how a function in code references a definition stored elsewhere.

This changes a fundamental limitation of earlier versions: previously, after importing a Custom Block, any changes made to the source .ntop file required a manual re-import to take effect. Now, nTop watches the source file and updates your notebook automatically.

Impact:

A single Custom Block definition can be shared across many notebooks.
When you update the source .ntop file, every notebook referencing it reflects the change, just like with code.
Custom Block files can be version-controlled, shared via Git, and organized into libraries.

Embedding is still fully supported. When enabled in settings, custom blocks are defined externally by default. However, embedding is now opt-in via right click menus rather than the default behavior upon import.

New Improvements

Custom Blocks as external references - Custom blocks live in their own .ntop file on disk and all notebooks that import that block update automatically when the source changes.
Custom Block libraries - Users can define custom block libraries defined as a folder of .ntop files. These blocks also share the external definition behavior.

External vs. Embedded Custom Blocks

All Custom Blocks have a double line down the left side of the block, indicating that the block is a user-defined collection of other blocks. In nTop 6.2 onward, Custom Blocks are additionally distinguished as either external or embedded:

	External	Embedded
Stored in	A separate .ntop file on disk	Inside the current notebook
Updates	Propagate automatically to all referencing notebooks	Isolated to this notebook
Sharing	Share the file or folder. No re-import needed	Requires manual export and re-import
Default behavior	✅ Yes (new in nTop 6.2)	Opt-in (right click -> embed)

The Imports tab in the left-hand sidebar visually distinguishes external Custom Blocks from embedded ones using a link icon for an external custom block, and a broken link icon for embedded custom blocks.

Custom Block Libraries

There is now a Custom Block Libraries section in the Imports panel. This panel allows custom block libraries, or groups of custom blocks, to be referenced. A library is just a collection of external blocks, with the addition that a Library Name is used as a prefix to libraries rather than relying on absolute paths. The MyBlocks folder is defined by default and has been moved to this panel from the user settings.

How Paths Work for Custom Blocks

nTop stores the path to each external Custom Block using one of three definitions, depending on where the file lives:

	External	Embedded
Stored in	A separate .ntop file on disk	Inside the current notebook
Updates	Propagate automatically to all referencing notebooks	Isolated to this notebook
Sharing	Share the project folder with paths intact. No re-import needed	Share the file alone. No folder structure required
Default behavior	✅ Yes (new in nTop 6.2)	Opt-in

Portability depends on keeping Custom Blocks inside the project folder. If a Custom Block is stored outside the notebook's directory, nTop saves an absolute path. That reference will break when the project is opened on a different machine or moved to a new location. When loading a notebook, for the custom blocks inside the notebook, nTop first checks for a relative path, then the absolute path. If a block with the same name is not defined at either location, an invalid block error will be shown.

For example:

my_project/

├── main_model.ntop

└── blocks/

    ├── engine.ntop

    └── wing.ntop

main_model.ntop references blocks/engine.ntop and blocks/wing.ntop as relative paths. Share or clone the entire my_project/ folder and the Custom Blocks will load correctly for anyone who opens it.

How Paths Work for Libraries

Paths work the same way for Libraries, with one addition. Custom Blocks stored in a Library are referenced by a path preceded by the Library's name (e.g. Library1:file.ntop), which nTop resolves to the library path configured in your settings.

If a user uses Library1:custom_block_1, they can share the file with someone else. If the other person also has a library called `Library1` containing a block called custom_block_1, the dependency will be resolved and the notebook will run. In other words:

C:/Users/person1/Desktop/CBs/Library1/custom_block_1.ntop

and

C:/Users/person2/Downloads/CBs/Library1/custom_block_1.ntop

will be registered as the same custom block.

Opening Existing Files

When loading older files with custom blocks imported, all imported blocks will be embedded, meaning there is no behavioral change to existing notebooks. To update a file and replace the custom blocks with external custom blocks, a user can:

Import the new custom block
Right click on the embedded custom block to replace
If the function signatures match (input and output types), a “Replace With” menu item will be available, which will replace the embedded block with the external one.
The embedded block is now unused and can be deleted.

Additionally, a user can manually swap out the blocks in the notebook.

Working with External Custom Blocks

Importing a Custom Block

Use the Imports tab in the left-hand sidebar to import a .ntop file as a Custom Block. The imported block is linked to the external file by default and becomes available to place via the Search bar or Context Menu by its block name.

If this behavior is not desired, it can be disabled in the settings by setting General -> Import blocks as external references. to off.

Viewing Custom Block Details

Select an external Custom Block to see its details in the Information panel:

The file path relative to your notebook is shown.
Hover over the path label to see the absolute path on disk.
Click the folder icon to open the folder containing the Custom Block.

Hover over a Custom Block entry in the Imports tab to see its details and modification date.

Editing and Hot Reloading an External Custom Block

Right-click an external Custom Block and select Open nTop File. Instead of opening in the block editor, the custom block source .ntop file opens in a new nTop instance.

nTop watches external Custom Block files on disk. When a source file changes, a notification appears in any open notebook that references it. You can:

Update: reload the Custom Block immediately with the latest version.
Cancel: keep using the current version for now. The modified indicator remains in the Imports tab as a reminder. You can apply the update at any time by right-clicking the import in the Imports tab and selecting Update.

If you close and reopen a notebook, it always loads the latest version of all external Custom Blocks from disk.

Note: Changes to an external Custom Block affect all notebooks that reference it, not just the one you are currently working in. The modal alerting the user only shows up for the files currently open.

Replacing a Custom Block Reference

To point an existing Custom Block reference at a different .ntop file, right-click the block in the Imports panel and select Replace with nTop File, then choose the new file.

Replacing an Embedded Custom Block

To replace an embedded Custom Block with an external one, first import the external .ntop file as a Custom Block. Then right-click the original embedded block in the Imports tab and select Replace With. If the function signature of the newly imported block matches, it will appear as an option in the menu — select it to replace all instances of the original. The original embedded block can then be deleted from the Imports tab.

Locating a Custom Block File

Right-click an imported block in the Imports tab to access:

Show in File Explorer opens the folder containing the source file.
Copy Path copies the absolute path to your clipboard.

Removing a Custom Block

Right-click the name in the Imports tab and select Delete. A Custom Block can only be deleted if it has no active instances in the notebook. To clean up all unused Custom Blocks at once, use Remove Unused Blocks in the Imports tab.

Embedding and Exporting Custom Blocks

Embedding a Custom Block

To embed an external custom block, right-click the block in the Notebook or in the Imports tab and select Embed. This bakes the definition directly into your notebook and breaks the link to the source file. After embedding, the Custom Block behaves as in earlier versions of nTop: it is self-contained and no longer updates from disk.

Use embedding when:

You are actively authoring the custom block while it’s being used and frequently changing the block signature.
You need to lock a specific version into a notebook for archival or change-control purposes.
You are sharing a standalone notebook file without the associated Custom Block files.

Exporting a Custom Block to a File

You can export any Custom Block via the right-click context menu using Export Block , which saves it as a .ntop file without changing how it is referenced in the current notebook.

Collaborating with External Custom Blocks

Because external Custom Blocks are separate .ntop files, they work naturally with version control systems like Git. No manual re-importing or block swapping required.

Example: Two engineers collaborating on an aircraft model

Engineer A organizes the project as a folder: main_model.ntop alongside a blocks/ subfolder of Custom Block files.
Engineer A pushes the folder to a shared Git repository.
Engineer B clones the repository. Opening main_model.ntop loads all Custom Blocks automatically from the relative paths.
Engineer B edits blocks/engine.ntop, commits, and pushes.
Engineer A pulls the latest changes. On next open, or via the Update notification, main_model.ntop reflects the updated Custom Block.

Error Handling

Missing Source File

If nTop cannot find the source .ntop file at the stored path (e.g. the file was moved or deleted), the block is replaced in the graph with a Missing Block placeholder and the name of the missing block. Your graph structure is preserved so you can reconnect the reference or replace it without rebuilding from scratch.

Signature Mismatch

If a Custom Block's inputs or outputs change, nTop's behavior depends on how the change is encountered:

Hot reload (file changes while the notebook is open): The Custom Block is replaced in your notebook with an Invalid Custom Block placeholder.

Circular References

nTop detects if a Custom Block directly or indirectly references itself and surfaces an error rather than hanging. This applies to edits made inside nTop and to changes made to source files externally.

Duplicate Block Names

If two different external Custom Block files define blocks with the same internal unique identifier (typically when a file is directly copied and pasted), nTop will surface an error. Rename one of the Custom Blocks to resolve the conflict.

Tips & Best Practices

Keep Custom Blocks close to your notebook. Storing source files in a subfolder next to your .ntop file (e.g. blocks/) makes the project self-contained and easy to share or version-control.
Check the Imports tab. The modified indicator tells you at a glance if any Custom Blocks have changed on disk since your last update.
Embed only when necessary. Keep Custom Blocks external so updates propagate across all notebooks. Embed only for archiving or standalone file sharing.
Use My Blocks Folder for personal libraries. Custom Blocks placed in your My Blocks Folder (File > Settings > General > My Blocks Folder) are automatically available in every nTop session and are imported as external references.
Use Git for team collaboration. External Custom Block files are plain .ntop files. They can be tracked, and shared like any other file in a version-controlled project.