Python UnboundLocalError — Complete Fix Guide 🔗

Python developers ka most confusing error — UnboundLocalError. Variable scope issues, global vs local variables, function shadowing — sab reasons cover karenge with solutions. Real employee data examples, debugging tips, aur interview questions ke saath. Data Insights par.

📑 Is Blog Mein Kya Sikhenge:

• 🟢 Basic: UnboundLocalError kya hai, kab aati hai
• 🟡 Medium: Common Causes — global variable shadowing, conditional assignment
• 🔴 Advanced: global keyword, nonlocal keyword, closures
• 🛠️ Solutions: Parameters, return values, class attributes
• 🔍 Debugging: Kaise trace aur prevent karo
• 💬 Interview: Top asked questions

📘 Definition: UnboundLocalError Python ka built-in exception hai jo tab raise hoti hai jab tum function ke andar kisi variable ko USE karte ho jo ABHI TAK ASSIGN nahi hui, lekin same function mein LATER assign hoti hai. Ye NameError ki subclass hai. Ye error confusing hai kyunki lagta hai variable exist karti hai (global), lekin Python function scope mein use karte time confuse ho jaata hai.

🎯 Samjho Hinglish Mein: Socho tumhare ghar ke bahar ek "AARAV" naam ka board laga hai (global). Ab tumne room ke andar bhi likha "AARAV = new name". Python ne room enter karte hi dekh liya — "andar bhi AARAV naam use hoga later". Ab tum bolo "AARAV ko print karo" (uss line se pehle jaha assign kiya) — Python confuse — bahar wala use kare ya andar wala? Ye assume karta hai ki tum ANDAR waala chahte ho (kyunki andar assignment hai) — but abhi tak assign nahi hui — hence UnboundLocalError! Function scope Python ka trick concept hai.

📊 Sample Data (Employee Salary Calculator):

# Global company variables
company_name = "TechCorp"
total_employees = 5
average_salary = 66000

# Employee data
employees = [
    {"name": "Aarav", "salary": 55000},
    {"name": "Ishita", "salary": 72000},
    {"name": "Kabir", "salary": 65000},
    {"name": "Diya", "salary": 58000},
    {"name": "Rohan", "salary": 80000}
]

def update_average():
    print(f"Current average: ₹{average_salary}")   # Read global
    average_salary = sum(e["salary"] for e in employees) / total_employees
    # ❌ UnboundLocalError!
    # Python sees assignment below → treats as LOCAL variable
    # But used BEFORE assignment → error!

❌ Error Output:

update_average()

# ❌ ERROR OUTPUT:
# Traceback (most recent call last):
#   File "salary.py", line 20, in <module>
#     update_average()
#   File "salary.py", line 14, in update_average
#     print(f"Current average: ₹{average_salary}")
# UnboundLocalError: cannot access local variable 'average_salary'
# where it is not associated with a value

📘 Cause: Sabse common case — global variable exist karti hai, function ke andar SAME NAME ki variable assign karte ho, aur pehle usko READ karne ki koshish karte ho. Python confused ho jaata hai — assignment hai toh local samajh leta hai, but read before assign — error!

❌ Wrong Code (Error):

# ❌ Global variable
total_salary = 330000

def add_bonus():
    print(f"Current total: ₹{total_salary}")   # Read
    total_salary = total_salary + 50000       # Assignment
    print(f"After bonus: ₹{total_salary}")

add_bonus()
# ❌ UnboundLocalError: cannot access local variable 'total_salary'

# ❌ Another example — counter
counter = 0

def increment():
    counter += 1   # ❌ UnboundLocalError
    # Reason: counter += 1 is same as counter = counter + 1
    # Assignment (=) makes it local, but read fails

# ❌ Employee count
employee_count = 5

def hire_employee():
    print(f"Before: {employee_count} employees")  # Read
    employee_count = employee_count + 1          # Assignment
    print(f"After: {employee_count} employees")   # ❌ Error!

✅ Fix Options:

# ✅ Solution 1: Use 'global' keyword
total_salary = 330000

def add_bonus():
    global total_salary   # Explicit: use global
    print(f"Current total: ₹{total_salary}")
    total_salary = total_salary + 50000
    print(f"After bonus: ₹{total_salary}")

add_bonus()   # ✅ Works!
print(f"Outside function: {total_salary}")   # Also updated

# ✅ Solution 2: Pass as parameter (BEST!)
def add_bonus(current_total, bonus=50000):
    print(f"Current: ₹{current_total}")
    new_total = current_total + bonus
    print(f"After: ₹{new_total}")
    return new_total

total_salary = 330000
total_salary = add_bonus(total_salary)   # ✅ Clean!

# ✅ Solution 3: Different variable name
total_salary = 330000

def calculate_new_total():
    new_total = total_salary + 50000   # Different name
    print(f"New total: ₹{new_total}")
    return new_total

