# How to Customize thefuck Behavior: 4 Configuration Methods Explained

> Customize thefuck behavior with 4 methods: edit settings.py, use environment variables, pass command-line flags, or create custom rules. Optimize your command-line workflow today.

- Repository: [Vladimir Iakovlev/thefuck](https://github.com/nvbn/thefuck)
- Tags: how-to-guide
- Published: 2026-02-27

---

**You can customize thefuck behavior by editing the user settings file at `~/.config/thefuck/settings.py`, exporting environment variables such as `THEFUCK_RULES`, passing command-line flags like `--debug`, or creating custom Python rule modules in `~/.config/thefuck/rules/`.**

The `thefuck` command correction tool matches failed console commands against a library of rules to suggest fixes. According to the nvbn/thefuck source code, all customization happens through configuration files, environment variables, command-line arguments, and custom rule modules—allowing you to tailor behavior without modifying the core codebase.

## Editing the User Settings File

When `thefuck` launches, it initializes a Python settings file at `~/.config/thefuck/settings.py` (falling back to `~/.thefuck/settings.py` for legacy installations). The creation logic resides in `Settings._init_settings_file` within [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py) (lines 46‑53).

### Available Configuration Options

The settings file shadows defaults defined in `DEFAULT_SETTINGS` from [`thefuck/const.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/const.py). Key options that control thefuck behavior include:

- **rules** – List of enabled rule names or `['ALL_ENABLED']` to load all bundled rules.
- **exclude_rules** – Rules to ignore even when using `ALL_ENABLED`.
- **priority** – Dictionary mapping rule names to integers; higher values run later during matching.
- **require_confirmation** – Boolean to show a prompt before executing fixes.
- **instant_mode** – Boolean to skip the interactive prompt and output the fix directly.
- **repeat** – Boolean to wrap fixes so `thefuck` runs again if the first correction fails.
- **wait_command** – Seconds to wait for slow commands before offering a fix.
- **debug** – Boolean to enable verbose output via `settings.debug`.
- **alter_history** – Boolean to write corrected commands into shell history.

### Example settings.py Configuration

```python

# ~/.config/thefuck/settings.py

rules = ['git_push', 'sudo', 'cd_parent']
exclude_rules = ['sudo']
priority = {'git_push': 10}
instant_mode = True
debug = False

```

After saving, `thefuck` reads these values automatically on the next invocation.

## Using Environment Variables

For temporary overrides, export variables mapped in `ENV_TO_ATTR` from [`thefuck/const.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/const.py) (lines 49‑63). The `Settings._settings_from_env` method in [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py) (lines 19‑23) parses these at runtime.

Common environment variables include:

- `THEFUCK_RULES` – Colon-separated list of rules to load (e.g., `cd_parent:git_push`).
- `THEFUCK_EXCLUDE_RULES` – Rules to ignore.
- `THEFUCK_PRIORITY` – Priority overrides in `rule=priority` format.
- `THEFUCK_DEBUG` – Set to `true` to enable debugging.
- `THEFUCK_INSTANT_MODE` – Set to `1` to skip confirmation prompts.
- `THEFUCK_REPEAT` – Set to `1` to enable repeat mode.
- `THEFUCK_NO_COLORS` – Set to `1` to disable colored output.
- `THEFUCK_ALTER_HISTORY` – Set to `0` to prevent history modification.

These variables take precedence over the settings file but yield to command-line flags.

## Command-Line Flags

Per-invocation tweaks are handled by the parser in [`thefuck/argument_parser.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/argument_parser.py). Flags override both file and environment settings:

- `--debug` – Sets `settings.debug = True`.
- `--repeat` – Enables repeat mode (alias generation handled in [`thefuck/utils.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/utils.py) by `get_alias`).
- `--yes` – Skips confirmation by setting `settings.require_confirmation = False`.
- `--quiet` – Disables colors via `settings.no_colors = True`.
- `--no-alter-history` – Prevents history modification.

Because argument parsing occurs last in the initialization chain, these options provide the highest priority configuration.

## Creating Custom Rules

