irs-form-filler v1.0.0
irs-form-filler
irs-form-filler is a tool for filling out Internal Revenue Service (IRS) income tax forms for the 2021 tax year. Given a simple input file, this tool will generate a series of documents for filing with the IRS.
This tool was designed to file taxes for US citizens who reside abroad and file their taxes within their country of residence and need to submit their taxes to the IRS with (hopefully) $0.00 amount owed. Some companies charge substiantial amounts for filing, and this is a punative tax on US citizens living abroad.
Actually, this tool was specifically designed to file taxes for its author. Unless you fit the specific profile (i.e. married, filing separately, no dependents, etc.), then this tool may not work for you out-of-the-box. However, I am happy to accept PR that might extend the functionality of the scripts so as to support other filers, such as single filers, etc., but you have to do the work. See CONTRIBUTING.md.
This tool takes an input YAML file, with your personal and finandical details e.g.:
firstName: Joe
middleInitial: A
lastName: Bloggs
ssn: 012-34-5678
occupation: Programmer
phone: 0015551212
email: joe.bloggs@domain.com
...And fills the following IRS forms:
- f1116 - Foreign Tax Credit
- f1116 amt - Foreign Tax Credit Alternative Minimum Tax
- f1040 schedule 3 - Additional Credits and Payments
- f1040 - U.S. Individual Income Tax Return
- f6251 - Alternative Minimum Tax—Individuals
- f1040 schedule 2 - Additional Taxes
- f1040 schedule b - Interest and Ordinary Dividends
- f8938 - Statement of Specified Foreign Financial Assets (FBAR also required, but filed electronically)
Everything is done locally - no data ever leaves your machine.
Once filled you can use the e-file (if you earn $73,000 or less) and copy the values from the PDF documents to the e-file. Alternatively, you can print all the files and post them snail-mail. For more information, see US Citizens and Resident Aliens Abroad.
WARNING
Do not rely on this tool to be correct. The maintainers are developers, not tax experts. You are responsible for filing your taxes correctly, not the maintainers of irs-form-filler, and we accept no responsibility for the documents this tool produces, and make no promises as to their correctness. If you know what you are doing, then this tool can help you.
Versions
This tool is only a form filler (to the best of its ability) for the specific tax year. It has formulas for calculating individual fields and requires re-calibration every tax year because the IRS changes the forms every year. Each year, there will be a new tagged version.
- irs-2020 - Fills forms for the 2020 tax return.
- irs-2021 - Fills forms for the 2021 tax return.
- irs-2022 - Fills forms for the 2022 tax return.
How to use irs-form-filler
It is recommended to create and retain separate directories for each tax year. Use the tool to initialize a directory, populate the config.yaml file, and generate the tax documents, and then file your taxes. It is a good idea to keep backups.
Initialize a new tax year project
$ mkdir tax-2022
$ cd tax-2022
$ npx irs-form-filler initAfter running, your tax-2022 directory will be initialized with a config.yaml file, which you use to provide your financial information.
Fill out config.yaml
Edit config.yaml and fill out your information as per the Configuration sections below.
Generate tax documents
This tool uses a configuration file (e.g. config.yaml) to generate tax documents. You must fill this file with your own details before running this tool. See the Configuration section for more information.
To generate your tax documents:
$ npx irs-form-filler fillIt will write all the PDF documents to ./filled.
IRS filing deadline
You are allowed an automatic 2-month extension to file (i.e. June). See https://www.irs.gov/individuals/international-taxpayers/us-citizens-and-resident-aliens-abroad-automatic-2-month-extension-of-time-to-file.
However, you still need to file an FBAR separately (even though the US government has all the information via FATCA and your tax return - it's practically identical information). You can use the f8938 that is produced from this tool to help you file the FBAR.
Configuration
The following sections detail all the fields necessary to configure config.yaml. You should keep a backup of this file and the documents that this tool produces, because they will be needed next year.
Personal information
Edit config.yaml and update all of the following fields with your personal information.
| Field | Description |
|---|---|
| firstName | Your first name. |
| middleInitial | Your middle initial. |
| lastName | Your last name (surname). |
| ssn | Your USA social security number or equivalent. |
| occupation | Your employment occupation. |
| phone | Your phone, including 00 country code (use numbers only). |
| Your email address. | |
| address.street | The house number and street where you are tax resident. |
| address.county | The county in which you are tax resident. |
| address.city | The city in which are tax resident. |
| address.postCode | The postal code in which are tax resident. |
| address.countryCode | The country code in which are tax resident. |
| address.country | The country in which are tax resident. |
| employer.name | Your employer / company. |
| employer.usaAddress | Your employer's USA address. |
| employer.foreignAddress | Your employer's foreign address. |
Financial information
Edit config.yaml and update all of the following fields with your financial information.
| Field | Description |
|---|---|
| endOfTaxYear | The end of the tax year in MM/DD/YYYY format, e.g. 12/31/2021 |
| filingStatus | Your filing status, one of: Single | Married filing jointly | Married filing separately | Head of household | Qualifying widow(er) |
| income¹ | This is your income from wages. |
| incomeTax¹ | This is the amount of tax you paid on wages. |
| averageExchangeRate | Look up the exchange rate for on irs.gov for converting from your tax resident country's currency to USD. |
| treasuryExchangeRate | Look up the treasury exchange rate for on fiscal.treasury.gov for converting from your tax resident country's currency to USD. |
| countriesWithBankAccounts | A comma-separated list of countries for which you have bank accounts (an Schedule B and FBAR are required). |
- This field value is in your tax resident country's currency;
irs-form-fillerwill convert to USD.
Foreign bank accounts
If you hold any foreign bank accounts, you must declare them to the IRS using form f8938, but you must also submit a separate FBAR electronically. For each account you own, create an item in accounts with the following fields:
| Field | Description | |
|---|---|---|
| account | The account number/designation. | |
| type | The type of account, one of deposit | custodial. A "custodial" might be a mutual fund, or brokerage account. |
| name | The name of the financial institution. | |
| address | The financial institution's address. | |
| city | The cityfinancial institution's city. | |
| currency | The currency of the account. | |
| value | The value of the account, in the stated currency. | |
| opened | Set to true if the account was opened this year, otherwise false. | |
| closed | Set to true if the account was closed this year, otherwise false. | |
| joint | Set to true if the account is a joint account, otherwise false. | |
| tax | Set to true if the account is taxable, otherwise false. |
Carryover
As a US citizen living abroad and paying taxes in a foreign country with a bilateral tax agreement, there are two choices for how to handle the the foreign tax:
This configuration assumes #2. This tool will calculate the amount of utilized taxes, and any "excess" can accumulate credit over the tax years.
Foreign tax credit general carryover
Pay attention because it can be a little confusing. This section deals with carryover from previous years. This tax year is the year for which you are filing taxes, and previous tax year is the year prior to that.
| Field | Description |
|---|---|
| lastYearTaxCarryOverUSD | This is the cumulative total amount of tax carryover, up to the previous tax year (excluding this tax year). So, if you used this tool to generate these files for the 2021 tax year, then it is in the carryover-general.pdf file and the total value in the field Carryover to 2021. If you did not calculate carryover for the previous tax year, enter 0. |
If you used this tool to generate tax in the previous tax year, then open the previous tax year's carryover-general.pdf file, and find the row of values for the previous tax year. Then, in the carryover.general section, create a new section for the previous year's carryover, and copy the values for Foreign Taxes and Utilized and record them as follows:
general:
2019:
foreign-taxes: 10404
utilized: 980Keep this config.yaml for all previous tax years, and also keep this tax year's carryover-general.pdf as it will feed into next year's tax.
Foreign tax credit alternative minimum tax (AMT) carryover
This is similar to the Carryover section but instead deals with Alternative Minimum Tax. This is any surplus tax that paid in your tax resident country that is above what you would have paid to the USA.
Open last tax year's carryover-general.pdf file, and find the row of values for the previous tax year. Then, in the carryover.alternative-minimum-tax section, create a new section for the previous year's carryover, and copy the values for Foreign Taxes and Utilized and record them as follows:
alternative-minimum-tax:
2019:
foreign-taxes: 10404
utilized: 980Keep this record of all the previous tax years. This section will feed into next year's taxes.