new_amount = calculate_new_total()   # ✅ Works

# ✅ Solution 4: Return updated value
employee_count = 5

def hire_employee(current_count):
    new_count = current_count + 1
    print(f"Hired! Count: {current_count} → {new_count}")
    return new_count

employee_count = hire_employee(employee_count)
# ✅ Explicit, clean, testable!

📘 Cause: Variable ko if/else block ke andar assign kiya lekin condition FALSE ho toh assignment kabhi execute nahi hoti — variable "unbound" reh jaati hai. Python static analysis mein assignment DEKHTA hai but runtime pe skip ho sakti hai.

❌ Wrong Code (Error):

# ❌ Conditional assignment
def get_employee_bonus(salary):
    if salary > 70000:
        bonus = salary * 0.15
    # No else clause!
    return bonus   # ❌ Error if salary <= 70000

print(get_employee_bonus(75000))   # ✅ Works: 11250.0
print(get_employee_bonus(55000))   # ❌ UnboundLocalError

# ❌ Nested conditions
def classify_employee(experience):
    if experience > 5:
        level = "Senior"
    elif experience > 2:
        level = "Mid"
    # Missing: elif for <= 2 or else
    return level   # ❌ Error for experience <= 2

# ❌ Loop without match
def find_employee(emp_id, employees):
    for emp in employees:
        if emp["id"] == emp_id:
            found = emp
    return found   # ❌ Error if no match found!

✅ Fix Options:

# ✅ Solution 1: Initialize variable BEFORE condition
def get_employee_bonus(salary):
    bonus = 0   # Default value
    if salary > 70000:
        bonus = salary * 0.15
    return bonus   # ✅ Always defined

print(get_employee_bonus(55000))   # 0
print(get_employee_bonus(75000))   # 11250.0

# ✅ Solution 2: Add else clause
def classify_employee(experience):
    if experience > 5:
        level = "Senior"
    elif experience > 2:
        level = "Mid"
    else:
        level = "Junior"   # Default
    return level   # ✅ Always defined

# ✅ Solution 3: Use ternary operator
def get_bonus(salary):
    bonus = salary * 0.15 if salary > 70000 else 0
    return bonus

# ✅ Solution 4: Return early
def get_bonus(salary):
    if salary > 70000:
        return salary * 0.15
    return 0   # Default return

# ✅ Solution 5: Handle "not found" case
def find_employee(emp_id, employees):
    found = None   # Default None
    for emp in employees:
        if emp["id"] == emp_id:
            found = emp
            break
    return found   # ✅ None if not found

# Real employee example
employees = [
    {"id": 101, "name": "Aarav", "salary": 55000},
    {"id": 102, "name": "Ishita", "salary": 72000}
]

def get_employee(emp_id):
    for emp in employees:
        if emp["id"] == emp_id:
            return emp
    return None   # ✅ Explicit None if not found

print(get_employee(101))   # Aarav's data
print(get_employee(999))   # None

📘 Definition: global keyword Python ko explicitly batata hai — "yeh variable global scope ki hai, LOCAL nahi banao". Ye UnboundLocalError ko fix karta hai jab tum truly global variable modify karna chahte ho. But be careful — globals over-use karna bad practice hai.

💻 Global Keyword Examples:

# Global variables
total_employees = 5
total_salary = 330000
company_name = "TechCorp"

# ✅ Read-only access — no global keyword needed
def print_info():
    print(f"Company: {company_name}")
    print(f"Employees: {total_employees}")
    # Reading is fine — no assignment

print_info()   # ✅ Works

# ✅ Modify global — MUST use 'global' keyword
def hire_employee(salary):
    global total_employees, total_salary
    total_employees += 1
    total_salary += salary
    print(f"✅ Employee hired. Total: {total_employees}")

hire_employee(60000)
print(f"After hire: {total_employees} employees, ₹{total_salary}")
# Output:
# ✅ Employee hired. Total: 6
# After hire: 6 employees, ₹390000

# ❌ Without global keyword
def wrong_hire(salary):
    total_employees += 1   # ❌ UnboundLocalError
    total_salary += salary

# ✅ Multiple globals in one statement
def reset_company():
    global total_employees, total_salary, company_name
    total_employees = 0
    total_salary = 0
    company_name = "New Corp"
    print("✅ Company reset")

# ✅ Verify global change
def check_globals():
    print(f"Employees: {total_employees}")
    print(f"Salary: ₹{total_salary}")
    print(f"Company: {company_name}")

⚠️ Why global is BAD PRACTICE:

# ❌ BAD: Heavy use of globals
total_employees = 0
total_salary = 0
department_count = 0

def add_employee(salary, dept):
    global total_employees, total_salary, department_count
    total_employees += 1
    total_salary += salary
    # ... more global modifications

