# Welcome to Django-money’s documentation!

# django-money

A little Django app that uses py-moneyed to add support for Money fields in your models and forms.

- Django versions supported: 4.2, 5.0, 5.1, 5.2

- Python versions supported: 3.10, 3.11, 3.12, 3.13

- PyPy versions supported: PyPy3

If you need support for older versions of Django and Python, please refer to older releases mentioned in the release notes.

Through the dependency py-moneyed, `django-money` gets:

- Support for proper Money value handling (using the standard Money design pattern)

- A currency class and definitions for all currencies in circulation

- Formatting of most currencies with correct currency sign

## Installation

Using pip:

    $ pip install django-money

This automatically installs `py-moneyed` v1.2 (or later).

Add `djmoney` to your `INSTALLED_APPS`. This is required so that money field are displayed correctly in the admin.

    INSTALLED_APPS = [
       ...,
       'djmoney',
       ...
    ]

## Model usage

Use as normal model fields:

    from djmoney.models.fields import MoneyField
    from django.db import models

    class BankAccount(models.Model):
        balance = MoneyField(max_digits=14, decimal_places=2, default_currency='USD')

To comply with certain strict accounting or financial regulations, you may consider using `max_digits=19` and `decimal_places=4`, see more in this StackOverflow answer

It is also possible to have a nullable `MoneyField`:

    class BankAccount(models.Model):
        money = MoneyField(max_digits=10, decimal_places=2, null=True, default_currency=None)

    account = BankAccount.objects.create()
    assert account.money is None
    assert account.money_currency is None

Searching for models with money fields:

    from djmoney.money import Money

    account = BankAccount.objects.create(balance=Money(10, 'USD'))
    swissAccount = BankAccount.objects.create(balance=Money(10, 'CHF'))

    BankAccount.objects.filter(balance__gt=Money(1, 'USD'))
    # Returns the "account" object

The default currency code length is 3 but you can change it with the CURRENCY_CODE_MAX_LENGTH setting.

Caution: this setting also affects the initial migration of the exchange plugin, so changing it after running the initial migration has no effect. (You’d need to manage migrate exchange zero and migrate again if you want to change it).

## Callable defaults

Added in version 3.6.0: Callables were introduced in 3.6.0 and did not work before.

To make things configurable through project settings (especially useful for third-party applications using django-money), you can wrap configurable defaults in a callable. This avoids generating migrations on models when the defaults change!

You can define a default callable for your MoneyField defaults, both money and separate currency. Here is an example:

    from django.conf import settings
    from django.db import models
    from djmoney.models.fields import MoneyField
    from djmoney.money import Money

    def get_default_currency():
        return settings.MY_DEFAULT_CURRENCY

    def get_default_zero():
        return Money("0.00", settings.MY_DEFAULT_CURRENCY)

    class Product(models.Model):
        # The price has no default value, but a default currency is defined!
        price = MoneyField(max_digits=10, decimals=2, currency_default=get_default_currency)
        # Discount field defaults to 0 Money and thus does not need a default currency (it's in the Money
        # value supplied by get_default_zero
        discount = MoneyField(max_digits=10, decimals=2, default=get_default_zero)

Note that the supplied callables are subject to Django’s internals and the fact that they need to be serializable for the migration framework.

## Configuring currency choices

It’s possible to supply a global Django project setting for `CURRENCY_CHOICES`, but you may also supply this as an individual `currency_choices` option for MoneyFields:

    from django.conf import settings
    from django.db import models
    from djmoney.models.fields import MoneyField

    class Invoice(models.Model):
        # Allow 2 different currencies for total amount
        total_amount = MoneyField(max_digits=15, decimal_places=2, currency_choices=[("CLY", "CLY"), ("USD", "USD")])
        # Only allow 1 currency in the accounted field
        converted_amount = MoneyField(max_digits=15, decimal_places=2, currency_choices=[("CLY", "CLY")])

As with other Django Field `choices` kwargs, you can also supply a callable for `currency_choices` (but not a lambda). Please note that - similar to other `choices` fields - there are NO database constraints implied by this option, so you need may need additional validation safeguards and adding your own db constraints.

## Field validation

There are 3 different possibilities for field validation:

- by numeric part of money despite on currency;

- by single money amount;

- by multiple money amounts.

All of them could be used in a combination as is shown below:

    from django.db import models
    from djmoney.models.fields import MoneyField
    from djmoney.money import Money
    from djmoney.models.validators import MaxMoneyValidator, MinMoneyValidator

    class BankAccount(models.Model):
        balance = MoneyField(
            max_digits=10,
            decimal_places=2,
            validators=[
                MinMoneyValidator(10),
                MaxMoneyValidator(1500),
                MinMoneyValidator(Money(500, 'NOK')),
                MaxMoneyValidator(Money(900, 'NOK')),
                MinMoneyValidator({'EUR': 100, 'USD': 50}),
                MaxMoneyValidator({'EUR': 1000, 'USD': 500}),
            ]
        )

