Sublime Text Packages: The Official Syntax Definition Repository for Built-in Languages

What This Repository Contains and Who Should Use It

sublimehq/Packages holds the .sublime-syntax and related support files that Sublime Text and Sublime Merge bundle with each release. These are the definitions that run automatically when you open a file in either application without installing any third-party packages.

The repository is maintained by the Sublime Text development team. It is useful for three groups: engineers at Sublime HQ who maintain the definitions, contributors who want to fix a highlighting error or add missing patterns to an existing language, and developers who build tools that need to understand how Sublime's syntax format works. End users who just want better highlighting for a language already in the list should look for updates through the editor itself; end users who want support for a language not in the list should install a user-contributed package via Package Control.

Repository Structure: 40-Plus Language Directories

The repository contains one directory per language or file format. The top-level listing includes: ASP, ActionScript, AppleScript, Batch File, Binary, C#, C++, CSS, Clojure, D, Diff, Erlang, Git Formats, Go, Graphviz, Groovy, HTML, Haskell, JSON, Java, JavaScript, LaTeX, Lisp, Lua, Makefile, Markdown, Matlab, OCaml, Objective-C, PHP, Pascal, Perl, Python, R, Rails, Regular Expressions, RestructuredText, Ruby, Rust, SQL, Scala, ShellScript, TCL, TOML, Text, Textile, XML, and YAML.

Each directory typically contains a `.sublime-syntax` file as the core definition, syntax test files used to verify that highlighting is correct, and sometimes additional support files such as snippet files or completions.

The repository does not include the `Default` package or `Theme - Default`. Those handle application behavior and UI rather than syntax highlighting and are maintained separately.

Setting Up a Local Override for Testing Changes

Sublime Text's package system allows a user-installed package to override a default package by placing files with the same names into the user `Packages` directory. To test a change to a built-in syntax, clone the repository and symlink the specific language folder into Sublime Text's Packages directory.

On macOS:

git clone https://github.com/sublimehq/Packages.git
ln -s `pwd`/Packages/Python ~/Library/Application\ Support/Sublime\ Text/Packages/

On Linux:

git clone https://github.com/sublimehq/Packages.git
ln -s `pwd`/Packages/Python ~/.config/sublime-text/Packages/

On Windows, symlinks require administrative rights, so directory junctions are the alternative:

git clone https://github.com/sublimehq/Packages.git
cmd /c mklink /J "$env:APPDATA/Sublime Text/Packages/Python" (convert-path ./Packages/Python)

After the symlink is in place, changes to the cloned file are reflected immediately in the editor without a full restart.

The Override System's File-Shadowing Behavior

The Sublime Text package override system has a specific behavior that catches contributors off guard. When you symlink a language folder, you override only the files present in your symlinked folder. Files that exist in the built-in `.sublime-package` zip but not in your symlinked folder are still loaded from the shipped package.

This means that if you delete or rename a file in your local clone, the original version from the shipped package is still picked up. To fully replace the shipped package, create an empty `.sublime-package` zip file in the user's `Installed Packages` directory with the same name. This causes Sublime Text to use your symlinked folder as the complete package, ignoring the shipped version entirely.

The README gives two shell commands for creating a minimal valid empty zip file:

printf "PK\x05\x06\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00" > empty.zip

A named empty zip in `Installed Packages` can then be pointed to via a symlink from each language directory, so it does not need to be duplicated.

Build Requirements and Format Compatibility

The packages are developed against the latest dev channel build of Sublime Text. The README states that the `.sublime-syntax` format used is not compatible with builds older than Build 4095. Bugs may exist on older builds.

The `.sublime-syntax` format is a YAML-based syntax definition system that Sublime Text uses to parse and tokenize source code for highlighting. The official documentation for the format and scope naming conventions is at the Sublime Text documentation site, which the README links as the primary reference.

The repository has no GitHub releases. Tagged versions in the repository correspond to the releases of the Packages bundle shipped with specific Sublime Text builds. The tag list on the repository is the authoritative reference for which version of the syntax definitions shipped with which build.

Contributing: PR Format, Syntax Tests, and Performance

The contribution guidelines specify that pull requests must begin with the name of the language in square brackets, for example `[XML]`. Changes should be as small as possible to keep review time short. Any change to a `.sublime-syntax` file must include a new or updated syntax test.

Significant changes require both multiple syntax tests and performance measurements comparing the old and new versions. The PR description should show the timing results side by side. This requirement exists because syntax highlighting runs on every keypress, and a regression in a commonly used language definition has a direct impact on editor responsiveness.

Pull requests are squashed on merge. New language packages are not accepted at this stage. The README notes that adding new packages creates a conflict risk for users who have a third-party package installed via Package Control under the same name, and that a planned change to the package management system will eventually address this.

Complex plugins such as autocomplete systems and linters are expected to live as standalone Package Control packages rather than in this repository.

How This Differs from Package Control Packages

Package Control is a third-party package manager for Sublime Text that indexes thousands of user-contributed packages. A Package Control syntax package for a language works through the same override mechanism as this repository: it installs a package into the user's Packages directory that takes precedence over the shipped default.

The difference is governance and scope. sublimehq/Packages contains only the definitions that ship with the editor, maintained by the Sublime HQ team with a strict review process and performance requirements. A Package Control package is published and maintained by its author independently.

For a language already covered in this repository, a Package Control alternative may offer different highlighting choices, more patterns, or support for a newer language version. For languages not in this repository at all, Package Control is the only path to get support without modifying the editor's source.

Maintenance and License

The last push to the repository was on 2026-09-11, reflecting active maintenance by the Sublime HQ team. The repository is not archived and tracks the dev channel build continuously.

The license field is listed as NOASSERTION in the repository metadata, which is not a standard SPDX license identifier. The repository contains a LICENSE file at the root. Any use outside of contributing to Sublime Text should verify the contents of that file, as NOASSERTION in the metadata does not indicate an open license.

Editorial conclusion

This repository is for engineers who maintain or contribute to Sublime Text's built-in syntax definitions. If you use Sublime Text and want to fix a highlighting bug in a language like Python, Go, or Rust, this is the correct place to submit a pull request. End users who want to add support for a language not already included should publish a separate package through Package Control rather than submitting here. New language packages are not accepted in this repository at this stage. The license field is listed as NOASSERTION in the repository metadata, which is not a standard SPDX identifier; verify the LICENSE file before redistributing any files from this repository.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. sublimehq/Packages on GitHub