philosophy | for whom? | screenshots | documentation | contribute | achievements | FAQ

`. Then you can clone Spacemacs into that directory. If the following error occurs after starting Emacs: ``` The directory ~/.emacs.d/server is unsafe ``` Fix it by changing the owner of the directory `~/.emacs.d/server`: - from Properties select the Tab “Security”, - select the button “Advanced”, - select the Tab “Owner” - change the owner to your account name Source: [Stack Overflow][so-server-unsafe] For efficient searches we recommend installing `pt` ([the platinum searcher][]). `pt` version 1.7.7 or higher is required. **Notes:** Depending on the installed version of GnuTLS securely installing emacs packages may fail. In this case it is possible to install using `emacs --insecure`. However be aware that this means your packages will be transferred using http, use at your own risk. # Install ## Default installation 1. If you have an existing Emacs configuration, back it up first by running the following code in your terminal: ```sh cd ~ mv .emacs.d .emacs.d.bak mv .emacs .emacs.bak ``` Don't forget to backup and *remove* the `~/.emacs` file. Otherwise Spacemacs **WILL NOT** be able to load. Because that file prevents Emacs from loading the proper initialization file. 2. Clone the repository with [Git][]: ```sh git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d ``` Or ```sh git clone --depth 1 https://github.com/syl20bnr/spacemacs ~/.emacs.d ``` In case you have a limited internet connection or speed. `master` is the stable branch and it is _immutable_, **DO NOT** make any modification to it or you will break the update mechanism. If you want to fork Spacemacs safely, use the `develop` branch where you'll handle updates manually. **Note for Windows users** If you use windows, then you'll have to modify the git command by inserting the correct path to your `.emacs.d` folder. The dot before the folder means that it's hidden. You'll have to search for hidden files to find the folder. When you have found the folder, substitute the original path with the correct one. The proper code would look something like this: ```sh git clone https://github.com/syl20bnr/spacemacs /path/to/your/.emacs.d ``` 3. (Optional) Install the default fonts It's recommended to install [Source Code Pro][] by Adobe, as the default font. It ensures that, for example the symbols on the modeline (bottom bar) looks correct. It's also recommended to use a "Fallback font". These depend on the system: - GNU/Linux: *NanumGothic* (package named *fonts-nanum* on Debian, for example) - macOS: *Arial Unicode MS* - Windows: *MS Gothic* or *Lucida Sans Unicode* If the modeline doesn't look similar to the [picture at the top of this page](#introduction), then make sure you have the correct fallback font installed. If you're running in a terminal then you'll also need to change the terminals font settings. 4. Launch Emacs. Spacemacs will automatically install the packages it requires. There is a well-known issue with some GPG keys having expired end of 2019. This can be fixed by upgrading to Emacs 26.3 or above or by manually adding the new keys using something like: ```sh gpg --homedir ~/.emacs.d/elpa/gnupg --receive-keys 066DAFCB81E42C40 ``` If you have a restrictive firewall it may help to manually specify the keyserver: ```sh gpg --keyserver keyserver.ubuntu.com --homedir ~/.emacs.d/elpa/gnupg/ --receive-keys 066DAFCB81E42C40 ``` 5. Launch Emacs, and answer the questions in the Dotfile wizard installer. If you are new to Emacs and Spacemacs, then it's fine to just accept the default choices. It's easy to try the other choices later, without having to reinstall Spacemacs. They can be changed in the dotfile `~/.spacemacs`. After answering the questions, then Spacemacs starts downloading and installing the packages it requires. When the packages have been installed. Restart Emacs to complete the installation. **Notes:** If you are behind a firewall or similar and you get an error regarding package downloads then you may try to disable the HTTPS protocol by starting Emacs with ```sh emacs --insecure ``` but this should be a last resort because of the security implications. You can set the `dotspacemacs-elpa-https` variable to `nil` in your dotfile `~/.spacemacs` but this has the same security implications as the insecure flag. You may also want to clear out your `.emacs.d/elpa` directory before doing this, so that any corrupted packages you may have downloaded will be re-installed. `error: Package 'package-build-' is unavailable` may occur due to heavy network taffic. You can fix it by setting the `dotspacemacs-elpa-timeout` variable to `70` in your dotfile. `Warning (bytecomp)` and other compilation warnings are perfectly normal. If you're curious, you can find out why these occur [here][compilation-warnings]. If the mode-line turns red then be sure to consult the [FAQ][FAQ.org]. ## Alternative installations There are currently, two supported, alternative locations, for a Spacemacs configuration. ### Modify HOME environment variable This solution is ideal for quickly trying Spacemacs without compromising your existing configuration. Clone Spacemacs outside the Emacs dotdirectory `~/.emacs.d` and modify the HOME environment variable. ```sh mkdir ~/spacemacs git clone https://github.com/syl20bnr/spacemacs.git ~/spacemacs/.emacs.d HOME=~/spacemacs emacs ``` Note: If you're using the Fish shell, then you'll need to modify the last command to: `env HOME=$HOME/spacemacs emacs` ### Modify spacemacs-start-directory variable This solution is better suited to "embed" Spacemacs into your own configuration. If you've cloned Spacemacs into `~/.emacs.d/spacemacs/`, then drop the following lines in the `~/.emacs.d/init.el` file: ```elisp (setq spacemacs-start-directory "~/.emacs.d/spacemacs/") (load-file (concat spacemacs-start-directory "init.el")) ``` ## Spacemacs logo For Linux users, create `spacemacs.desktop` in `~/.local/share/applications/` using [this](https://github.com/emacs-mirror/emacs/blob/master/etc/emacs.desktop) as a reference. Change the `Name` parameter to `Name=Spacemacs` and the `Icon` parameter to `Icon=/PATH/TO/EMACSD/core/banners/img/spacemacs.png` where `PATH/TO/EMACSD` is the path to your `.emacs.d` directory, usually `~/.emacs.d` or `~/.config/emacs`. For macOS users, you need to [download the .icns version of the logo][icon-repository], then [change the logo on the Dock][icon-mac-instructions]. # Update Spacemacs shows a notification when a new version is available (only when you are on the default `master` branch). If you are on the `develop` branch then you'll have to update the Spacemacs repository manually. ## Automatic update (on master branch) When a new version is available then a little arrow appears in the mode-line. Its color depends on the number of versions that have been released since your last update. Green means that you have a recent version, orange and red means that you have an older version.  Click on the arrow to update Spacemacs to the latest version. ## Manual update (on master branch) Remove the `<` and `>` angle brackets when you're typing the lines below into your shell. And replace the text: "tag version which you are updating to" with a tagged version. This page lists the [latest tags][] ```sh git fetch git reset --hard ``` ## On develop branch 1. Close Emacs and update the git repository: ```sh git pull --rebase ``` 2. Restart Emacs to complete the upgrade. ## Revert to a specific version To revert to a specific version, just checkout the corresponding branch. For instance to revert to version `0.200`, type the following command: ```sh git checkout origin/release-0.200 ``` **After updating Spacemacs (either manually or automatically), then you also should check if any updates are available for your packages. On the Spacemacs Home Buffer `SPC b h`, click (press `RET`) on the `[Update Packages]` button.** # Quotes [Quote][quote01] by [ashnur](https://github.com/ashnur): «I feel that spacemacs is an aircraft carrier and I am playing table tennis on the deck as a freerider.» [Quote][quote02] by [deuill](https://github.com/deuill): «I LOVE SPACEMACS AND MAGIT That is all» # Contributions Spacemacs is a community-driven project, it needs _you_ to keep it up to date and to propose great and useful configurations for all the things! Before contributing be sure to consult the [contribution guidelines][CONTRIBUTING.org] and [conventions][CONVENTIONS.org]. # Communities - [Gitter Chat] - [Stack Exchange] - [Reddit] # Spacemacs Everywhere Once you've learned the Spacemacs key bindings, you can use them in other IDEs/tools, thanks to the following projects: - [Intellimacs](https://github.com/MarcoIeni/intellimacs) - Spacemacs' like key bindings for IntelliJ platform - [Spaceclipse](https://github.com/MarcoIeni/spaceclipse) - Spacemacs’ like key bindings for Eclipse - [SpaceVim](https://github.com/SpaceVim/SpaceVim) - A community-driven modular vim distribution - [VSpaceCode](https://github.com/VSpaceCode/VSpaceCode) - Spacemacs’ like key bindings for Visual Studio Code # License The license is GPLv3 for all parts specific to Spacemacs, this includes: - the initialization and core files - all the layer files - the documentation For the packages shipped in this repository, you can refer to the files header. [Spacemacs logo][] by [Nasser Alshammari][] released under a [Creative Commons Attribution-ShareAlike 4.0 International License.](https://creativecommons.org/licenses/by-sa/4.0/) # Supporting Spacemacs The best way to support Spacemacs is to contribute to it either by reporting bugs, helping the community on the [Gitter Chat][] or sending pull requests. You can show your love for the project by getting cool Spacemacs t-shirts, mugs and more in the [Spacemacs Shop][]. If you want to show your support financially, then you can contribute to [Bountysource][], or buy a drink for the maintainer by clicking on the [Paypal badge](#top). If you used spacemacs in a project, and you want to show that fact, you can use the spacemacs badge: [](https://spacemacs.org) - For Markdown: ```markdown [](https://spacemacs.org) ``` - For HTML: ```html ``` - For Org-mode: ```org [[https://spacemacs.org][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]] ``` Thank you! [Twitter]: https://i.imgur.com/tXSoThF.png [CONTRIBUTING.org]: CONTRIBUTING.org [CONVENTIONS.org]: https://spacemacs.org/doc/CONVENTIONS [DOCUMENTATION.org]: https://spacemacs.org/doc/DOCUMENTATION [QUICK_START.org]: https://spacemacs.org/doc/QUICK_START [FAQ.org]: https://spacemacs.org/doc/FAQ [VIMUSERS.org]: https://spacemacs.org/doc/VIMUSERS [dotfile]: https://spacemacs.org/doc/DOCUMENTATION#dotfile-configuration [osx layer]: https://spacemacs.org/layers/+os/osx/README.html [Gitter Chat]: https://gitter.im/syl20bnr/spacemacs [Gitter Chat IRC server]: https://irc.gitter.im/ [Homebrew]: https://brew.sh [emacs-plus]: https://github.com/d12frosted/homebrew-emacs-plus [powerline documentation]: https://spacemacs.org/doc/DOCUMENTATION.html#powerline-separators [emacs-for-windows]: https://ftp.gnu.org/gnu/emacs/windows/ [gzip-for-windows]: http://gnuwin32.sourceforge.net/packages/gzip.htm [the platinum searcher]: https://github.com/monochromegane/the_platinum_searcher [so-server-unsafe]: https://stackoverflow.com/questions/885793/emacs-error-when-calling-server-start [Spacemacs logo]: https://github.com/nashamri/spacemacs-logo [Nasser Alshammari]: https://github.com/nashamri [compilation-warnings]: https://github.com/quelpa/quelpa/issues/90#issuecomment-137982713 [cpaulik-unity-icon]: http://splendidabacus.com/posts/2015/03/spacemacs-unity-icon/ [icon-mac-instructions]: https://www.idownloadblog.com/2014/07/16/how-to-change-app-icon-mac/ [latest tags]: https://github.com/syl20bnr/spacemacs/tags [icon-repository]: https://github.com/nashamri/spacemacs-logo [Stack Exchange]: https://emacs.stackexchange.com/questions/tagged/spacemacs [Reddit]: https://www.reddit.com/r/spacemacs [quote01]: https://gitter.im/syl20bnr/spacemacs?at=568e627a0cdaaa62045a7df6 [quote02]: https://gitter.im/syl20bnr/spacemacs?at=5768456c6577f032450cfedb [build_source]: https://www.gnu.org/software/emacs/manual/html_node/efaq/Installing-Emacs.html [Bountysource]: https://salt.bountysource.com/teams/spacemacs [Source Code Pro]: https://github.com/adobe-fonts/source-code-pro [Spacemacs Shop]: https://shop.spreadshirt.com/spacemacs-shop [Git]: https://git-scm.com/downloads