Skip to content
Get packs

Guide · Open source

How to use thefuck: install, run and fix typos faster

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

The Fuck (thefuck) is an open-source command-line tool that looks at the last command you ran, finds a likely fix for the error it produced, and offers the corrected command. This guide is for people who use a terminal and mistype commands like git or docker. By the end you will know how to install it, set up the alias, run a fix, and decide whether to confirm each suggestion or skip confirmation.

The Fucknvbn/thefuck · ★ 97.9k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have Python 3.5 or newer and pip. The README also lists python-dev.
  2. 2Install the tool. Use brew install thefuck on macOS or Linux, or pip install thefuck on other systems.
  3. 3Add the alias. Add eval $(thefuck --alias) to your .bashrc, .zshrc or other startup script.
  4. 4Open a new shell. Start a new shell session or run source on your shell config so the alias is available.
  5. 5Run fuck after an error. After a failed command, type fuck and review the suggested correction.
  6. 6Confirm or skip the fix. Press enter to run the suggestion, or ctrl+c to cancel. Use --yeah only if you accept the risk of running suggestions without confirmation.

What does thefuck do?

The Fuck is a command-line tool that corrects errors in previous console commands. It works by matching the previous command against a set of rules. If a rule matches, it builds a new command from that rule and offers it to you.

For example, if you type git brnch, the tool can suggest git branch. If you forget sudo on apt-get install vim, it can suggest sudo apt-get install vim.

Install thefuck on macOS, Linux, FreeBSD or other systems

On macOS or Linux, install it with Homebrew. On FreeBSD, use pkg. On Arch based systems, use pacman. On other systems, use pip. The README lists the prerequisites as Python 3.5 or newer, pip, and python-dev.

On Ubuntu or Mint, the README first installs the Python tooling with apt, then installs the tool with pip3 using the --user flag.

  • macOS or Linux (Homebrew): brew install thefuck
  • FreeBSD: pkg install thefuck
  • Arch based systems: sudo pacman -S thefuck
  • Other systems (pip): pip install thefuck
brew install thefuck

Set up the fuck alias in your shell

The README recommends adding an alias line to your .bash_profile, .bashrc, .zshrc or other startup script. The default alias is fuck. You can choose a different name, such as FUCK.

Changes only apply in a new shell session. To apply them immediately, run source on your shell config file, such as ~/.bashrc or ~/.zshrc. The README also links to a wiki page for Fish, Powershell and tcsh setups.

eval $(thefuck --alias) # You can use whatever you want as an alias, like for Mondays: eval $(thefuck --alias FUCK)

Run a fix after a typo

After a command fails, type fuck in the terminal. The tool shows the corrected command and waits for you. Press enter to run it, or use the arrow keys or ctrl+c as the prompt indicates.

The README shows this flow with examples. After git push fails because the branch has no upstream, fuck suggests git push --set-upstream origin master. After git brnch, fuck suggests git branch.

  • Press enter to run the suggested command
  • Press ctrl+c to cancel
  • Use the up and down arrows to pick between options where shown
fuck

Choose confirmation, auto-run or recursive fixes

By default, the tool asks before it runs a corrected command. The README says you can run fixed commands without confirmation with the --yeah option, or -y for short. It also mentions --hard as a more forceful alias for the same option.

The README also describes the -r option, which fixes commands recursively until one succeeds. The README warns against blindly running corrected commands, so use the auto-run options only when you are comfortable with that risk. The require_confirmation setting in the settings section controls this behaviour.

fuck --yeah fuck -r

Know the built-in rules and where to learn more

The tool works through rules. The README lists more than forty enabled by default. Examples include adb_unknown_command for misspelled adb commands, cd_mkdir for creating a directory before cd'ing into it, git_branch_exists for branches that already exist, and docker_not_command for wrong docker commands.

The README also covers creating your own rules, settings, and third party packages that add rules. For the full list and details, read the project README and its linked wiki pages.

  • cd_mkdir: creates directories before cd'ing into them
  • git_add_force: adds --force to git add when paths are .gitignore'd
  • git_checkout: fixes branch name or creates new branch
  • dry: fixes repetitions like git git push

Update or uninstall thefuck

To update with pip, the README uses pip3 install thefuck --upgrade. The README notes that alias functionality changed in v1.34, so check your alias line if you upgrade from an older install.

To uninstall, the README says to remove the thefuck alias line from your shell config, then use the package manager you installed with (brew, pip3, pkg, crew or pip) to remove the binaries.

pip3 install thefuck --upgrade

What people use it for

  • Fixing a misspelled git subcommand such as git brnch, which becomes git branch
  • Adding the missing upstream branch flag after git push fails
  • Correcting a python command typed as puthon
  • Adding sudo to an apt-get install that failed because of permissions
  • Fixing a misspelled docker or cargo subcommand

Frequently asked questions

Is thefuck free to use?

The Fuck is released under the MIT licence, as listed on its project page. The licence is permissive, so you can use the tool without paying for it. Check the LICENSE file in the project for the full terms.

What are the requirements for thefuck?

The README lists Python 3.5 or newer, pip, and python-dev as requirements. Installation on Ubuntu or Mint also installs python3-dev, python3-pip and python3-setuptools with apt first.

How do I install thefuck on macOS?

On macOS, run brew install thefuck through Homebrew. After installing, add the eval $(thefuck --alias) line to your shell startup file and open a new shell.

Does thefuck work on Windows?

The README does not describe a supported Windows install path beyond pip and the listed systems. Its listed platforms are macOS, Linux and FreeBSD, plus ChromeOS through chromebrew. Check the project README before trying it on Windows.

Is it safe to run the suggested commands?

The README warns against blindly running corrected commands. Keep the default confirmation on so you can read each suggestion before it runs. Only turn confirmation off if you accept that risk.

Why is thefuck slow, and are there alternatives?

The README says the default can be slow and mentions an experimental instant mode for faster results. The project README links to a list of third party packages with rules, and the alternatives listed for this directory include thefuck-alternatives and Did you mean.

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

The Fuck is a good fit for developers and terminal users on macOS, Linux or FreeBSD who often mistype git, docker or other common commands. If you would rather not run suggested commands at all, or you need instant results on every keystroke, look at the alternatives listed in this directory instead.

Install options & downloads