# Problems:
# 1. Hard to test (state changes)
# 2. Hard to debug (state can change anywhere)
# 3. Not thread-safe
# 4. Coupling between functions

# ✅ GOOD: Use class or return values
class Company:
    def __init__(self, name):
        self.name = name
        self.total_employees = 0
        self.total_salary = 0
    
    def hire(self, salary):
        self.total_employees += 1
        self.total_salary += salary
        return self
    
    def get_stats(self):
        return {
            "employees": self.total_employees,
            "total_salary": self.total_salary
        }

# Clean, testable, maintainable!
company = Company("TechCorp")
company.hire(55000)   # Aarav
company.hire(72000)   # Ishita
print(company.get_stats())   # {'employees': 2, 'total_salary': 127000}

📘 Definition: nonlocal keyword nested functions (closures) mein use hota hai — enclosing function ki variable modify karne ke liye. global module-level ke liye, nonlocal nested function ke enclosing scope ke liye. Advanced concept but important for closures.

❌ Without nonlocal (Error):

# ❌ Employee counter with closure — WRONG
def create_counter():
    count = 0   # Enclosing scope variable
    
    def increment():
        count += 1   # ❌ UnboundLocalError
        return count
    
    return increment

counter = create_counter()
print(counter())   # ❌ Error!

# Reason: Python sees 'count += 1' as assignment inside inner function
# Treats 'count' as local to inner function
# But count is enclosing scope variable
# Result: UnboundLocalError

✅ With nonlocal (Fixed):

# ✅ Employee counter — using nonlocal
def create_counter():
    count = 0
    
    def increment():
        nonlocal count   # ✅ Modify enclosing variable
        count += 1
        return count
    
    return increment

counter = create_counter()
print(counter())   # 1
print(counter())   # 2
print(counter())   # 3

# ✅ Real-world: Employee ID generator
def create_id_generator(start=101):
    current_id = start
    
    def next_id():
        nonlocal current_id
        result = current_id
        current_id += 1
        return result
    
    return next_id

generate_id = create_id_generator()
aarav_id = generate_id()   # 101
ishita_id = generate_id()  # 102
kabir_id = generate_id()   # 103
print(f"IDs: Aarav={aarav_id}, Ishita={ishita_id}, Kabir={kabir_id}")

# ✅ Salary tracker closure
def create_salary_tracker():
    total = 0
    count = 0
    
    def add_salary(amount):
        nonlocal total, count
        total += amount
        count += 1
        average = total / count
        return {
            "total": total,
            "count": count,
            "average": average
        }
    
    return add_salary

tracker = create_salary_tracker()
print(tracker(55000))   # Aarav
print(tracker(72000))   # Ishita
print(tracker(65000))   # Kabir
# Output:
# {'total': 55000, 'count': 1, 'average': 55000.0}
# {'total': 127000, 'count': 2, 'average': 63500.0}
# {'total': 192000, 'count': 3, 'average': 64000.0}

📋 global vs nonlocal Comparison:

📘 Best Practice: UnboundLocalError se bachne ka BEST solution — global variables avoid karo. Instead, use function parameters aur return values. Ye code cleaner, testable, aur predictable banata hai. Modern Python community mein "pure functions" preferred hain — jo external state modify nahi karti.

💻 Best Practice Examples:

# ❌ ANTI-PATTERN: Global state
total_salary = 0

def add_to_total(amount):
    global total_salary
    total_salary += amount   # Hard to test, hidden state

# ✅ BEST PRACTICE: Pure function
def add_to_total(current_total, amount):
    return current_total + amount   # Testable!

total_salary = 0
total_salary = add_to_total(total_salary, 55000)   # Aarav
total_salary = add_to_total(total_salary, 72000)   # Ishita
print(total_salary)   # 127000

# ✅ Employee management — clean approach
def calculate_bonus(salary, performance_rating):
    """Pure function — no side effects"""
    if performance_rating >= 4.5:
        return salary * 0.20
    elif performance_rating >= 3.5:
        return salary * 0.10
    else:
        return 0

def calculate_total_compensation(salary, bonus, benefits=5000):
    """Pure function — testable"""
    return salary + bonus + benefits

def process_employee(employee):
    """Compose multiple pure functions"""
    salary = employee["salary"]
    rating = employee["rating"]
    
    bonus = calculate_bonus(salary, rating)
    total = calculate_total_compensation(salary, bonus)
    
    return {
        "name": employee["name"],
        "salary": salary,
        "bonus": bonus,
        "total": total
    }

# Usage — clean, no globals
employees = [
    {"name": "Aarav", "salary": 55000, "rating": 4.5},
    {"name": "Ishita", "salary": 72000, "rating": 4.8},
    {"name": "Kabir", "salary": 65000, "rating": 3.9}
]