The `balance` field from the model above has the following validation:

- All input values should be between 10 and 1500 despite on currency;

- Norwegian Crowns amount (NOK) should be between 500 and 900;

- Euros should be between 100 and 1000;

- US Dollars should be between 50 and 500;

## Constructing form data

The default `ModelForm` class will use a form field (`djmoney.forms.fields.MoneyField`) that is constructed of two separate fields for amount and currency.

If you need to feed data directly to such a form (for instance if you are writing a test case), then you need to pass amount and currency like this:

    # models.py
    class Product(models.Model):
        price = MoneyField(
            max_digits=14,
            decimal_places=2,
            default_currency='EUR'
        )

    # forms.py
    class ProductForm(ModelForm):
        class Meta:
            model = Product
            fields = ["price"]

    # tests.py

    # construct the form in your test case
    form = ProductForm({'price_0': 10, 'price_1': 'EUR'})

## Adding a new Currency

Currencies are listed on moneyed, and this modules use this to provide a choice list on the admin, also for validation.

To add a new currency available on all the project, you can simply add these few lines to your `settings.py` file:

    import moneyed

    BOB = moneyed.add_currency(
        code='BOB',
        numeric='068',
        name='Peso boliviano',
        countries=('BOLIVIA', )
    )

To restrict the currencies listed on the project set a `CURRENCIES` variable with a list of Currency codes on `settings.py`

    CURRENCIES = ('USD', 'BOB')

The list has to contain valid Currency codes

Additionally there is an ability to specify currency choices directly:

    CURRENCIES = ('USD', 'EUR')
    CURRENCY_CHOICES = [('USD', 'USD $'), ('EUR', 'EUR €')]

## Important note on model managers

Django-money leaves you to use any custom model managers you like for your models, but it needs to wrap some of the methods to allow searching for models with money values.

This is done automatically for the “objects” attribute in any model that uses MoneyField. However, if you assign managers to some other attribute, you have to wrap your manager manually, like so:

    from djmoney.models.managers import money_manager

    class BankAccount(models.Model):
        balance = MoneyField(max_digits=10, decimal_places=2, default_currency='USD')
        accounts = money_manager(MyCustomManager())

Also, the money_manager wrapper only wraps the standard QuerySet methods. If you define custom QuerySet methods, that do not end up using any of the standard ones (like “get”, “filter” and so on), then you also need to manually decorate those custom methods, like so:

    from djmoney.models.managers import understands_money

    class MyCustomQuerySet(QuerySet):

       @understands_money
       def my_custom_method(*args, **kwargs):
           # Awesome stuff

## Note on serialization

Django-money provides a custom deserializer, it is not registered by default so you will have to actively register it in your `settings.py`.

    SERIALIZATION_MODULES = {"json": "djmoney.serializers"}

## Format localization

The formatting is turned on if you have set `USE_L10N = True` in the your settings file.

If formatting is disabled in the configuration, then in the templates will be used default formatting.

In the templates you can use a special tag to format the money.

In the file `settings.py` add to `INSTALLED_APPS` entry from the library `djmoney`:

    INSTALLED_APPS += ('djmoney', )

In the template, add:

    {% load djmoney %}
    ...
    {% money_localize money %}

and that is all.

Instructions to the tag `money_localize`:

    {% money_localize <money_object> [ on(default) | off ] [as var_name] %}
    {% money_localize <amount> <currency> [ on(default) | off ] [as var_name] %}

Examples:

The same effect:

    {% money_localize money_object %}
    {% money_localize money_object on %}

Assignment to a variable:

    {% money_localize money_object on as NEW_MONEY_OBJECT %}

Formatting the number with currency:

    {% money_localize '4.5' 'USD' %}

    Return::

        Money object

## Testing

Install the required packages:

    git clone https://github.com/django-money/django-money

    cd ./django-money/

    pip install -e ".[test]" # installation with required packages for testing

Recommended way to run the tests:

    tox

Testing the application in the current environment python:

    make test

## Working with Exchange Rates

To work with exchange rates, add the following to your `INSTALLED_APPS`.

    INSTALLED_APPS = [
        ...,
        'djmoney.contrib.exchange',
    ]

Also, it is required to have `certifi` installed. It could be done via installing `djmoney` with `exchange` extra:

    pip install "django-money[exchange]"

