Skip to content
Get packs

Guide · Open source

How to use tmuxinator: install, configure and start tmux sessions

Updated · written with AI from the project's own documentation and checked against our catalogue data

Tmuxinator is an open-source tool that lets you describe a tmux terminal setup, including windows, panes, layouts and the commands to run in them, in a YAML file and start that setup with one command. It is aimed at developers who open the same multi-pane workspace for a project again and again. This guide shows you how to install it, create a project config, define windows and panes, and open the session.

tmuxinatortmuxinator/tmuxinator · ★ 13.7k · MIT

Quick start

  1. 1Install tmuxinator. Install the gem with RubyGems, which the README prefers over Homebrew. Make sure tmux is version 1.8 or later and not 2.5.
  2. 2Set your editor. Run echo $EDITOR to check the default editor. Set EDITOR in your shell file if you want a different one.
  3. 3Create a project. Run tmuxinator new followed by your project name. Add --local to store the config as .tmuxinator.yml in the current directory.
  4. 4Define windows. Add a windows list to the YAML. Give each window a name and a command, or use null to keep the default shell name.
  5. 5Add panes and a layout. Nest panes under a window and set layout, such as main-vertical. Check indentation if the result is not what you expect.
  6. 6Start the project. Run tmuxinator start with your project name to open the session. Use the same command each day to get the same workspace.

Install tmuxinator with RubyGems

Tmuxinator is written in Ruby and is licensed under MIT. You need a currently maintained Ruby version, and tmux 1.8 or later is recommended. The tmux version 2.5 is not supported.

The README prefers installing through RubyGems. Some users have reported issues when installing via Homebrew, so RubyGems is the preferred route until those issues are resolved. If your system Ruby is unsupported, the README suggests using RVM or rbenv to install a supported Ruby and use that version's gem binary.

  • Make sure tmux is installed and is version 1.8 or later, not 2.5.
  • Use a currently maintained Ruby, or install one with RVM or rbenv.
gem install tmuxinator

Set your default editor and enable shell completion

Tmuxinator opens config files in your shell's default editor. To check what it is, run the command below. If you want to change it, add an export line to your shell startup file, such as ~/.bashrc.

If you installed with gem, completion files are not installed automatically. The README gives wget commands for bash, zsh and fish that put the completion file where your shell loads it.

  • bash: /etc/bash_completion.d/tmuxinator.bash
  • zsh: /usr/local/share/zsh/site-functions/_tmuxinator (other $fpath locations also work)
  • fish: ~/.config/fish/completions/tmuxinator.fish
echo $EDITOR

Create a project config with tmuxinator new

Run tmuxinator new followed by a project name. Your default editor opens a config file, and if the project is new you will see a sample config. Use tmuxinator open to create or open a config, or tmuxinator edit to change an existing one without creating a new one. The aliases n, o and e are available for new, open and edit.

To keep the config inside a project folder, add --local. The file is then stored as .tmuxinator.yml in the current working directory instead of the default location such as ~/.config/tmuxinator. Project names cannot contain dots, because tmux uses dots to separate windows and panes.

To build a project from a session that is already running, pass the session name as a second argument. Tmuxinator records the windows, layouts, panes, session options and a project root based on the session's default-path.

  • Dots are not allowed in project names.
  • The default config is saved as a sample you can edit.
  • tmuxinator new [project] [session] creates a project from an existing tmux session.
tmuxinator new [project]

Define windows and panes in the YAML file

Each window is a YAML array entry with a name and a command. A window can also be given a null value (null or ~) so that it uses its default name, which is usually the name of your shell. A window can have its own root directory, which overrides the top-level root.

Panes are children of a window and do not need names. The layout setting is passed directly to tmux, so you can use one of the five standard tmux layouts or define your own. Indentation in the YAML matters. If the config does not behave as expected, check indentation first.

  • Use layout: main-vertical to place one large pane beside smaller ones.
  • Set focused_pane to choose which pane is selected, by name or by zero-based index.
  • Use synchronize to send input to all panes of a window, either before or after pane commands run.
  • Set startup_window and startup_pane to choose what is selected when the project starts.
  • Set attach: false if you do not want the session attached automatically.
windows: - editor: layout: main-vertical panes: - vim - guard - server: bundle exec rails s - logs: tail -f log/development.log

Use hooks, root and tmux options for more control

The sample config lists optional settings you can uncomment. Project hooks such as on_project_start, on_project_first_start, on_project_restart, on_project_exit and on_project_stop run commands at those points. The README notes that the pre and post options are deprecated and will be replaced by project hooks.

The socket_name option selects a tmux socket. tmux_options passes command-line options to tmux, for example to use a different tmux.conf. tmux_command changes the command used to call tmux, which the README says can help with wrappers such as byobu. Pane titles can be shown with enable_pane_titles, and the position and format can be set with pane_title_position and pane_title_format.

  • on_project_start runs every time the project starts.
  • on_project_first_start runs only the first time.
  • tmux_options: -f ~/.tmux.mac.conf is an example from the sample config.
  • pane_title_position accepts bottom, top or "off"; the default is top.
# on_project_start: command # tmux_options: -f ~/.tmux.mac.conf # tmux_command: byobu

What people use it for

  • Open an editor, a development server and a log tail in one tmux session every morning.
  • Start a window with a root directory set per project, so each window opens in the right folder.
  • Share a standard terminal layout by committing a .tmuxinator.yml file to a team repository.
  • Save a running tmux session as a reusable project with tmuxinator new [project] [session].

Frequently asked questions

Is tmuxinator free to use?

Yes. The project is licensed under MIT, which is stated in the repository information for this item.

How do I install tmuxinator?

The README prefers RubyGems, so run gem install tmuxinator. Homebrew is also documented with brew install tmuxinator, but the README notes that some users have reported issues with it.

What do I need before installing tmuxinator?

You need Ruby, ideally a currently maintained version, and tmux. The README recommends tmux 1.8 or later and states that 2.5 is not supported. If your system Ruby is too old, use RVM or rbenv.

Do I need to know tmux before using tmuxinator?

Yes. The README assumes a working knowledge of tmux, including what windows and panes are. If you are new to tmux, read the tmux man pages first.

Why is my tmuxinator config not working?

The README says indentation in YAML is deliberate and often causes problems, so check it first. It also says earlier tmux versions may behave oddly, so confirm your tmux version.

How does tmuxinator compare to tmuxp or teamocil?

This source does not compare them directly. The item's analysis lists tmux-resurrect, tmuxp and teamocil as comparable projects, so review each one's documentation to decide which fits your workflow.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Tmuxinator is a good fit if you already use tmux and open the same multi-pane workspace for a project each day, or want to share one layout through a config file. It is not suited to people who do not use tmux, or who run tmux 2.5 or very old versions. If you are new to tmux, learn its windows and panes first, then consider tmuxinator or one of the comparable tools.

Install options & downloads