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: [phone]
email: [e-mail]
...

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 init

After 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 fill

It 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).
email	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).

1. This field value is in your tax resident country's currency; irs-form-filler will 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
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:

1. Foreign Earned Income Exclusion (f2555)
2. Foreign Tax Credit (f1116)

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

Keep 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: 980

Keep this record of all the previous tax years. This section will feed into next year's taxes.