To create required relations run `python manage.py migrate`. To fill these relations with data you need to choose a data source. Currently, 2 data sources are supported - https://openexchangerates.org/ (default) and https://fixer.io/. To choose another data source set `EXCHANGE_BACKEND` settings with importable string to the backend you need:

    EXCHANGE_BACKEND = 'djmoney.contrib.exchange.backends.FixerBackend'

If you want to implement your own backend, you need to extend `djmoney.contrib.exchange.backends.base.BaseExchangeBackend`. Two data sources mentioned above are not open, so you have to specify access keys in order to use them:

`OPEN_EXCHANGE_RATES_APP_ID` - ‘<your actual key from openexchangerates.org>’

`FIXER_ACCESS_KEY` - ‘<your actual key from fixer.io>’

Backends return rates for a base currency, by default it is USD, but could be changed via `BASE_CURRENCY` setting. Open Exchanger Rates & Fixer supports some extra stuff, like historical data or restricting currencies in responses to the certain list. In order to use these features you could change default URLs for these backends:

    OPEN_EXCHANGE_RATES_URL = 'https://openexchangerates.org/api/historical/2017-01-01.json?symbols=EUR,NOK,SEK,CZK'
    FIXER_URL = 'http://data.fixer.io/api/2013-12-24?symbols=EUR,NOK,SEK,CZK'

Or, you could pass it directly to `update_rates` method:

    >>> from djmoney.contrib.exchange.backends import OpenExchangeRatesBackend
    >>> backend = OpenExchangeRatesBackend(url='https://openexchangerates.org/api/historical/2017-01-01.json')
    >>> backend.update_rates(symbols='EUR,NOK,SEK,CZK')

There is a possibility to use multiple backends in the same time:

    >>> from djmoney.contrib.exchange.backends import FixerBackend, OpenExchangeRatesBackend
    >>> from djmoney.contrib.exchange.models import get_rate
    >>> OpenExchangeRatesBackend().update_rates()
    >>> FixerBackend().update_rates()
    >>> get_rate('USD', 'EUR', backend=OpenExchangeRatesBackend.name)
    >>> get_rate('USD', 'EUR', backend=FixerBackend.name)

Regular operations with `Money` will use `EXCHANGE_BACKEND` backend to get the rates. Also, there are two management commands for updating rates and removing them:

    $ python manage.py update_rates
    Successfully updated rates from openexchangerates.org
    $ python manage.py clear_rates
    Successfully cleared rates for openexchangerates.org

Both of them accept `-b/--backend` option, that will update/clear data only for this backend. And `clear_rates` accepts `-a/--all` option, that will clear data for all backends.

To set up a periodic rates update you could use Celery task:

    CELERY_BEAT_SCHEDULE = {
        'update_rates': {
            'task': 'path.to.your.task',
            'schedule': crontab(minute=0, hour=0),
            'kwargs': {}  # For custom arguments
        }
    }

Example task implementation:

    from django.utils.module_loading import import_string

    from celery import Celery
    from djmoney import settings

    app = Celery('tasks', broker='pyamqp://guest@localhost//')

    @app.task
    def update_rates(backend=settings.EXCHANGE_BACKEND, **kwargs):
        backend = import_string(backend)()
        backend.update_rates(**kwargs)

To convert one currency to another:

    >>> from djmoney.money import Money
    >>> from djmoney.contrib.exchange.models import convert_money
    >>> convert_money(Money(100, 'EUR'), 'USD')
    <Money: 122.8184375038380800 USD>

Exchange rates are integrated with Django Admin.

django-money can be configured to automatically use this app for currency conversions by settings `AUTO_CONVERT_MONEY = True` in your Django settings. Note that currency conversion is a lossy process, so automatic conversion is usually a good strategy only for very simple use cases. For most use cases you will need to be clear about exactly when currency conversion occurs, and automatic conversion can hide bugs. Also, with automatic conversion you lose some properties like commutativity (`A + B == B + A`) due to conversions happening in different directions.

## Usage with Django REST Framework

Make sure that `djmoney` and is in the `INSTALLED_APPS` of your `settings.py` and that `rest_framework` has been installed. MoneyField will automatically register a serializer for Django REST Framework through `djmoney.apps.MoneyConfig.ready()`.

You can add a serializable field the following way:

    from djmoney.contrib.django_rest_framework import MoneyField

    class Serializers(serializers.Serializer):
        my_computed_prop = MoneyField(max_digits=10, decimal_places=2)

Built-in serializer works in the following way:

    class Expenses(models.Model):
        amount = MoneyField(max_digits=10, decimal_places=2)

    class Serializer(serializers.ModelSerializer):
        class Meta:
            model = Expenses
            fields = '__all__'

    >>> instance = Expenses.objects.create(amount=Money(10, 'EUR'))
    >>> serializer = Serializer(instance=instance)
    >>> serializer.data
    ReturnDict([
        ('id', 1),
        ('amount_currency', 'EUR'),
        ('amount', '10.000'),
    ])

