# How to Configure The Fuck with Environment Variables

> Learn how environment variables configure The Fuck. Discover ENV_TO_ATTR mapping and _val_from_env for custom behavior.

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

---

**The Fuck reads configuration from environment variables defined in the `ENV_TO_ATTR` mapping in [`thefuck/const.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/const.py), converting values to appropriate Python types via `_val_from_env()` in [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py) during initialization.**

The Fuck (nvbn/thefuck) supports environment-variable-driven configuration as a first-class alternative to the [`settings.py`](https://github.com/nvbn/thefuck/blob/main/settings.py) file. When the library initializes, the `settings.init()` method in [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py) calls `_settings_from_env()` to build a configuration dictionary from your shell environment, allowing you to customize behavior without modifying files.

## The Configuration Pipeline

Configuration loading follows a predictable hierarchy. The `Settings` class initializes by merging sources, with environment variables taking precedence over default values.

In [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py), the `_settings_from_env()` method iterates over the `ENV_TO_ATTR` dictionary defined in [`thefuck/const.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/const.py):

```python

# thefuck/conf.py

def _settings_from_env(self):
    """Loads settings from env."""
    return {attr: self._val_from_env(env, attr)
            for env, attr in const.ENV_TO_ATTR.items()
            if env in os.environ}

```

The `ENV_TO_ATTR` mapping translates shell-friendly variable names into internal Python attributes:

```python

# thefuck/const.py

ENV_TO_ATTR = {
    'THEFUCK_RULES': 'rules',
    'THEFUCK_EXCLUDE_RULES': 'exclude_rules',
    'THEFUCK_WAIT_COMMAND': 'wait_command',
    'THEFUCK_REQUIRE_CONFIRMATION': 'require_confirmation',
    'THEFUCK_NO_COLORS': 'no_colors',
    'THEFUCK_DEBUG': 'debug',
    'THEFUCK_PRIORITY': 'priority',
    'THEFUCK_HISTORY_LIMIT': 'history_limit',
    'THEFUCK_ALTER_HISTORY': 'alter_history',
    'THEFUCK_WAIT_SLOW_COMMAND': 'wait_slow_command',
    'THEFUCK_SLOW_COMMANDS': 'slow_commands',
    'THEFUCK_REPEAT': 'repeat',
    'THEFUCK_INSTANT_MODE': 'instant_mode',
    'THEFUCK_NUM_CLOSE_MATCHES': 'num_close_matches',
    'THEFUCK_EXCLUDED_SEARCH_PATH_PREFIXES': 'excluded_search_path_prefixes',
}

```

## Variable Types and Value Syntax

The `_val_from_env()` method in [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py) handles type conversion automatically. You must format values according to the target attribute's expected type:

- **List values** (`rules`, `exclude_rules`, `slow_commands`, `excluded_search_path_prefixes`): Split elements with a colon (`:`).
- **Priority mapping** (`priority`): Use `rule=number` syntax for ordering.
- **Integers** (`wait_command`, `history_limit`, `wait_slow_command`, `num_close_matches`): Provide numeric strings castable via `int()`.
- **Booleans** (`require_confirmation`, `no_colors`, `debug`, `alter_history`, `instant_mode`): Use `true` or `false` (case-insensitive evaluation checks `value.lower() == 'true'`).

```python

# thefuck/conf.py

def _val_from_env(self, env, attr):
    """Transforms env‑strings to python."""
    val = os.environ[env]
    if attr in ('rules', 'exclude_rules'):
        return self._rules_from_env(val)
    elif attr == 'priority':
        return dict(self._priority_from_env(val))
    elif attr in ('wait_command', 'history_limit', 'wait_slow_command',
                  'num_close_matches'):
        return int(val)
    elif attr in ('require_confirmation', 'no_colors', 'debug',
                  'alter_history', 'instant_mode'):
        return val.lower() == 'true'
    elif attr in ('slow_commands', 'excluded_search_path_prefixes'):
        return val.split(':')
    else:
        return val

```

## Runtime-Specific Environment Variables

Beyond the standard `ENV_TO_ATTR` mapping, several variables control runtime behavior in specific modules:

- **`THEFUCK_INSTANT_MODE`**: Checked in [`thefuck/shells/bash.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/shells/bash.py) and [`thefuck/shells/zsh.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/shells/zsh.py) to enable instant execution without confirmation prompts.
- **`TF_ALIAS`**: Consulted in [`thefuck/utils.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/utils.py) to override the default command name (`fuck`).
- **`TF_SHELL_ALIASES`** / **`TF_OVERRIDDEN_ALIASES`**: Used by shell-specific modules for custom alias handling.
- **`SHELL_LOGGER_SOCKET`**: Configured in [`thefuck/output_readers/shell_logger.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/output_readers/shell_logger.py) to set the communication socket for the shell logger.

