Because the Emacs defaults are not so great sometimes.
Emacs Lisp Shell
Pull request Compare This branch is 35 commits ahead, 8 commits behind technomancy:v2.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Emacs Starter Kit

The Starter Kit provides a more pleasant set of defaults than you get normally with Emacs. It was originally intended for beginners, but it offers a nicely augmented working environment for anyone using Emacs.

The latest release is at with the source at

This version of the Starter Kit acts as a set of config files you drop into your home directory. Version 2 (the v2 branch) is a set of packages you can pull in using package.el instead now that it's been included in Emacs.


This won't teach you Emacs, but it'll make it easier to get comfortable. To access the tutorial, press control-h followed by t.

You may also find the commercial PeepCode Meet Emacs screencast helpful. The Emacs Wiki is also very handy.


You'll need Emacs 24, which comes with package.el. It's not hard to compile from source, but precompiled versions are readily available for Debian-based systems, Mac OS X, and Windows.

If you need to maintain compatibility with Emacs 23 or 22, you need to use version 1.

Add Marmalade as a package archive source in ~/.emacs.d/init.el:

(require 'package)
(add-to-list 'package-archives
             '("marmalade" . "") t)

Evaluate that code by hitting M-x eval-buffer in init.el, then you can install it:

M-x package-refresh-contents
M-x package-install RET starter-kit RET

Other modules are also available:

  • starter-kit-bindings (spun out due to concerns about keybinding conventions)
  • starter-kit-eshell
  • starter-kit-js
  • starter-kit-ruby
  • starter-kit-perl
  • starter-kit-lisp (enhances Emacs Lisp, Clojure, Scheme, and Common Lisp)

These modules are installed separately from the base Starter Kit package.

It's recommended to create a list of packages in init.el which will be installed if they are found to not be present:

(when (not package-archive-contents)

;; Add in your own as you wish:
(defvar my-packages '(starter-kit starter-kit-lisp starter-kit-bindings)
  "A list of packages to ensure are installed at launch.")

(dolist (p my-packages)
  (when (not (package-installed-p p))
    (package-install p)))

That way you can be ensured of a consistent experience across machines.

There are a few conventions for naming files which will get loaded automatically. ~/.emacs.d/$USER.el as well as any files in the ~/.emacs.d/$USER/ directory. Finally, the Starter Kit will look for a file named after the current hostname ending in ".el" which will allow host-specific configuration.

The Starter Kit used to be a git repository that you checked out and used as your own personal .emacs.d directory, but it's been restructured so that it can be treated like any other package, freeing you up to structure your .emacs.d directory as you wish. See "Upgrading" below.


Q: When I try to create a new file or buffer, the autocompletion is eager and tries to use the name of an existing file or buffer.
A: That's called ido-mode, and it's awesome! But sometimes it gets in the way. To temporarily disable it, press C-f while the prompt is open. You can also press C-j while it's still enabled to force the creation of the name.

Q: When I'm writing Javascript, all my functions show up as ƒ. Am I going insane?
A: That's actually a render-time hack. The file on disk shows as "function", but it's just rendered using the script F in order to tone down the verbosity inherent in the language a bit. The same happens with fn in Clojure and lambda to λ in other lisps.

Q: I can't delete parentheses in Lisp!
A: To be specific, you can't delete parenthesis if deleting the parentheses would result in invalid structure. That's called Paredit, and once you get used to it, you'll wonder how you ever did anything without it. But it can be disorienting at first. When paredit tries to stop you from deleting something, you're probably trying to delete something you shouldn't. Use C-k to kill whole expressions. Two things to remember: you can always use C-w to kill a region regardless of Paredit's rules, and you can always insert a single character like a close-paren by prefixing it with C-q. You may find the Paredit cheat sheet or this Paredit walkthrough helpful. You can also enable paredit for non-lisp modes using the esk-paredit-nonlisp function.

Q: How awesome is Emacs?
A: So awesome.


Users of the old version of the Starter Kit (version 1) should be able to upgrade easily. Move your old Starter Kit checkout at ~/.emacs.d out of the way and create a new directory containing init.el with the lines above. Copy your username.el and username directory from your old checkout into the new ~/.emacs.d. You should be able to check this new directory into your main dotfiles repository instead of keeping it separate.

The main difference in version 2 is that the new one doesn't pull in a bunch of other package.el dependencies; users may pick and choose which they want, including language-specific modules. Read more about the differences with version 1.


Copyright © 2008-2011 Phil Hagelberg and contributors

  1. Install GNU Emacs (at least version 22, 23 is preferred) Use your package manager if you have one. Otherwise Mac users may get some prebuilt binaries, and Windows users can get them from GNU.
  2. Move the directory containing this file to ~/.emacs.d (If you already have a directory at ~/.emacs.d move it out of the way and put this there instead.)
  3. Launch Emacs!

If you find yourself missing some autoloads after an update (which should manifest itself as "void function: foobar" errors) try M-x regen-autoloads. After some updates an M-x recompile-init will be necessary; this should be noted in the commit messages.

If you want to keep your regular ~/.emacs.d in place and just launch a single instance using the starter kit, try the following invocation:

$ emacs -q -l ~/src/emacs-starter-kit/init.el

Note that having a ~/.emacs file might override the starter kit loading, so if you've having trouble loading it, make sure that file is not present.


Work is in progress on version 2 of the Starter Kit, which is structured as a set of packages rather than a git repository you use wholesale as your dotfiles. This allows for greater modularity: support for each language may be installed separately, and once package.el becomes more widespread it should make installation much easier.

Version 2 is not quite ready for general consumption, though adventurous users are welcome to try it. Note that it requires Emacs version 24, which is still in development.

If you have ideas for improvements to the Starter Kit, please base them on the v2 branch.


The init.el file is where everything begins. It's the first file to get loaded. The starter-kit-* files provide what I consider to be better defaults, both for different programming languages and for built-in Emacs features like bindings or registers.

Files that are pending submission to ELPA are bundled with the starter kit under the directory elpa-to-submit/. The understanding is that these are bundled just because nobody's gotten around to turning them into packages, and the bundling of them is temporary. For these libraries, autoloads will be generated and kept in the loaddefs.el file. This allows them to be loaded on demand rather than at startup.

There are also a few files that are meant for code that doesn't belong in the Starter Kit. First, the user-specific-config file is the file named after your user with the extension ".el". In addition, if a directory named after your user exists, it will be added to the load-path, and any elisp files in it will be loaded. Finally, the Starter Kit will look for a file named after the current hostname ending in ".el" which will allow host-specific configuration. This is where you should put code that you don't think would be useful to everyone. That will allow you to merge with newer versions of the starter-kit without conflicts.


Libraries from Marmalade installed via package.el are preferred when available since dependencies are handled automatically, and the burden to update them is removed from the user.

There's no vendor/ directory in the starter kit because if an external library is useful enough to be bundled with the starter kit, it should be useful enough to submit to Marmalade so that everyone can use it, not just users of the starter kit.

Variants of Emacs

The Starter Kit is designed to work with GNU Emacs version 22 or greater. Using it with forks or other variants is not supported. It probably won't work with XEmacs, though some have reported getting it to work with Aquamacs. However, since Aquamacs is not portable, it's difficult to test in it, and breakage is common.


Please see the note re: "Future" above; active development is only happening on the "v2" branch.

If you know your way around Emacs, please try out the starter kit as a replacement for your regular dotfiles for a while. If there's anything you just can't live without, add it or let me know so I can add it. Take a look at what happens in init.el to get started.

Also: Helping submit new libraries to Marmalade is the easiest way to help out. This involves ensuring the library's dependencies are all already packaged and then adding the appropriate package headers and autoload comments. It's best to contact the package maintainer to ask them if they mind having their software distributed on Marmalade. It's also ideal to push your autoload/header changes back upstream.


Files are licensed under the same license as Emacs unless otherwise specified. See the file COPYING for details.