Skip to content
Get packs

Guide · Open source

How to use oh-my-fish: install, omf commands and tips

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

Oh My Fish is a framework for the fish command-line shell. It gives you core infrastructure to install packages and themes that change how your shell looks and behaves, all managed with an included omf command. This guide walks through installing it, the main omf commands, where your settings live, and what to watch for, since the README says the project is unmaintained.

Oh My Fishoh-my-fish/oh-my-fish · ★ 11.4k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have fish 3.0 or later and git 1.9.5 or later.
  2. 2Run the installer. Run the default install command in fish to download and install Oh My Fish.
  3. 3List available themes. Run omf theme with no argument to see the themes you can apply.
  4. 4Apply a theme. Run omf theme followed by the theme name to switch your prompt.
  5. 5Install a package. Run omf install with a package name, URL or user/repo.
  6. 6Back up your config. Keep the $OMF_CONFIG directory under version control so theme, bundle and channel files are saved.
  7. 7Troubleshoot. If something breaks, run omf doctor before opening an issue.

Check the requirements before you install

Oh My Fish needs the fish shell, version 3.0 or later, and git, version 1.9.5 or later. If you do not use fish, this framework is not for you.

  • fish shell, version 3.0 or later
  • git, version 1.9.5 or later

Install Oh My Fish with the default setup

Run the default installer in fish. The README says this downloads the installer script and starts the installation.

To customize the install paths, download the installer first and pass options. Run install --help for a full list of options. You can also verify the installer against the published checksum.

  • Use --offline if you have no network access. It skips fetching plugins, which you can fetch later with omf install.
  • Install from git by cloning the repository and running bin/install --local-source.
curl https://raw.githubusercontent.com/oh-my-fish/oh-my-fish/master/bin/install | fish

Use the omf command to manage themes and packages

Oh My Fish includes a small utility, omf, to fetch and install new packages and themes. The commands below are the core ones described in the README.

  • omf install name|url|user/repo installs one or more packages.
  • omf theme theme-name applies a theme. Run omf theme with no argument to list available themes.
  • omf search name finds a package or theme, with fuzzy matching.
  • omf list shows installed packages.
  • omf remove name removes a theme or package.
  • omf update updates Oh My Fish, package repositories and installed packages.
  • omf reload restarts the shell to reload Oh My Fish and plugins.
omf install user/repo

Know where your settings are stored

The $OMF_CONFIG directory holds your Oh My Fish user state and is a good candidate for your dotfiles or version control. It contains three key files: theme (the current theme), bundle (the list of installed packages and themes) and channel (stable or dev updates).

You can also create init.fish for custom code sourced after shell start, before.init.fish for code sourced before start, and key_bindings.fish for custom key bindings. Every time you install or remove a package, the bundle file is updated. Editing bundle by hand and running omf install applies the changes, but removing an entry does not uninstall the package.

set -xg PYTHONDONTWRITEBYTECODE 1

Troubleshoot broken themes and packages

The README warns that a few themes and packages are currently broken. Start with omf doctor, which the README recommends before opening an issue.

Load order also matters. Files in ~/.config/fish/conf.d/ are sourced in filesystem order, so you may need numeric prefixes such as 00_ to run a script before omf.fish. The README also notes a fish 2.6 regression where right prompts make the shell unusable, and says the default theme has a right prompt, so an alternative theme is needed on that version.

  • Run omf doctor and check the output.
  • Rename scripts with ordering prefixes if a custom script runs in the wrong order.
  • If the default theme breaks on fish 2.6, pick a theme without a right prompt.

What people use it for

  • Switching fish prompt themes with omf theme.
  • Installing a community package directly from a GitHub user/repo with omf install.
  • Keeping a shell setup in dotfiles by version-controlling the $OMF_CONFIG directory.
  • Adding custom environment variables such as GOPATH in init.fish.

Frequently asked questions

Is Oh My Fish free and open source?

Yes. The project is licensed under the MIT License, as shown in the README. The source is on GitHub under the oh-my-fish organisation.

What does Oh My Fish require?

It requires fish shell version 3.0 or later and git version 1.9.5 or later. It is only useful if you use the fish shell.

Is Oh My Fish still maintained?

No. The README says the project has been unmaintained for years, a few themes and packages are broken, and the current maintainers have run out of steam. It is not a good choice if you need a well-maintained tool.

How do I install Oh My Fish?

Run the default installer command in fish, or clone the repository with git and run bin/install --local-source. The README also describes a customizable install and an offline option.

Why isn't my theme working?

The README says some themes and packages are currently broken. Run omf doctor to troubleshoot, and try a different theme or package if the problem persists.

What are the alternatives to Oh My Fish?

The README lists oh-my-zsh, Fisher and Starship as comparable projects. Oh My Zsh is for zsh rather than fish, while Fisher and Starship are other options for fish users.

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

Oh My Fish suits fish users who want an easy way to add themes and prompt tweaks and are comfortable fixing an occasional broken package. If you need a dependable, maintained setup, pick an alternative such as Fisher or Starship, or oh-my-zsh if you are switching to zsh.

Install options & downloads