{"id":40376481,"url":"https://github.com/maximbilan/spain-tax","last_synced_at":"2026-01-20T11:35:47.843Z","repository":{"id":331651776,"uuid":"1131646439","full_name":"maximbilan/spain-tax","owner":"maximbilan","description":"Spain Tax Calculator","archived":false,"fork":false,"pushed_at":"2026-01-10T18:18:08.000Z","size":56,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T04:34:35.509Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximbilan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-10T12:29:22.000Z","updated_at":"2026-01-10T18:18:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maximbilan/spain-tax","commit_stats":null,"previous_names":["maximbilan/spain-tax"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/maximbilan/spain-tax","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fspain-tax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fspain-tax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fspain-tax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fspain-tax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximbilan","download_url":"https://codeload.github.com/maximbilan/spain-tax/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fspain-tax/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28602507,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T10:46:13.255Z","status":"ssl_error","status_checked_at":"2026-01-20T10:42:51.865Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-20T11:35:47.140Z","updated_at":"2026-01-20T11:35:47.838Z","avatar_url":"https://github.com/maximbilan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spain Tax Calculator 🇪🇸\n\nA comprehensive command-line tool for calculating Spanish personal income tax (IRPF) and Social Security contributions. This calculator supports all major tax scenarios including regional variations, dependent allowances, age-based adjustments, and special tax regimes like Beckham Law.\n\n## Features\n\n- **Complete Tax Calculation**: Calculates both IRPF (personal income tax) and Social Security contributions\n- **Regional Support**: Supports all major Spanish regions with their specific tax brackets\n- **Dependent Allowances**: Full support for children, ascendants, disabilities, and family situations\n- **Age-Based Adjustments**: Automatic personal allowance adjustments based on taxpayer age\n- **Beckham Law**: Special tax regime for foreign workers (24% flat rate up to €600k)\n- **Beautiful Output**: Color-coded, aligned output with detailed breakdowns\n- **Flexible Input**: Support for annual or monthly income input\n\n## Screenshots\n\n```\n./run.sh 120000 --age 35 --children-under-3 1 --children-3-plus 2 --ascendants-65 2 --region valencia --verbose\n```\n\n\u003cimg width=\"567\" height=\"848\" alt=\"Screenshot 2026-01-10 at 16 32 52\" src=\"https://github.com/user-attachments/assets/311690b5-dec3-4492-b989-7641f3e7548a\" /\u003e\n\n## Installation\n\n### Prerequisites\n\n- Python 3.7 or higher\n- Bash shell (for the setup script)\n\n### Quick Start\n\n1. Clone or download this repository\n2. Make the shell script executable (if needed):\n   ```bash\n   chmod +x run.sh\n   ```\n3. Run the calculator:\n   ```bash\n   ./run.sh 60000\n   ```\n\nThe script will automatically:\n- Create a Python virtual environment\n- Run the calculator\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Calculate tax for €60,000 annual income\n./run.sh 60000\n\n# Or run directly with Python\npython3 tax_calculator.py 60000\n```\n\n### Common Examples\n\n```bash\n# With region (Valencia)\n./run.sh 60000 --region valencia\n\n# With dependents (2 children: one under 3, one older)\n./run.sh 60000 --children-under-3 1 --children-3-plus 1 --region valencia\n\n# With detailed breakdown\n./run.sh 60000 --region madrid --verbose\n\n# Monthly income input\n./run.sh 5000 --monthly --region catalonia\n\n# Age-based personal allowance (65+)\n./run.sh 60000 --age 68\n\n# Beckham Law (24% flat rate)\n./run.sh 100000 --beckham-law\n\n# Autónomo (self-employed) examples:\n./run.sh 60000 --autonomo --region madrid\n./run.sh 60000 --autonomo --months-as-autonomo 6  # New autónomo (reduced rate)\n./run.sh 60000 --autonomo --contribution-base 40000  # Custom contribution base\n\n# Show IRPF rates by region\npython3 tax_calculator.py --show-regions\n```\n\n## Command Line Options\n\n### Income Options\n\n- `income` (required unless `--show-regions` is used): Annual income in euros (or monthly if `--monthly` is used)\n- `--monthly`: Treat income as monthly instead of annual\n\n### Tax Calculation Options\n\n- `--region REGION`: Spanish region for regional IRPF tax\n  - Options: `madrid`, `catalonia`, `andalusia`, `valencia`, `basque`, `galicia`, `castilla_leon`, `canary_islands`, `none`\n  - Default: `none` (state tax only)\n\n- `--beckham-law`: Apply Beckham Law (24% flat rate on income up to €600,000)\n  - Income above €600k is taxed at normal progressive rates\n  - Regional tax does not apply under Beckham Law\n\n- `--allowance AMOUNT`: Custom personal allowance amount (overrides age-based calculation)\n  - Default: €5,550 (or age-based if `--age` is provided)\n\n- `--age AGE`: Taxpayer age in years (affects personal allowance)\n  - Under 65: €5,550\n  - 65-74: €6,700\n  - 75+: €8,100\n\n- `--ss-rate RATE`: Social Security rate as decimal (for employees only)\n  - Default: 0.0635 (6.35%)\n\n- `--autonomo`: Calculate for autónomo (self-employed) instead of employee\n  - Uses contribution base system instead of percentage of income\n  - See \"Autónomo Mode\" section below for details\n\n- `--contribution-base AMOUNT`: Annual contribution base for autónomos\n  - If not provided, estimated as 75% of income (clamped to €12,000-€56,400 annually)\n  - Must be between €12,000 and €56,400 annually\n\n- `--months-as-autonomo N`: Number of months as autónomo (for reduced rates)\n  - 1-12 months: €80/month flat rate\n  - 13-24 months: €160/month flat rate\n  - 25+ months: Full rate (30% of contribution base)\n  - If not specified, uses full rate\n\n### Dependent Options\n\n#### Children\n\n- `--children-under-3 N`: Number of children under 3 years old\n  - Base allowance: €2,400 (first), €2,700 (second), €4,000 (third), €4,500 (fourth+)\n  - Additional: €2,800 per child under 3\n\n- `--children-3-plus N`: Number of children 3 years old or older\n  - Base allowance: €2,400 (first), €2,700 (second), €4,000 (third), €4,500 (fourth+)\n\n- `--children-disability-33 N`: Number of children with 33%+ disability\n  - Additional allowance: €3,000 per child\n\n- `--children-disability-65 N`: Number of children with 65%+ disability\n  - Additional allowance: €12,000 per child\n\n#### Ascendants (Elderly Parents/Grandparents)\n\n- `--ascendants-65 N`: Number of ascendants over 65 years old\n  - Allowance: €1,150 per ascendant\n\n- `--ascendants-disability-33 N`: Number of ascendants with 33%+ disability\n  - Allowance: €3,000 per ascendant\n\n- `--ascendants-disability-65 N`: Number of ascendants with 65%+ disability\n  - Allowance: €12,000 per ascendant\n\n#### Family Status\n\n- `--large-family`: General large family status\n  - Allowance: €2,400\n\n- `--large-family-special`: Special large family (5+ children or 4+ with disability)\n  - Allowance: €4,800\n\n- `--single-parent`: Single parent family status\n  - Allowance: €2,100\n\n#### Taxpayer Disability\n\n- `--taxpayer-disability-33`: Taxpayer has 33%+ disability\n  - Allowance: €3,000\n\n- `--taxpayer-disability-65`: Taxpayer has 65%+ disability\n  - Allowance: €12,000\n\n- `--taxpayer-disability-mobility`: Taxpayer has mobility disability\n  - Allowance: €3,000\n\n- `--taxpayer-disability-dependency`: Taxpayer requires assistance\n  - Allowance: €12,000\n\n### Output Options\n\n- `--verbose` or `-v`: Show detailed tax bracket breakdown\n- `--show-regions`: Display IRPF tax rates by region and exit (income argument not required)\n  - Shows state IRPF rates (applies to all regions)\n  - Shows regional IRPF rates for each region\n  - Displays total rates (State + Regional) for easy comparison\n  - Useful for comparing tax rates across different Spanish regions\n\n## How It Works\n\n### Calculation Flow\n\n1. **Social Security Calculation**\n   - Deducted from gross income: 6.35% (default, configurable)\n   - This includes healthcare, unemployment, and pension contributions\n\n2. **Allowance Calculation**\n   - Personal allowance (age-based or custom)\n   - Dependent allowances (children, ascendants, disabilities, family status)\n   - Total allowances = Personal + Dependent allowances\n\n3. **Taxable Income**\n   - Taxable income = Income after Social Security - Total allowances\n\n4. **IRPF Tax Calculation**\n   - **State IRPF**: Progressive brackets (19%-47%)\n   - **Regional IRPF**: Additional progressive brackets (varies by region, 8%-15%)\n   - **Total IRPF** = State IRPF + Regional IRPF\n   - **Beckham Law**: 24% flat rate on income up to €600k (if applicable)\n\n5. **Net Income**\n   - Net income = Gross income - Social Security - IRPF tax\n\n### Tax Brackets (2024)\n\n#### State IRPF Brackets\n- €0 - €12,450: 19%\n- €12,450 - €20,200: 24%\n- €20,200 - €35,200: 30%\n- €35,200 - €60,000: 37%\n- €60,000 - €300,000: 45%\n- Over €300,000: 47%\n\n#### Regional IRPF (Examples)\n- **Madrid**: 9%-14% (lower rates)\n- **Catalonia**: 10%-15%\n- **Valencia**: 10%-15%\n- **Canary Islands**: 8%-13% (lowest rates)\n\n### Social Security\n\n#### Employee Mode (Default)\n- **Rate**: 6.35% of gross income (national, same across all regions)\n- **Includes**: Healthcare, unemployment benefits, pension contributions, professional training\n- **Coverage**: You and your dependents (spouse and children) are automatically covered\n\n#### Autónomo Mode (Self-Employed)\n- **System**: Based on contribution base (base de cotización), not percentage of income\n- **Contribution Base**: Choose between €1,000-€4,700/month (default: estimated as 75% of income)\n- **Full Rate**: 30% of contribution base (after 24 months)\n- **Reduced Rates for New Autónomos**:\n  - First 12 months: €80/month flat rate\n  - Months 13-24: €160/month flat rate\n  - After 24 months: Full rate (30% of contribution base)\n- **Includes**: Healthcare, unemployment benefits, pension contributions, professional training, cessation of activity\n- **Coverage**: You and your dependents (spouse and children) are automatically covered\n\n**Note**: The calculator defaults to employee mode. Use `--autonomo` flag to calculate for self-employed.\n\n## Example Calculations\n\n### Example 1: Single Person, €60,000, Madrid\n\n```bash\n./run.sh 60000 --region madrid\n```\n\n**Result:**\n- Social Security: €3,810 (6.35%)\n- State IRPF: €14,438.30\n- Regional IRPF (Madrid): €5,398.30\n- Total Tax: €23,646.60\n- Net Income: €36,353.40\n- Effective Rate: 39.41%\n\n### Example 2: Family with 2 Children, €60,000, Valencia\n\n```bash\n./run.sh 60000 --children-under-3 1 --children-3-plus 1 --region valencia\n```\n\n**Result:**\n- Social Security: €3,810 (6.35%)\n- Dependent Allowances: €7,900\n  - First child: €2,400\n  - Second child (under 3): €2,700 + €2,800 (under 3 bonus) = €5,500\n- State IRPF: €11,515.30\n- Regional IRPF (Valencia): €4,877.70\n- Total Tax: €20,203.00\n- Net Income: €39,797.00\n- Effective Rate: 33.67%\n\n### Example 3: High Earner with Beckham Law, €700,000\n\n```bash\n./run.sh 700000 --beckham-law --verbose\n```\n\n**Result:**\n- First €600k: 24% = €144,000\n- Excess €55,550: Progressive rates = €16,255\n- Total IRPF: €160,255\n- Effective Rate: 29.24%\n\n## Understanding the Output\n\nThe calculator provides:\n\n1. **Summary Section**\n   - Gross income\n   - Social Security deduction\n   - Income after Social Security\n   - Personal and dependent allowances\n   - Taxable income\n   - State and regional IRPF taxes\n   - Total deductions\n   - Net income\n   - Effective tax rate\n\n2. **Detailed Breakdown** (with `--verbose`)\n   - Tax bracket-by-bracket breakdown\n   - Shows how much income falls in each bracket\n   - Shows tax amount for each bracket\n\n3. **Monthly Breakdown**\n   - All amounts converted to monthly figures\n   - Useful for budgeting\n\n4. **Regional Rates Comparison** (with `--show-regions`)\n   - Complete breakdown of IRPF rates by region\n   - Shows state rates, regional rates, and total combined rates\n   - Helps compare tax rates across different Spanish regions\n\n## Important Notes\n\n### Social Security\n- **National Rate**: 6.35% is the same across all regions\n- **Includes Healthcare**: No separate payment needed for government medical insurance\n- **Coverage**: Automatic coverage for you and dependents\n\n### Personal Allowance\n- **Age-Based**: Automatically adjusts if you provide `--age`\n- **Default**: €5,550 (under 65)\n- **65-74**: €6,700\n- **75+**: €8,100\n\n### Regional Taxes\n- Regional IRPF is **in addition to** state IRPF\n- Total IRPF = State + Regional\n- Some regions (like Madrid) have lower rates\n- Canary Islands has the lowest regional rates\n- Use `--show-regions` to view all regional tax rates at a glance\n\n### Beckham Law\n- Only applies to eligible foreign workers\n- 24% flat rate on income up to €600,000\n- Income above €600k taxed at normal progressive rates\n- No regional tax under Beckham Law\n- No personal allowance under Beckham Law\n\n## Limitations\n\n- Tax brackets are based on 2024 rates (may need updates for future years)\n- Does not account for all possible deductions and credits\n- Does not handle joint filing for married couples (calculates individual only)\n- Contribution base limits for Social Security are not implemented\n- Some regional variations may not be fully captured\n\n## Contributing\n\nFeel free to submit issues or pull requests to improve the calculator.\n\n## License\n\nThis project is provided as-is for educational and personal use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximbilan%2Fspain-tax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximbilan%2Fspain-tax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximbilan%2Fspain-tax/lists"}