thefuck: rewrites the last command from a rule that matched it

It works by replaying the previous command through a rule

The mechanism is a match, not an AI guess. When you run fuck, the tool takes the previous command and the output it produced and tries each enabled rule against them. If a rule matches, a new command is built from that rule and offered for you to run. The default set is long and specific. adb_unknown_command repairs a mistyped adb subcommand, cd_mkdir creates a directory before cd'ing into it, cp_create_destination makes a directory when you copy into a missing one, dirty_untar fixes a tar that extracted into the current directory, and docker_login runs docker login and then repeats what you were trying to do. Consequence for the reader: the correction is only as good as the rule, so the tool fixes the mistakes someone thought to write a rule for and leaves your typo alone if no one has.

The shell alias is how the tool ever runs

Installing the package is not enough on its own. The README tells you to place a line in your shell startup file.

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

That eval line defines the command in your shell, and the README notes the change is only live in a new session unless you source your config, for example with source ~/.bashrc. Consequence for the reader: you are evaluating output into your interactive shell at every login, and the alias name is yours to choose, so the four-letter default and the uppercase variant are both supported. Anyone auditing a shell profile is looking at an eval of a command substitution, not a plain binary, which is a line worth understanding before you commit it to a dotfiles repo.

Two flags change how much the tool trusts you

By default the corrected command waits for you. Press enter to run it, the arrow keys to move through alternatives, and ctrl+c to give up. The README also documents a setting, require_confirmation, that you can disable if you are willing to run corrected commands blindly. Two command-line options skip the review step for a single invocation.

fuck --yeah

The short form is -y, and the README offers --hard if you are especially frustrated. There is also a recursive mode that keeps fixing until something succeeds.

fuck -r

Consequence for the reader: --yeah and -r stack the two ways this tool can surprise you. One fires the correction without showing you, the other chains corrections, so together they can run several commands you never read. For a utility whose whole pitch is rewriting commands, that is the switch to leave off until you trust the rule set on your machine.

Every platform gets its own install, and none of them are the same command

The README branches by operating system rather than offering one path. macOS and Linux go through Homebrew.

brew install thefuck

Ubuntu and Mint install the build tools and then the package for the current user.

sudo apt update
sudo apt install python3-dev python3-pip python3-setuptools
pip3 install thefuck --user

FreeBSD uses pkg, ChromeOS uses crew from chromebrew, Arch uses pacman, and anything else falls back to a plain pip install.

pip install thefuck

Consequence for the reader: the requirements are python 3.5 and later plus pip and python-dev, so on the Ubuntu path you are installing a Python package for your user account, not a system binary, and on the others a system package manager owns the file. Upgrading is a separate pip3 install thefuck --upgrade, which is a pip-shaped task even on the machines where you installed with brew. Removing it is likewise two steps, erasing or commenting the alias line in your shell config and then uninstalling the binary through whichever package manager put it there. The mixed ownership is the part that trips people up, because a brew install and a later pip install leave two copies on the path and the one that wins is decided by your shell's ordering rather than by either tool.

The last commit is 2024 and the newest release is from 2022

Maintenance is the fact you have to weigh. The repository is not archived, but the last push was 2024-07-19, and the most recent tagged releases are 3.32 from 2022-01-02, 3.31 from 2021, and 3.30 from 2020. The README also carries a note that alias functionality changed in v1.34, a reminder that the interface has moved under you before. Consequence for the reader: this is a project with a very large rule set and a long quiet period, so the rules still describe the mistakes the author cared about, and the ones that depend on a tool's current output format, an error string that has since changed, can silently stop firing. A rule that stops matching does not warn you, it just stops helping.

The package ships two entry points and one first-run helper

setup.py registers more than the command you type. On macOS and Linux it declares console_scripts for thefuck and fuck, both pointing at thefuck.entrypoints.main:main, plus a thefuck_firstuse entry point at thefuck.entrypoints.not_configured:main. On Windows it swaps in scripts\fuck.bat and scripts\fuck.ps1. The runtime dependencies are short, psutil, colorama, and six, with older interpreters picking up extras such as pathlib2 and win_unicode_console. Consequence for the reader: fuck is the friendly name and thefuck is the real entry, and the first-use hook is how the tool handles being run before the alias is configured. The dependency list is light, but the rule set is where the weight sits, and it lives in the thefuck/ directory rather than in these few imports.

setup.py gates the interpreter before it installs anything

The installer checks its own environment before it does anything else. It reads the installed pip version and exits with a message telling you to run pip install -U pip if pip is older than 6.0. It then reads sys.version_info and refuses to continue on Python older than 2.7, and separately on a Python version between 3.0 and 3.5, printing that thefuck requires Python version 3.5 or later along with the version it detected. Consequence for the reader: the two version checks are written out separately and the message for each names the version it found, so an interpreter that is too old is caught at install time rather than at first run. The cost is a hard stop, not a warning, which on a locked-down machine where you cannot upgrade pip yourself means the install simply refuses.

Instant mode trades a pause for a faster suggestion

The README opens by acknowledging the tool can be slow and pointing at an experimental instant mode as the answer. The regular path waits, and the instant path is offered as the alternative when the pause is the problem. Consequence for the reader: the thing you are installing has a performance complaint attached to it by its own author, and the fix is labelled experimental rather than default, which tells you it is not the path the author wants most people on. If you are sensitive to latency between typing fuck and seeing a suggestion, you are the case that mode was written for, and you should expect it to be the less travelled one. The repository ships two example recordings, example.gif and example_instant_mode.gif, which is the author's way of letting you compare the two before deciding.

Editorial conclusion

thefuck earns a place on a workstation where you lean on shell tools with deep subcommand trees, because the default rules cover real cases like cd into a missing directory, a tar that unpacked in place, or a mistyped subcommand. It does not earn one in a locked-down environment, since it installs a shell alias that runs an executable the moment you type fuck, and it does not fit a team that needs an actively patched tool, because the last commit was 2024-07-19 and the newest tagged release, 3.32, is from 2022. Before you wire it into a shell profile that every terminal loads, read the rule that fires on your own most common typo, and confirm the project still installs on your Python, which the requirements pin at 3.5 and later.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes