How to Configure The Fuck with Environment Variables

The Fuck reads configuration from environment variables defined in the ENV_TO_ATTR mapping in thefuck/const.py, converting values to appropriate Python types via _val_from_env() in thefuck/conf.py during initialization.

The Fuck (nvbn/thefuck) supports environment-variable-driven configuration as a first-class alternative to the settings.py file. When the library initializes, the settings.init() method in 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, the _settings_from_env() method iterates over the ENV_TO_ATTR dictionary defined in thefuck/const.py:

# 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:

# 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 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').

# 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 and thefuck/shells/zsh.py to enable instant execution without confirmation prompts.
• TF_ALIAS: Consulted in 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 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:

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:

export THEFUCK_REQUIRE_CONFIRMATION=false
thefuck

Adjust Analysis Wait Time

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

export THEFUCK_WAIT_COMMAND=1
thefuck

Prioritize Specific Rules

Assign priority weights using rule=value syntax:

export THEFUCK_PRIORITY="git=10"
thefuck

Enable Instant Mode

Activate instant mode for non-interactive shell integration:

export THEFUCK_INSTANT_MODE=true
thefuck

Override the Command Name

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

export TF_ALIAS=fix
fix  # invokes thefuck

Define Slow Commands

Identify commands requiring special timeout handling:

export THEFUCK_SLOW_COMMANDS="gradle:webpack"
thefuck

Combine Multiple Variables

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

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 using the ENV_TO_ATTR map from 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.

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 and 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 file?

Yes. The settings.init() method merges configuration from 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}