<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> config</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> user.overlay_dir="$(</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">realpath</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> qmk_userspace)"</span></span></code></pre></div><h2id="external-userspace-setup-locally-stored-only"tabindex="-1">External Userspace Setup (locally stored only) <aclass="header-anchor"href="#external-userspace-setup-locally-stored-only"aria-label="Permalink to "External Userspace Setup (locally stored only)""></a></h2><p>If you don't want to use GitHub and prefer to keep everything local, you can clone a copy of the default External Userspace locally instead:</p><divclass="language-sh vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">sh</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> $HOME</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> config</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> user.overlay_dir="$(</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">realpath</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> qmk_userspace)"</span></span></code></pre></div><h2id="adding-a-keymap"tabindex="-1">Adding a Keymap <aclass="header-anchor"href="#adding-a-keymap"aria-label="Permalink to "Adding a Keymap""></a></h2><p><em>These instructions assume you have already set up QMK locally, and have a copy of the QMK Firmware repository on your machine.</em></p><p>Keymaps within External Userspace are defined in the same way as they are in the main QMK repository. You can either use the <code>qmk new-keymap</code> command to create a new keymap, or manually create a new directory in the <code>keyboards</code> directory.</p><p>Alternatively, you can use the <code>layouts</code> directory to store your keymaps, using the same layout system as the main QMK repository -- if you choose to do so you'll want to use the path <code>layouts/<layout name>/<keymap name>/keymap.*</code> to store your keymap files, where <code>layout name</code> matches an existing layout in QMK, such as <code>tkl_ansi</code>.</p><p>After creating your new keymap, building the keymap matches normal QMK usage:</p><divclass="language-sh vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">sh</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> compile</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -kb</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">keyboar</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -km</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">keyma</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">p</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><divclass="warning custom-block"><pclass="custom-block-title">WARNING</p><p>The <code>qmk config user.overlay_dir=...</code> command must have been run when cloning the External Userspace repository for this to work correctly.</p></div><h2id="adding-the-keymap-to-external-userspace-build-targets"tabindex="-1">Adding the keymap to External Userspace build targets <aclass="header-anchor"href="#adding-the-keymap-to-external-userspace-build-targets"aria-label="Permalink to "Adding the keymap to External Userspace build targets""></a></h2><p>Once you have created your keymap, if you want to use GitHub Actions to build your firmware, you will need to add it to the External Userspace build targets. This is done using the <code>qmk userspace-add</code> command:</p><divclass="language-sh vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">sh</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># for a keyboard/keymap combo:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># or, for a json-based keymap (if kept "loose"):</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> userspace-add</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">relative/path/to/my/keymap.jso</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><p>This updates the <code>qmk.json</code> file in the root of your External Userspace directory. If you're using a git repository to store your keymaps, now is a great time to commit and push to your own fork.</p><h2id="compiling-external-userspace-build-targets"tabindex="-1">Compiling External Userspace build targets <aclass="header-anchor"href="#compiling-external-userspace-build-targets"aria-label="Permalink to "Compiling External Userspace build targets""></a></h2><p>Once you have added your keymaps to the External Userspace build targets, you can compile all of them at once using the <code>qmk userspace-compile</code> command:</p><divclass="language-sh vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">sh</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> userspace-compile</span></span></code></pre></div><p>All firmware builds you've added to the External Userspace build targets will be built, and the resulting firmware files will be placed in the root of your External Userspace directory.</p><h2id="using-github-actions"tabindex="-1">Using GitHub Actions <aclass="header-anchor"href="#using-github-actions"aria-label="Permalink to "Using GitHub Actions""></a></h2><p>GitHub Actions can be used to automatically build your keymaps whenever you push changes to your External Userspace repository. If you have set up your list of build targets, this is as simple as enabling workflows in the GitHub repository settings:</p><p><imgsrc="https://i.imgur.com/EVkxOt1.png"alt="Repo Settings"></p><p>Any push will result in compilation of all configured builds, and once completed a new release containing the newly-minted firmware files will be created on GitHub, which you can subsequently download and flash to your keyboard:</p><p><imgsrc="https://i.imgur.com/zmwOL5P.png"alt="Releases"></p></div></div></main><footerclass="VPDocFooter"data-v-39a288b8data-v-09de1c0f><!--[--><!--]--><!----><navclass="prev-next"data-v-09de1c0f><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link prev"href="/support"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Previous page</span><spanclass="title"data-v-09de1c0f>Getting Help/Support</span><!--]--></a></div><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link next"href="/newbs_learn_more_resources"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Next page</span><spanclass="title"data-v-09de1c0f>Other Resources</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
