1# Developing Extensions
2
3## Extension Features
4
5Extensions are able to provide the following features to Zed:
6
7- [Languages](./languages.md)
8- [Debuggers](./debugger-extensions.md)
9- [Themes](./themes.md)
10- [Icon Themes](./icon-themes.md)
11- [Slash Commands](./slash-commands.md)
12- [MCP Servers](./mcp-extensions.md)
13
14## Developing an Extension Locally
15
16Before starting to develop an extension for Zed, be sure to [install Rust via rustup](https://www.rust-lang.org/tools/install).
17
18> Rust must be installed via rustup. If you have Rust installed via homebrew or otherwise, installing dev extensions will not work.
19
20When developing an extension, you can use it in Zed without needing to publish it by installing it as a _dev extension_.
21
22From the extensions page, click the `Install Dev Extension` button (or the {#action zed::InstallDevExtension} action) and select the directory containing your extension.
23
24If you need to troubleshoot, you can check the Zed.log ({#action zed::OpenLog}) for additional output. For debug output, close and relaunch zed with the `zed --foreground` from the command line which show more verbose INFO level logging.
25
26If you already have the published version of the extension installed, the published version will be uninstalled prior to the installation of the dev extension. After successful installation, the `Extensions` page will indicate that the upstream extension is "Overridden by dev extension".
27
28## Directory Structure of a Zed Extension
29
30A Zed extension is a Git repository that contains an `extension.toml`. This file must contain some
31basic information about the extension:
32
33```toml
34id = "my-extension"
35name = "My extension"
36version = "0.0.1"
37schema_version = 1
38authors = ["Your Name <you@example.com>"]
39description = "My cool extension"
40repository = "https://github.com/your-name/my-zed-extension"
41```
42
43In addition to this, there are several other optional files and directories that can be used to add functionality to a Zed extension. An example directory structure of an extension that provides all capabilities is as follows:
44
45```
46my-extension/
47 extension.toml
48 Cargo.toml
49 src/
50 lib.rs
51 languages/
52 my-language/
53 config.toml
54 highlights.scm
55 themes/
56 my-theme.json
57```
58
59## WebAssembly
60
61Procedural parts of extensions are written in Rust and compiled to WebAssembly. To develop an extension that includes custom code, include a `Cargo.toml` like this:
62
63```toml
64[package]
65name = "my-extension"
66version = "0.0.1"
67edition = "2021"
68
69[lib]
70crate-type = ["cdylib"]
71
72[dependencies]
73zed_extension_api = "0.1.0"
74```
75
76Use the latest version of the [`zed_extension_api`](https://crates.io/crates/zed_extension_api) available on crates.io. Make sure it's still [compatible with Zed versions](https://github.com/zed-industries/zed/blob/main/crates/extension_api#compatible-zed-versions) you want to support.
77
78In the `src/lib.rs` file in your Rust crate you will need to define a struct for your extension and implement the `Extension` trait, as well as use the `register_extension!` macro to register your extension:
79
80```rs
81use zed_extension_api as zed;
82
83struct MyExtension {
84 // ... state
85}
86
87impl zed::Extension for MyExtension {
88 // ...
89}
90
91zed::register_extension!(MyExtension);
92```
93
94> `stdout`/`stderr` is forwarded directly to the Zed process. In order to see `println!`/`dbg!` output from your extension, you can start Zed in your terminal with a `--foreground` flag.
95
96## Forking and cloning the repo
97
981. Fork the repo
99
100> Note: It is very helpful if you fork the `zed-industries/extensions` repo to a personal GitHub account instead of a GitHub organization, as this allows Zed staff to push any needed changes to your PR to expedite the publishing process.
101
1022. Clone the repo to your local machine
103
104```sh
105# Substitute the url of your fork here:
106# git clone https://github.com/zed-industries/extensions
107cd extensions
108git submodule init
109git submodule update
110```
111
112## Update Your Extension
113
114When developing/updating your extension, you will likely need to update its content from its submodule in the extensions repository.
115To quickly fetch the latest code for only specific extension (and avoid updating all others), use the specific path:
116
117```sh
118# From the root of the repository:
119git submodule update --remote extensions/your-extension-name
120```
121
122> Note: If you need to update all submodules (e.g., if multiple extensions have changed, or for a full clean build), you can run `git submodule update` without a path, but this will take longer.
123
124## Extension License Requirements
125
126As of October 1st, 2025, extension repositories must include a license.
127The following licenses are accepted:
128
129- [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)
130- [BSD 3-Clause](https://opensource.org/license/bsd-3-clause)
131- [GNU GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)
132- [MIT](https://opensource.org/license/mit)
133
134This allows us to distribute the resulting binary produced from your extension code to our users.
135Without a valid license, the pull request to add or update your extension in the following steps will fail CI.
136
137Your license file should be at the root of your extension repository. Any filename that has `LICENCE` or `LICENSE` as a prefix (case insensitive) will be inspected to ensure it matches one of the accepted licenses. See the [license validation source code](https://github.com/zed-industries/extensions/blob/main/src/lib/license.js).
138
139> This license requirement applies only to your extension code itself (the code that gets compiled into the extension binary).
140> It does not apply to any tools your extension may download or interact with, such as language servers or other external dependencies.
141> If your repository contains both extension code and other projects (like a language server), you are not required to relicense those other projects—only the extension code needs to be one of the aforementioned accepted licenses.
142
143## Publishing your extension
144
145To publish an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
146
147In your PR, do the following:
148
1491. Add your extension as a Git submodule within the `extensions/` directory
150
151```sh
152git submodule add https://github.com/your-username/foobar-zed.git extensions/foobar
153git add extensions/foobar
154```
155
156> All extension submodules must use HTTPS URLs and not SSH URLS (`git@github.com`).
157
1582. Add a new entry to the top-level `extensions.toml` file containing your extension:
159
160```toml
161[my-extension]
162submodule = "extensions/my-extension"
163version = "0.0.1"
164```
165
166> If your extension is in a subdirectory within the submodule you can use the `path` field to point to where the extension resides.
167
1683. Run `pnpm sort-extensions` to ensure `extensions.toml` and `.gitmodules` are sorted
169
170Once your PR is merged, the extension will be packaged and published to the Zed extension registry.
171
172> Extension IDs and names should not contain `zed` or `Zed`, since they are all Zed extensions.
173
174## Updating an extension
175
176To update an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
177
178In your PR do the following:
179
1801. Update the extension's submodule to the commit of the new version.
1812. Update the `version` field for the extension in `extensions.toml`
182 - Make sure the `version` matches the one set in `extension.toml` at the particular commit.
183
184If you'd like to automate this process, there is a [community GitHub Action](https://github.com/huacnlee/zed-extension-action) you can use.
185
186> **Note:** If your extension repository has a different license, you'll need to update it to be one of the [accepted extension licenses](#extension-license-requirements) before publishing your update.