## Practical Configuration Examples

### Set a Custom Rule List

Restrict The Fuck to specific rules by separating identifiers with colons:

```bash
export THEFUCK_RULES="git:python:docker"
thefuck

```

The value `git:python:docker` splits into `['git', 'python', 'docker']`.

### Disable Confirmation Prompts

Run corrected commands automatically without interactive approval:

```bash
export THEFUCK_REQUIRE_CONFIRMATION=false
thefuck

```

### Adjust Analysis Wait Time

Control how many seconds The Fuck waits before analyzing the previous command:

```bash
export THEFUCK_WAIT_COMMAND=1
thefuck

```

### Prioritize Specific Rules

Assign priority weights using `rule=value` syntax:

```bash
export THEFUCK_PRIORITY="git=10"
thefuck

```

### Enable Instant Mode

Activate instant mode for non-interactive shell integration:

```bash
export THEFUCK_INSTANT_MODE=true
thefuck

```

### Override the Command Name

Use `TF_ALIAS` to rename the entrypoint (e.g., from `fuck` to `fix`):

```bash
export TF_ALIAS=fix
fix  # invokes thefuck

```

### Define Slow Commands

Identify commands requiring special timeout handling:

```bash
export THEFUCK_SLOW_COMMANDS="gradle:webpack"
thefuck

```

### Combine Multiple Variables

Configure a complete session with rule filtering, disabled colors, and instant mode:

```bash
export THEFUCK_RULES="git:python"
export THEFUCK_NO_COLORS=true
export THEFUCK_INSTANT_MODE=true
thefuck

```

## Summary

- **Configuration source**: The Fuck loads environment variables via `_settings_from_env()` in [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py) using the `ENV_TO_ATTR` map from [`thefuck/const.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/const.py).
- **Type handling**: The `_val_from_env()` method automatically converts strings to lists (colon-separated), integers, booleans (case-insensitive `true`/`false`), and priority mappings.
- **Shell integration**: Variables like `TF_ALIAS` and `THEFUCK_INSTANT_MODE` provide runtime control in shell-specific modules and utilities.
- **No file edits required**: Environment variables allow temporary or persistent configuration without modifying [`settings.py`](https://github.com/nvbn/thefuck/blob/main/settings.py).

## Frequently Asked Questions

### What is the difference between `THEFUCK_RULES` and `THEFUCK_EXCLUDE_RULES`?

`THEFUCK_RULES` accepts a colon-separated list defining an allowlist of rules to enable (e.g., `git:docker`), while `THEFUCK_EXCLUDE_RULES` accepts a colon-separated list of rules to disable. If you set `THEFUCK_RULES`, The Fuck uses only those specified rules; if you set `THEFUCK_EXCLUDE_RULES`, it uses all rules except those listed.

### How do I enable instant mode using environment variables?

Set `THEFUCK_INSTANT_MODE` to `true`. According to the source code in [`thefuck/shells/bash.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/shells/bash.py) and [`thefuck/shells/zsh.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/shells/zsh.py), this boolean flag bypasses the confirmation prompt and immediately executes the corrected command. Ensure you also export `TF_ALIAS` if your shell setup requires a specific entrypoint name for instant mode integration.

### Why does `THEFUCK_PRIORITY` use a different syntax than list variables?

Unlike lists that use simple colon separation, `THEFUCK_PRIORITY` expects `key=value` pairs to construct a Python dictionary mapping rule names to numeric priority values. The `_val_from_env()` method specifically checks for the `priority` attribute and calls `_priority_from_env()` to parse these pairs, allowing you to control the order in which rules are evaluated.

### Can I use environment variables to completely replace the [`settings.py`](https://github.com/nvbn/thefuck/blob/main/settings.py) file?

Yes. The `settings.init()` method merges configuration from [`settings.py`](https://github.com/nvbn/thefuck/blob/main/settings.py), environment variables, and command-line arguments. Since environment variables are processed after defaults but before CLI args, you can define all standard options (rules, timeouts, boolean flags) via environment variables. However, complex Python logic or custom rule functions still require [`settings.py`](https://github.com/nvbn/thefuck/blob/main/settings.py).