Back to blog

/ Updated

How to Install Your Own Chrome Extension

Learn how to install your own Chrome extension locally using Developer Mode, test changes, fix common errors, and understand when you need the Chrome Web Store.

  • chrome
  • chrome extensions
  • browser extensions
  • web development

Suggested slug: install-own-extension-chrome.mdx

If you built a Chrome extension yourself, you do not need to publish it to the Chrome Web Store just to test it. The easiest method is to install it as an unpacked extension from chrome://extensions with Developer Mode enabled.

This is the normal workflow for personal extensions, local testing, and extension development. For other people to install your extension safely and receive updates, you should usually publish it through the Chrome Web Store.

Table of Contents

Before you start

You need a folder that contains your extension files. At minimum, a Chrome extension needs a manifest.json file in the root of the extension folder. According to the official Chrome Extensions documentation, the manifest file describes the extension’s structure, version, permissions, and behavior.

For modern Chrome extensions, use Manifest V3:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "description": "A simple Chrome extension."
}

A common beginner mistake is selecting the wrong folder. When you click Load unpacked, you must select the folder that directly contains manifest.json, not the parent folder above it.

Method 1: Install your own extension locally

Use this method when you already have an extension folder on your computer.

  1. Open Google Chrome.
  2. Type this into the address bar and press Enter:
chrome://extensions
  1. Turn on Developer Mode in the top-right corner.
  2. Click Load unpacked.
  3. Select your extension folder.
  4. Click Select Folder or Open, depending on your operating system.

Chrome should now install the extension locally. If the extension has a toolbar action, it will appear in the Extensions menu, which is the puzzle icon near the address bar.

This local installation is mainly for development and personal use. Google specifically describes unpacked extensions as a development workflow, and recommends using trusted code only.

Official reference: Chrome Extensions Hello World tutorial

Method 2: Create a tiny test extension from scratch

If you want to test the process with a clean example, create a new folder called my-extension and add these two files inside it.

1. Create manifest.json

{
  "manifest_version": 3,
  "name": "My Local Extension",
  "version": "1.0.0",
  "description": "A simple local Chrome extension.",
  "action": {
    "default_popup": "popup.html"
  }
}

2. Create popup.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Extension</title>
  </head>
  <body>
    <h2>Hello from my extension</h2>
    <p>This popup is running from a local Chrome extension.</p>
  </body>
</html>

Now open chrome://extensions, enable Developer Mode, click Load unpacked, and select the my-extension folder.

After loading it, click the puzzle icon in Chrome and open your extension. You should see the popup.

How to update the extension after editing files

When you edit your extension files, Chrome does not always update everything instantly.

Go back to:

chrome://extensions

Then click the reload icon on your extension card.

You usually need to reload the extension after changing:

  • manifest.json
  • service worker files
  • content scripts
  • permissions
  • extension icons

For simple popup HTML or CSS changes, reopening the popup may be enough. If something looks stuck, reload the extension anyway. It is the Chrome extension developer equivalent of turning it off and on again, except this one actually makes sense.

How to pin your extension to the toolbar

By default, your local extension may be hidden inside Chrome’s Extensions menu.

To pin it:

  1. Click the puzzle icon near the address bar.
  2. Find your extension.
  3. Click the pin icon next to it.

Now the extension icon should stay visible on the Chrome toolbar.

Can you install a packed CRX file manually?

For normal users on Windows and macOS, Chrome does not treat random extension files like regular apps that you can freely install from anywhere. Officially supported distribution is mainly through the Chrome Web Store. Self-hosted extension distribution is mostly for managed enterprise environments.

For your own development, use Load unpacked instead of trying to manually install a .crx file.

Chrome can also pack an unpacked extension from chrome://extensions using the Pack extension button, but packing is not the same as making it easy for everyone to install. If you want other users to install your extension normally, publish it to the Chrome Web Store.

Official reference: Distribute your extension

When you should publish to the Chrome Web Store

Local installation is great when:

  • you are building the extension yourself
  • you are testing a new feature
  • you only need the extension on your own computer
  • you are debugging before release

Publishing to the Chrome Web Store is the better option when:

  • other people need to install it easily
  • you want automatic updates
  • you want a public listing
  • you want a safer installation flow for users
  • you need a real release process

The official publishing flow requires a Chrome Web Store developer account, a prepared extension package, listing details, privacy information, and review submission.

Official reference: Publish in the Chrome Web Store

Troubleshooting

Chrome says the manifest is missing or unreadable

This usually means you selected the wrong folder.

Make sure the folder you selected contains manifest.json directly inside it:

my-extension/
  manifest.json
  popup.html

This is correct.

downloads/
  my-extension/
    manifest.json
    popup.html

If you select downloads instead of my-extension, Chrome will not find the manifest.

Chrome says the manifest is invalid

Open manifest.json and check for JSON mistakes:

  • missing commas
  • extra commas at the end of an object
  • wrong quote marks
  • invalid manifest_version
  • comments inside JSON

JSON does not support comments, so this is invalid:

{
  "manifest_version": 3,
  "name": "My Extension" // This comment breaks JSON
}

Use this instead:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0"
}

The extension loads, but the icon is missing

If you did not define icons in the manifest, Chrome may show a generic icon. That does not mean the extension is broken.

You can add icons later with an icons field:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "icons": {
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  }
}

Make sure the file paths match your actual folder structure.

Changes are not showing

Try these steps:

  1. Go to chrome://extensions.
  2. Click the reload icon on your extension.
  3. Refresh the webpage where you are testing the extension.
  4. Close and reopen the popup if your extension uses one.
  5. Check the extension error panel if Chrome shows an Errors button.

Content scripts often need both an extension reload and a page refresh because the script runs inside the webpage.

The extension disappears after moving the folder

Unpacked extensions are loaded from the folder path you selected. If you move, rename, or delete that folder, Chrome can no longer load it correctly.

Keep your extension folder in a stable location, such as:

Documents/chrome-extensions/my-extension

Avoid loading it directly from a temporary downloads folder if you plan to keep using it.

Developer Mode warning appears

Chrome may warn you that Developer Mode extensions are enabled. This is expected when you install unpacked extensions.

Only keep Developer Mode extensions installed if you trust the code. Extensions can request powerful permissions, read pages, modify tabs, or interact with browser data depending on what the manifest allows.

FAQ

Do I need a Chrome Web Store account to install my own extension?

No. For local testing, you can install your own extension with Load unpacked in Developer Mode. You need a Chrome Web Store developer account only when you want to publish the extension.

Can I install my extension from a ZIP file?

Not directly through the normal local development flow. Extract the ZIP first, then use Load unpacked and select the extracted folder that contains manifest.json.

Can I share my unpacked extension folder with a friend?

Technically, yes, but it is not the best distribution method. Your friend would need to enable Developer Mode and load the folder manually. For a real user-friendly release, use the Chrome Web Store.

Is Developer Mode safe?

Developer Mode itself is not the problem. The risk is loading code you do not trust. Only install unpacked extensions from your own code or from a source you fully trust.

Why does Chrome require Manifest V3?

Manifest V3 is the current extension platform for Chrome. New extensions should use "manifest_version": 3 unless you are maintaining an old project with specific migration needs.

Conclusion

To install your own Chrome extension, open chrome://extensions, enable Developer Mode, click Load unpacked, and select the folder that contains manifest.json.

That is the best method for testing and personal use. If you want normal users to install your extension, publish it through the Chrome Web Store instead.