OpenFisca Country-Template

This repository helps you quickly set up and use your own OpenFisca country package.

You should NOT fork it but follow the set up instructions below.

Otherwise, you will have to clean up all tags when you deploy your own country package.

Setting up your Country Package

This set of instructions only needs to be followed once and will create your own copy of this boilerplate directory, customising it to the country you want to work on. You will need to have Git installed.

Using GitHub (recommended for GitHub users)

Click on the “Use this template” dropdown and select “Create a new repository”.
Set the repository name to openfisca-<your_country_name>; use underscore _ as separator if there are spaces in the country name. For example, openfisca-new_zealand or openfisca-france.
After being redirected to your newly created repository, please allow a few minutes for the automatic setup to be executed. Once done, the title of the README file should be updated to OpenFisca <your_country_name>.

If the automatic setup does not start within a few minutes, you can initiate it manually:

Navigate to the “Actions” tab.

Select the “First time setup” workflow.

Click on “Run workflow” to start the setup process manually.

Follow the instructions in the new repository's README.md.

Manual setup (recommended for users of other Git hosts)

Download a copy of this repository, unzip it and cd into it in a Terminal window.
Create a new repository on your favourite git host (Bitbucket, GitLab, …) with the name openfisca-<your_country_name>. For example, openfisca-new_zealand or openfisca-france.
Execute the first-time-setup.sh script to initialise the git repository. This performs numerous tasks including replacing all references to openfisca-country_template with references to the new country package.
- To execute the script run bash first-time-setup.sh from the command line
- After the first-time-setup.sh has run both it and these instructions are removed.
Follow the instructions in the new repository's README.md.

Writing the Legislation

The country whose law is modelled here has a very simple tax and benefit system.

It has a flat rate tax whose rates increase every year.
On the first of December, 2015, it introduced a basic income for all its citizens of age who have no income.
On the first of December, 2016, it removed the income condition, providing all its adult citizens with a basic income.

These elements are described in different folders. All the modelling happens within the openfisca_country_template folder.

The rates are in the parameters folder.
The formulas are in the variables folder.
This country package comes also with reforms in the reforms folder. This is optional: your country may exist without defining any reform.
- In this country, there is a reform project aiming to modify the social security taxation, deleting the first bracket, raising the intermediary ones and adding a new bracket with a higher tax rate of 40 % for people earning more than 40000. This reform project would apply starting from 2017-01-01.

The files that are outside from the openfisca_country_template folder are used to set up the development environment.

Packaging your Country Package for Distribution

Country packages are Python distributions. You can choose to distribute your package automatically via the predefined continuous deployment system on GitHub Actions, or manually.

Automatic continuous deployment on GitHub

This repository is configured with a continuous deployment system to automate the distribution of your package via pip.

Setting up continuous deployment

To activate the continuous deployment:

Create an account on PyPI if you don't already have one.
Generate a token in your PyPI account. This token will allow GitHub Actions to securely upload new versions of your package to PyPI.
Add this token to your GitHub repository's secrets under the name PYPI_TOKEN.

Once set up, changes to the main branch will trigger an automated workflow to build and publish your package to PyPI, making it available for pip installation.

Manual distribution

If you prefer to manually manage the release and distribution of your package, follow the guidelines provided by the Python Packaging Authority.

This involves detailed steps on preparing your package, creating distribution files, and uploading them to PyPI.

Install Instructions for Users and Contributors

This package requires Python 3.11. More recent versions should work, but are not tested.

All platforms that can execute Python are supported, which includes GNU/Linux, macOS and Microsoft Windows.

A. Minimal Installation

Follow this installation if you wish to:

run calculations on a large population;
create tax & benefits simulations;
write an extension to this legislation (e.g. city specific tax & benefits);
serve your Country Package with the OpenFisca Web API.

For more advanced uses, head to the Advanced Installation.

Install this Country Package with uv

Install the Country Package:

uv add install openfisca-country_template

🎉 This OpenFisca Country Package is now installed and ready!

Next Steps

To learn how to use OpenFisca, follow our tutorials.
To serve this Country Package, serve the OpenFisca Web API.

Depending on what you want to do with OpenFisca, you may want to install yet other packages:

To install extensions or write on top of this Country Package, head to the Extensions documentation.
To plot simulation results, try matplotlib.
To manage data, check out pandas.

B. Advanced Installation (Git Clone)

Follow this tutorial if you wish to:

create or change this Country Package's legislation;
contribute to the source code.

Clone this Country Package with Git

First, make sure Git is installed on your machine.

Set your working directory to the location where you want this OpenFisca Country Package cloned.

Clone this Country Package on your machine:

git clone https://example.com/repository.git
cd repository_folder

You can make sure that everything is working by running the provided tests with make test.

Learn more about tests

🎉 This OpenFisca Country Package is now installed and ready!

Next Steps

To write new legislation, read the Coding the legislation section to know how to write legislation.
To contribute to the code, read our Contribution Guidebook.

C. Contributing

Read CONTRIBUTING.
Open a pull request to the main branch of this repository.
Announce your changes as described in CONTRIBUTING.

Serve this Country Package with the OpenFisca Web API

If you are considering building a web application, you can use the packaged OpenFisca Web API with your Country Package.

To serve the Openfisca Web API locally, run:

openfisca serve --port 5000 --country-package openfisca_country_template

Or use the quick-start Make command:

make serve-local

To read more about the openfisca serve command, check out its documentation.

You can make sure that your instance of the API is working by requesting:

curl "http://localhost:5000/spec"

This endpoint returns the Open API specification of your API.

🎉 This OpenFisca Country Package is now served by the OpenFisca Web API! To learn more, go to the OpenFisca Web API documentation.

You can test your new Web API by sending it example JSON data located in the situation_examples folder.

curl -X POST -H "Content-Type: application/json" \
  -d @./openfisca_country_template/situation_examples/couple.json \
  http://localhost:5000/calculate

Release files for openfisca-country_template 8.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openfisca-country_template 8.0.4
File	Size	Uploaded
openfisca_country_template-8.0.4.tar.gz	137.9 kB	Sep 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for openfisca-country_template 8.0.4
File	Interpreter	ABI	Platform	Reset
openfisca_country_template-8.0.4-py3-none-any.whl 45.2 kB Sep 17, 2026	Python 3	none	any	Details

Total release size: 183.2 kB

Release files / openfisca_country_template-8.0.4.tar.gz

Download URL	openfisca_country_template-8.0.4.tar.gz
Size	137.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`22655819a651732d6ec04ea376024dee1f092b31e958e95866719045f5aa5bbe`
BLAKE2b-256 checksum How to use checksums	`ffcb021b36e588174bcac0ef9d09550346a1099c22bc570798534299a4e81c58`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / openfisca_country_template-8.0.4-py3-none-any.whl

Download URL	openfisca_country_template-8.0.4-py3-none-any.whl
Size	45.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a4c625bbd55aee957b0600c93ea6a09c49f8392ef4421b40ea17d1a34cafe186`
BLAKE2b-256 checksum How to use checksums	`ae754f2a098c4f39ec7f65fb3d46bd37d4a4859d8d7c3073559b6df6b49a1a82`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`