Creating Sublime Text Packages for JSON Formatting

If your only goal is to format JSON in Sublime Text, the quickest path in March 2026 is still to install a formatter package through Package Control and use an existing command such as Pretty JSON. Build your own package when you want a fixed team workflow, custom indentation rules, selection-aware formatting, or an offline-friendly command with no third-party formatter dependency.

This guide focuses on the custom-package route, but it starts with the shortest answer for search visitors: how to format JSON in Sublime Text today, and then how to package that behavior cleanly for reuse.

Fastest Option if You Just Want a JSON Formatter

• Open the Command Palette with Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS.
• Run Package Control: Install Package.
• Install Pretty JSON.
• Use the package command to format the active JSON buffer, validate JSON, or minify it when needed.

That is usually enough for the search intent behind queries like "format json in sublime text" or "sublime text json formatter". A custom package is the better choice when you want your own command name, settings file, and predictable behavior across machines.

When a Custom Package Is Worth It

• You want one command that formats either the current selection or the whole file.
• You need package-specific settings such as indent, sort_keys, or ASCII escaping.
• You want to avoid shipping a default keybinding that may collide with another package.
• You need a formatter that still works in locked-down or offline environments.

Create the Package Folder

Start in Preferences > Browse Packages.... Create a folder named JsonFormatter and put your package files at that folder's root.

JsonFormatter/
├── .python-version
├── json_formatter.py
├── Default.sublime-commands
└── JsonFormatter.sublime-settings

For a new package, add a .python-version file as well. The current Sublime Text API docs still describe package-level opt-in to Python 3.8, and Sublime HQ's May 21, 2025 build notes explicitly said Python 3.3 is being phased out. Starting with 3.8 now saves migration work.

3.8

Add the Formatter Command

Put the core logic in json_formatter.py. This example formats either the current selection or, if nothing is selected, the whole file. It also preserves the view's line endings and stops on invalid JSON instead of silently rewriting broken data.

import json

import sublime
import sublime_plugin


def normalized_regions(view, whole_file_if_no_selection):
    selections = [region for region in view.sel() if not region.empty()]
    if selections:
        return selections
    if whole_file_if_no_selection:
        return [sublime.Region(0, view.size())]
    return []


def line_ending_for_view(view):
    line_endings = view.line_endings()
    if line_endings == "Windows":
        return "\r\n"
    if line_endings == "CR":
        return "\r"
    return "\n"


class JsonFormatterCommand(sublime_plugin.TextCommand):
    def run(self, edit):
        settings = sublime.load_settings("JsonFormatter.sublime-settings")
        indent = settings.get("indent", 2)
        sort_keys = settings.get("sort_keys", False)
        ensure_ascii = settings.get("ensure_ascii", False)
        whole_file_if_no_selection = settings.get("whole_file_if_no_selection", True)

        regions = normalized_regions(self.view, whole_file_if_no_selection)
        if not regions:
            sublime.status_message("Select JSON first")
            return

        replacements = []
        line_ending = line_ending_for_view(self.view)

        for region in regions:
            source = self.view.substr(region)
            try:
                parsed = json.loads(source)
            except json.JSONDecodeError as exc:
                sublime.error_message(
                    "Invalid JSON at line {}, column {}: {}".format(
                        exc.lineno,
                        exc.colno,
                        exc.msg,
                    )
                )
                return

            formatted = json.dumps(
                parsed,
                indent=indent,
                sort_keys=sort_keys,
                ensure_ascii=ensure_ascii,
            ).replace("\n", line_ending)

            replacements.append((region, formatted))

        for region, formatted in reversed(replacements):
            self.view.replace(edit, region, formatted)

        sublime.status_message("JSON formatted")

• JsonFormatterCommand becomes the command name json_formatter inside Sublime Text.
• Selection support is useful when the JSON you need to clean up is embedded inside a larger file or log.
• ensure_ascii is left configurable because many teams prefer readable UTF-8 output instead of escaped Unicode sequences.

If your team standardizes on jq or prettier, keep the same package skeleton and swap the json.dumps call for a subprocess.run(...) wrapper. For editor formatting, a TextCommand is usually a better fit than a build system because it can update the current buffer directly.

Add a Command Palette Entry

Create Default.sublime-commands so the formatter is discoverable without remembering a keybinding.

[
  {
    "caption": "JSON Formatter: Format JSON",
    "command": "json_formatter"
  }
]

After saving the file, open the Command Palette and run JSON Formatter: Format JSON. For a package you intend to share, this is often enough on its own.

Add Package Settings

Keep formatting choices in a dedicated settings file instead of hard-coding them into the plugin. That makes the package easier to reuse and easier for users to override in their User package.

{
  "indent": 2,
  "sort_keys": false,
  "ensure_ascii": false,
  "whole_file_if_no_selection": true
}

Put user-specific overrides in Packages/User/JsonFormatter.sublime-settings. For example, you might keep the package default at two spaces while a personal override sets indent to 4 or "\t".

Add a Keybinding Only if You Want One

Current formatter packages increasingly avoid shipping default shortcuts because collisions are common. For a local workflow, add the keybinding in Packages/User/Default.sublime-keymap instead of baking it into the package.

[
  {
    "keys": ["primary+alt+j"],
    "command": "json_formatter",
    "context": [
      { "key": "selector", "operator": "equal", "operand": "source.json" }
    ]
  }
]

The primary modifier maps to Ctrl on Windows/Linux and Cmd on macOS, so one keybinding works across platforms. The selector guard keeps the shortcut limited to JSON buffers.

Package It for Reuse

For personal use, the loose package inside the folder opened by Browse Packages... is enough. Sublime Text will load the command from there.

If you want to hand the package to someone else, use Package Control: Create Package File instead of manually zipping the folder. That produces a .sublime-package archive in the format Sublime expects.

Troubleshooting

• If the command does not appear, confirm that json_formatter.py is at the root of the package folder and that the package folder name matches the paths used by your settings file.
• If formatting fails, check whether the buffer contains comments or trailing commas. Standard JSON does not allow either of those.
• If the keybinding never fires, remove it and test the Command Palette entry first. Shortcut conflicts are more common than plugin loading problems.
• If you only want a maintained formatter and not a custom workflow, go back to Package Control and install an existing package instead of maintaining code yourself.

Conclusion

The simplest way to format JSON in Sublime Text is to install a formatter package. The simplest way to own the behavior is a tiny package built around one TextCommand, one commands file, and one settings file.

That gives you a reusable Sublime Text JSON formatter without turning a small editor convenience into a large plugin project.