Rules are Python modules exposing specific callables. The `corrector.get_rules_import_paths` function in [`thefuck/corrector.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/corrector.py) (lines 22‑38) discovers rules from three locations:

1. **Bundled rules** – `thefuck/rules/` directory in the package.
2. **User rules** – `~/.config/thefuck/rules/` (created by `Settings._setup_user_dir`).
3. **Third-party packages** – Any installed package named `thefuck_contrib_*` containing a `rules/` subdirectory.

### Rule Structure

Each rule module must define:

- `match(command)` – Returns `True` if the rule applies to the given command object.
- `get_new_command(command)` – Returns a string or list of strings representing the corrected command.

Optional attributes include:

- `priority` – Integer value (default rules use lower numbers; higher numbers run later).
- `enabled_by_default` – Boolean; set to `False` to require explicit inclusion in `settings.rules`.
- `requires_output` – Boolean; if `True`, the rule only runs when the original command produced output.
- `side_effect(command, new_script)` – Callable for cleanup actions.

### Example Custom Rule

Create `~/.config/thefuck/rules/git_add_all.py`:

```python
def match(command):
    return command.script == 'git add .' and 'nothing added' in command.output

def get_new_command(command):
    return 'git add -A'

```

The `Rule.from_path` method in [`thefuck/types.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/types.py) (lines 30‑54) converts this file into a `Rule` object automatically. The rule will be available immediately without registration.

## Advanced Customization Techniques

### Controlling Rule Priority

The `priority` setting accepts a dictionary mapping rule names to integers. Internally, `corrector.get_rules` in [`thefuck/corrector.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/corrector.py) (lines 46‑49) sorts rules using `key=lambda rule: rule.priority`. Lower numbers execute first; the default priority is defined in [`thefuck/types.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/types.py).

### Enabling and Disabling Rules Dynamically

The `Rule.is_enabled` method in [`thefuck/types.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/types.py) (lines 56‑66) determines participation based on:

```python
return (self.name in settings.rules
        or self.enabled_by_default
        and 'ALL_ENABLED' in settings.rules)

```

To enable a rule explicitly, add its name to `settings.rules`. To disable a rule while using `ALL_ENABLED`, add it to `settings.exclude_rules`.

### Instant Mode vs. Confirmation

**Instant mode** (`settings.instant_mode`) bypasses the interactive prompt and outputs the fix directly, while **require_confirmation** (`settings.require_confirmation`) controls whether `thefuck` asks for permission before executing. You can toggle these via the settings file, environment variables (`THEFUCK_INSTANT_MODE`), or command-line flags.

## Summary

- **Configuration File**: Edit `~/.config/thefuck/settings.py` to permanently adjust rules, priorities, and behavior flags like `instant_mode` and `require_confirmation`.
- **Environment Variables**: Use `THEFUCK_RULES`, `THEFUCK_DEBUG`, and others for shell-session-specific overrides parsed by `Settings._settings_from_env`.
- **Command-Line Flags**: Pass `--debug`, `--repeat`, or `--yes` for one-time adjustments that override all other settings.
- **Custom Rules**: Place Python modules defining `match()` and `get_new_command()` in `~/.config/thefuck/rules/` to extend the built-in correction logic without modifying the core package.

## Frequently Asked Questions

### Where is the thefuck configuration file located?

The primary location is `~/.config/thefuck/settings.py`, falling back to `~/.thefuck/settings.py` for legacy installations. [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py) creates this file automatically via `Settings._init_settings_file` if it does not exist.

### How do I disable a specific rule in thefuck?

Add the rule name to the `exclude_rules` list in your [`settings.py`](https://github.com/nvbn/thefuck/blob/main/settings.py) (e.g., `exclude_rules = ['sudo']`), or export `THEFUCK_EXCLUDE_RULES=sudo` for temporary disabling. You can also remove the rule from the `rules` list if you are not using `ALL_ENABLED`.

### Can I create custom rules for thefuck?

Yes. Create a Python file in `~/.config/thefuck/rules/` containing a `match(command)` function returning a boolean and a `get_new_command(command)` function returning the corrected command string. The `corrector.get_rules_import_paths` function discovers these automatically on the next run.

### What is the difference between instant mode and require_confirmation?

**Instant mode** (`instant_mode = True`) skips the interactive menu and immediately outputs the first suggested fix, while **require_confirmation** determines whether `thefuck` asks for permission before executing the corrected command. You can use instant mode to see the fix without running it, or combine both settings to execute immediately without prompting.