08 February 2012

How I use Sublime Text 2 (for Django development)

This post follows a talk on ST2 I made a few days ago to my fellow coworkers. This is by no means a beginner introduction to this powerful editor. I just want to point out some things I found helpful getting  used to this marvelous thing.
This post will very likely evolve during my use of ST2.

PS. Unless you are a Vim ninja, brace yourself, you'll use your keyboard a lot.

Preliminary steps
First of all one has to download a copy of Sublime Text 2. As it still in development you can grab a stable build here. If you like living on the edge try the most current build from ST2 dev channel.

Secondly, Sublime is nothing without its Package Control system. It's maintained by the community so you have to install it separately. It's not hard though, just open the built-in command interface with Ctrl+` (back-tick, under the Escape key) and paste this Python one-liner:

Package installation
To install a package press Ctrl+Shift+P and type "install package" (to be fair only a few letters suffice, ST2 does loads of fuzzy matching magic). A list of package names and short descriptions appears (same as here). Select a package you like to start installation. All progress info is shown on the bottom part of the window - the status bar.
Some generally useful Sublime packages are:
  • Sidebar Enhancements (a lot of operations on files and directories for the sidebar)
  • Git (all familiar git operations without switching to the console)
  • SublimeCodeIntel (code completion with auto-scanning of your project and standard libraries ported from Komodo IDE, more on this later)
  • SublimeLinter (mostly syntactical and stylistic error highlighting),
  • Theme Soda (a beautiful light and dark themes for ST2, yes you want this)
  • BufferScroll (works like Vim history - remembers where you last finished editing your source)
  • AsAbove (press Ctrl+Shift+' to copy letters from the line above)
If you focus on web development you'll probably also want these:
  • Djaneiro (syntax for Django templates, useful snippets)
  • Colorpicker (cross-platform color picker, that's all)
  • JSFormat (beautifies your JavaScript)
But wait, there's more. Sublime Text 2 also supports TextMate bundles. You can find a lot of them on Github. I use tmbundles for CoffeeScript and EJS templates. To install a bundle just unpack it and move whole directory to ST2 Packages folder (Preferences -> Browse Packages will lead you there, otherwise consult official docs).

Configuration tips
This is a very opinionated part. I will show you some settings that speed up my work or just make development more comfortable.
Open Preferences -> File Settings - User from the menu bar. All ST2 configuration is made with proper JSON objects (although JS comments are allowed). Sublime warns you when settings are malformed (trailing commas, forgotten quotation marks and so on).
So, here are my preferred settings:
  • "auto_complete": false  - I don't like autocomplete crunching at every character I type (manual completion with Ctrl+Space and CodeIntel still works)
  • "caret_style": "wide" - because default caret is just too thin and madly blinking
  • "color_scheme": "Packages/Color Scheme - Default/Sunburst.tmTheme" - my preferred highlighting theme, go to Preferences -> Color Scheme for more choices if you don't like this one
  • "ensure_newline_at_eof_on_save": true
    "translate_tabs_to_spaces": true
    "trim_trailing_white_space_on_save": true - these are for proper handling of whitespace (always add an new empty line at the end of file, always use spaces for indentation, automatically remove trailing whitespace)
  • "highlight_line": true - just highlights current line you're editing
  • "indent_guide_options": ["draw_active"] - indentation guides can be distracting so draw them only on the active buffer
  • "line_numbers": false - I don't like line numbers either, especially when current line and column number is shown on the status bar
  • "rulers": [80] - show vertical ruler on the 80. column, really important if you stick to PEP8 rules for Python
  • "tab_size": 4 - indent with 4 spaces, although this is sometimes ignored by ST2 when it guesses indentation width while opening a file
  • "word_wrap": false - word wrap is usually confusing and leads to errors, I turn it off

Useful shortcuts
Generally look for interesting features in the menu bar. Some external packages (like Git) put there custom submenus. Here's a short list of the shortcuts (Linux/Windows specific as far as I know) you'd use most frequently:
  • Ctrl+P - famous Goto Anything - fuzzy matches files added to the project, allows you to take a peek at a file, open it or even go straight to a specific class/method (add @some_name) or line number (add :number)
  • Ctrl+Shift+P - Command Pallete - here you can find any command that is currently available in your ST2 installation, fuzzy matching applies
  • Ctrl+J - show CodeIntel completions
  • Ctrl+] / Ctrl+[ - indent or dedent selection
  • Ctrl+Shift+[ / Ctrl+Shift+] - fold / unfold current block (or scope)
  • Ctrl+Shift+F - search (and replace) in files - results are displayed as a new buffer
  • Ctrl+R - go to a class or function (similar to Goto Anything behavior)
  • Ctrl+G - go to specific line
  • F11 / Shift+F11 - switch fullscreen / distraction free mode on or off
Most of the well known graphical text editors' shortcuts are also supported.

That would be all by now. Feel free to roam Sublime Text 2 menu bar and sidebar to find all the features you need for your everyday work. Don't forget about the huge selection of external packages. If you think I missed something really important or you are just stuck not knowing how to find some tool let me know. 


  1. i love it! You really know how to write about Sublime Text 2!

  2. Thank you for your post !

  3. I'm a Django developing TextMate refugee, and it looks like I'm headed to the Sublime Text camp now... thanks for the brilliant post. Gonna save heaps of fiddling.

  4. Glad to see this post is still relevant, thanks.

  5. This comment has been removed by the author.

  6. Extremely useful post! This saved me a lot of time!

  7. Spread the word, make other people's lives easier :)

  8. Could you use build capabilities for django and virtualenv? I tried without success

  9. I'm afraid it's really hard if not impossible. First of all ST2 has its own Python (2.6.6) interpreter embedded. This means it's isolated from the system paths.

    I don't know what is your use case. If you want to get autocomplete for Django and others use Djaneiro and SublimeCodeIntel from Package Control.
    Make sure you add your virtualenv libs to CodeIntel configuration. Look here: https://github.com/Kronuz/SublimeCodeIntel#configuring .

  10. Thanks for posting, very helpful for a quick start with ST2

  11. I love it! And thanks for writing this! It got me up and running really fast!

  12. Great post! Thank you for this!

    1. Always happy to help. Though it's been a year -- I should probably check if all my instructions still apply.

    2. I've used your instructions twice now for two different machines. Works like a charm. Thanks again!