Note that when specifying individual fields on your serializer, the amount and currency fields are treated separately. To achieve the same behaviour as above you would include both field names:

    class Serializer(serializers.ModelSerializer):
        class Meta:
            model = Expenses
            fields = ('id', 'amount', 'amount_currency')

## Customization

If there is a need to customize the process deconstructing `Money` instances onto Django Fields and the other way around, then it is possible to use a custom descriptor like this one:

    class MyMoneyDescriptor:

        def __get__(self, obj, type=None):
            amount = obj.__dict__[self.field.name]
            return Money(amount, "EUR")

It will always use `EUR` for all `Money` instances when `obj.money` is called. Then it should be passed to `MoneyField`:

    class Expenses(models.Model):
        amount = MoneyField(max_digits=10, decimal_places=2, money_descriptor_class=MyMoneyDescriptor)

## Background

This project is a fork of the Django support that was in http://code.google.com/p/python-money/

This version adds tests, and comes with several critical bugfixes.

# Contents

- Changelog
  - Unreleased
  - 3.6.1 - 2026-06-07
  - 3.6 - 2026-01-27
  - 3.5.4 - 2025-04-17
  - 3.5.3 - 2024-08-01
  - 3.5.2 - 2024-05-07
  - 3.5.1 - 2024-05-05
  - 3.5 - 2024-05-04
  - 3.4.1 - 2023-11-30
  - 3.4 - 2023-10-17
  - 3.3 - 2023-09-10
  - 3.2 - 2023-07-03
  - 3.1 - 2023-04-20
  - 3.0 - 2022-06-20
  - 2.1.1 - 2022-01-02
  - 2.1 - 2021-09-17
  - 2.0.3 - 2021-09-04
  - 2.0.2 - 2021-09-04
  - 2.0.1 - 2021-07-09
  - 2.0 - 2021-05-23
  - 1.3.1 - 2021-02-04
  - 1.3 - 2021-01-10
  - 1.2.2 - 2020-12-29
  - 1.2.1 - 2020-11-29
  - 1.2 - 2020-11-26
  - 1.1 - 2020-04-06
  - 1.0 - 2019-11-08
  - 0.15.1 - 2019-06-22
  - 0.15 - 2019-05-30
  - 0.14.4 - 2019-01-07
  - 0.14.3 - 2018-08-14
  - 0.14.2 - 2018-07-23
  - 0.14.1 - 2018-07-17
  - 0.14 - 2018-06-09
  - 0.13.5 - 2018-05-19
  - 0.13.4 - 2018-05-19
  - 0.13.3 - 2018-05-12
  - 0.13.2 - 2018-04-16
  - 0.13.1 - 2018-04-07
  - 0.13 - 2018-04-07
  - 0.12.3 - 2017-12-13
  - 0.12.2 - 2017-12-12
  - 0.12.1 - 2017-11-20
  - 0.12 - 2017-10-22
  - 0.11.4 - 2017-06-26
  - 0.11.3 - 2017-06-19
  - 0.11.2 - 2017-05-31
  - 0.11.1 - 2017-05-26
  - 0.11 - 2017-05-19
  - 0.10.2 - 2017-02-18
  - 0.10.1 - 2016-12-26
  - 0.10 - 2016-12-19
  - 0.9.1 - 2016-08-01
  - 0.9.0 - 2016-07-31
  - 0.8 - 2016-04-23
  - 0.7.6 - 2016-01-08
  - 0.7.5 - 2015-12-22
  - 0.7.4 - 2015-11-02
  - 0.7.3 - 2015-10-16
  - 0.7.2 - 2015-09-01
  - 0.7.1 - 2015-08-11
  - 0.7.0 - 2015-06-14
  - 0.6.0 - 2015-05-23
  - 0.5.0 - 2014-12-15
  - 0.4.2 - 2014-07-31
  - 0.4.1 - 2013-11-28
  - 0.4.0.0 - 2013-11-26
  - 0.3.4 - 2013-11-25
  - 0.3.3.2 - 2013-10-31
  - 0.3.3.1 - 2013-10-01
  - 0.3.3 - 2013-02-17
  - 0.3.2 - 2012-11-30
  - 0.3.1 - 2012-10-11
  - 0.3 - 2012-09-30
  - 0.2 - 2012-04-10
- Contributing to Django money
  - Quickstart
  - Syntax and conventions
  - Running the tests
  - Report bugs
- Settings
  - DEFAULT_CURRENCY

# Indices and tables

- Index

- Module Index

- Search Page