results = [process_employee(emp) for emp in employees]
for result in results:
    print(f"{result['name']}: ₹{result['total']}")

# ✅ Alternative: Use class for stateful operations
class SalaryCalculator:
    def __init__(self):
        self.total = 0
        self.employees = []
    
    def add_employee(self, name, salary):
        self.total += salary
        self.employees.append({"name": name, "salary": salary})
        return self
    
    def get_average(self):
        if not self.employees:
            return 0
        return self.total / len(self.employees)

# Chainable, clean
calc = SalaryCalculator()
calc.add_employee("Aarav", 55000) \
    .add_employee("Ishita", 72000) \
    .add_employee("Kabir", 65000)

print(f"Average: ₹{calc.get_average():.2f}")

📋 Debugging Checklist:

🔍 Debugging Techniques:

# Technique 1: Check locals() and globals()
def debug_scope():
    x = 10
    print("Local variables:", locals())
    # Shows all local variables

# Technique 2: Print before problematic line
total = 100

def problematic():
    try:
        print(f"About to use total. Locals: {locals()}")
        print(total)   # May fail
        total = total + 1   # Assignment makes it local
    except UnboundLocalError as e:
        print(f"Error: {e}")

# Technique 3: dis module — see bytecode
import dis

def my_function():
    x = 10
    print(x)

dis.dis(my_function)
# Shows LOAD_FAST (local) vs LOAD_GLOBAL

# Technique 4: Explicit scope indication
def safe_function():
    # Explicitly declare intent
    global some_var
    # OR
    local_var = some_global   # Copy to local first

# Technique 5: Type hints for clarity
def calculate(total: int, amount: int) -> int:
    """Clear inputs and outputs"""
    return total + amount

# Technique 6: Use IDE features
# - PyCharm/VSCode highlight local vs global
# - Variable inspection during debugging
# - Set breakpoints before error line

# ══════════════════════════════════════
# COMMON CAUSES
# ══════════════════════════════════════

# 1. Read before assignment
count = 0
def f():
    print(count)     # ❌ UnboundLocalError
    count = 1       # Assignment makes it local

# 2. Compound assignment
counter = 0
def inc():
    counter += 1    # ❌ Same as counter = counter + 1

# 3. Conditional assignment
def get_bonus(salary):
    if salary > 70000:
        bonus = 1000
    return bonus       # ❌ Error if salary <= 70000


# ══════════════════════════════════════
# SOLUTIONS
# ══════════════════════════════════════

# Solution 1: global keyword
count = 0
def increment():
    global count
    count += 1

# Solution 2: nonlocal (closures)
def outer():
    x = 0
    def inner():
        nonlocal x
        x += 1
    return inner

# Solution 3: Pass as parameter (BEST!)
def increment(count):
    return count + 1

count = increment(count)

# Solution 4: Default value
def get_bonus(salary):
    bonus = 0          # Default
    if salary > 70000:
        bonus = 1000
    return bonus       # ✅ Always defined

# Solution 5: Return early
def get_bonus(salary):
    if salary > 70000:
        return 1000
    return 0           # Default


# ══════════════════════════════════════
# LEGB SCOPE RULE
# ══════════════════════════════════════
# L - Local (current function)
# E - Enclosing (outer function)
# G - Global (module level)
# B - Built-in (Python built-ins)


# ══════════════════════════════════════
# global vs nonlocal
# ══════════════════════════════════════

# global — module-level variable
x = 10
def f():
    global x
    x = 20

# nonlocal — enclosing function variable
def outer():
    y = 10
    def inner():
        nonlocal y
        y = 20


# ══════════════════════════════════════
# BEST PRACTICES
# ══════════════════════════════════════

# ❌ AVOID: Heavy global usage
total = 0
def add(x):
    global total
    total += x

# ✅ PREFER: Pure functions
def add(total, x):
    return total + x

# ✅ BETTER: Classes for state
class Calculator:
    def __init__(self):
        self.total = 0
    def add(self, x):
        self.total += x


# ══════════════════════════════════════
# GOLDEN RULES
# ══════════════════════════════════════
# 1. Assignment in function = local variable
# 2. Read before assign = UnboundLocalError
# 3. Use 'global' to modify globals
# 4. Use 'nonlocal' for closures
# 5. Prefer parameters over globals
# 6. Initialize variables at function start
# 7. Add default values for conditional assigns
# 8. Return early instead of unset variables
# 9. Understand LEGB scope rule
# 10. Classes better than heavy global state

Next: Data Insights Errors Fix Guide

Agle blog mein hum cover karenge: Python RecursionError — Complete Fix Guide. Maximum recursion depth exceeded error, kaise recursive functions manage karo, iterative solutions, aur real-world scenarios employee data ke saath. Errors series continues — Pandas errors sab upcoming. Data Insights par!

Happy Debugging & Keep Coding! 🚀