Creating a SketchUp Extension

This article is mostly aimed at new developers but can also be useful to those with previous development experience but new to SketchUp. This article focuses on the technical aspects of a valid SketchUp extension. For the more creative aspects of extension development, see Writing a Useful Snippet. If you are new, we recommend starting with Writing your first code.

What is a SketchUp Extension?

A SketchUp extension is a piece of software that extends the capabilities of SketchUp. It could be a new drawing tool, a content library or a way to automate a tedious and time consuming task.

Sometimes the phrases "plugin" and "extension" are used interchangeably, with extension being the more modern and preferred term. However, technically extensions are a subset of plugins that adhere to certain rules to avoid clashes with other plugins. There are still "non-extension" plugins used in the SketchUp community, although they should be phased out, and the term plugin is dying with them.

In SketchUp, all plugins/extensions run in a shared Ruby environment and risk clashing with each other if not built correctly. Extensions are a way to encapsulate the code to avoid these clashes. Just because it works great on your machine doesn't mean it plays nice with other plugins/extensions. Extensions also store metadata such as version number, author and description, increase portability and more. When developing for SketchUp, please make sure your creation is an actual extension, to ensure proper functionality.

Creating an Extension

Wrapping Namespace Module

If two plugins define a top level method or constant by the same name and a user installs both of them, they will clash. The latter to be loaded will override and replace the former, and typically the former will stop working. To ensure this doesn't happen, wrap everything you define under your own namespace module. Only one top level namespace is allowed per extension.

# Bad
def draw_cube
  # code...
end

# Someone else also being bad
def draw_cube
  # Other code... (!)
end

# Good
module JaneDoe
  module CubeMaker
    def self.draw_cube
      # code...
    end
  end
end

# Also good
module TureSventon
  module CubeMaker
    def self.draw_cube
      # Other code...
    end
  end
end

While this doesn't completely rule out naming clashes, it limits the potential for a clash to just the outer module. To reduce the risk further, make sure to use a name that is unlikely to be used by anyone else, such as your registered company name or full personal name. Traditionally extension developers have often used their initials but as the developer community grows it's good to use a longer name with less risk of overlap.

File Structure

Historically SketchUp plugins dumped all of their files directly into the Plugins folder. This meant two plugins could clash if they had a file by the same name. It also meant it could be tricky to fully uninstall a plugin as you didn't know what files belonged to it. Delete the wrong file and a different plugin stops working!

With an extension, only two items are allowed in the Plugins folder: the root .rb file and the support folder by the same name (excluding the .rb file extension). All other files go into the support folder. This allows for easy uninstallation and easy transfer between machines. you can even uninstall from the Extension Manager within SketchUp, and never have to actually see the Plugins folder.

Avoid changing the contents of the support folder after the extension is installed. Doing so could interfere with extension signing and with other users if the extension is loaded from a shared folder. If you need to save user settings or user content to file, prefer the user's document folder or appdata.

Root RB

The root .rb file defines the SketchupExtension object with metadata such as name, author and description, as well as a path to load the remaining extension from. All other code should go into the support folder, not the root .rb file.

The root .rb file always loads when SketchUp starts (if installed to the Plugins folder) but the rest of the extension can be disabled through the Extension Manager. If the extension is disabled, no additional files should load. No menus or toolbars should appear. Only the metadata should be read, nothing else.

module JanDoe
  module CubeMaker
    EXTENSION = SketchupExtension.new(
      "JD Cube Maker", "jane_doe_cube_maker/main"
    )
    EXTENSION.creator     = "Jane Doe"
    EXTENSION.description = "Draw cubes."
    EXTENSION.version     = "1.0.0"
    EXTENSION.copyright   = "2025 Jane Doe"
    Sketchup.register_extension(EXTENSION, true)
  end
end

Note that the .rb file extension is excluded from the file path in the example. By default Extension Warehouse encrypts extensions and turns .rb files into .rbe files. By omitting the file path you allow SketchUp to look for both .rb and .rbe files.

While not needed, holding on to the SketchupExtension object as a constant can be useful if you want to reference its metadata later. For a simple extension with just one command, you could reuse the extension's name and description for it.

The RBZ File

RBZ files are how extensions are packaged and distributed. An RBZ file is simply a ZIP archive containing the root .rb and support folder mentioned above, with the file extension changed to ".rbz".

To create an RBZ file, use the same tool you use for .zip files. On Windows you can select the items, right click and create a ZIP file from there. To be able to change the file extension, you may need to go into Settings and make sure the file extension is displayed.

Banned Content

A few features of Ruby are not allowed in SketchUp.

Global variables should not be used as they risk clashing with other extensions. Instead you can use an instance variable under your own namespace.

Installing a Gem does not work well inside of SketchUp. Instead package the Gem's files into your extension and wrap it under your namespace module (assuming its license allows it). Before considering using Gems, you can also check if the functionality already exists in the Ruby Standard Library that SketchUp ships with.

There are more things that are not allowed but they are outside the scope of an introductory article. You can read more in the SketchUp Extension Requirements or the rubocop-sketchup cops. Using rubocop-sketchup is a great way to detect and avoid code issues with a SketchUp Extension.

Publishing

Congrats! If you have some useful Ruby code that you've adapted to this format, you can now share it with the world! We recommend submitting it to Extension Warehouse where other SketchUp users can find and enjoy it.

Other Resources

Extension Requirements

Extension Warehouse