{"id":5189,"library":"django-money","title":"Django Money","description":"Django Money is a little Django app that integrates the `py-moneyed` library to add robust support for money and currency fields in Django models and forms. It ensures accurate handling of monetary values, currency conversions, and formatting. The current version, 3.6.0, supports modern Django and Python versions and is actively maintained with regular releases.","status":"active","version":"3.6.0","language":"en","source_language":"en","source_url":"https://github.com/django-money/django-money","tags":["django","money","currency","financial","localization","orm"],"install":[{"cmd":"pip install django-money","lang":"bash","label":"Install core library"},{"cmd":"pip install \"django-money[exchange]\"","lang":"bash","label":"Install with exchange rate support"}],"dependencies":[{"reason":"Provides the core Money object and currency handling. Automatically installed as a dependency.","package":"py-moneyed","optional":false},{"reason":"Required for the `exchange` optional dependency for secure SSL connections to exchange rate APIs.","package":"certifi","optional":true}],"imports":[{"symbol":"MoneyField","correct":"from djmoney.models.fields import MoneyField"},{"note":"While `moneyed.Money` is the underlying class, `djmoney.money.Money` is the recommended import for consistency within the `django-money` ecosystem and for potential future abstractions.","wrong":"from moneyed import Money","symbol":"Money","correct":"from djmoney.money import Money"},{"note":"Used to wrap custom model managers to ensure proper searching for money values.","symbol":"money_manager","correct":"from djmoney.models.managers import money_manager"},{"note":"A convenient validator for ensuring a MoneyField is not zero.","symbol":"money_is_not_zero","correct":"from djmoney.models.validators import money_is_not_zero"},{"note":"Loads the template tags, including `money_localize` for formatting Money objects in templates.","symbol":"money_localize (template tag)","correct":"{% load djmoney %}"}],"quickstart":{"code":"import os\nimport django\nfrom django.conf import settings\nfrom django.db import models\n\nsettings.configure(\n    INSTALLED_APPS=[\n        'djmoney',\n        'tests',\n    ],\n    DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}},\n    DEFAULT_CURRENCY='USD',\n    USE_L10N=True, # Enable localization for formatting\n)\ndjango.setup()\n\nfrom djmoney.models.fields import MoneyField\nfrom djmoney.money import Money\n\nclass BankAccount(models.Model):\n    balance = MoneyField(max_digits=14, decimal_places=2, default_currency='USD')\n    # It's also possible to have a nullable MoneyField:\n    # money = MoneyField(max_digits=10, decimal_places=2, null=True, default_currency=None)\n\n    def __str__(self):\n        return f\"{self.balance} - {self.pk}\"\n\n# Run migrations (simplified for quickstart)\nwith open(os.devnull, 'w') as f:\n    import sys\n    _stdout = sys.stdout\n    sys.stdout = f\n    try:\n        from django.core.management import call_command\n        call_command('makemigrations', 'tests', verbosity=0, interactive=False)\n        call_command('migrate', verbosity=0, interactive=False)\n    finally:\n        sys.stdout = _stdout\n\n# Create an account\naccount = BankAccount.objects.create(balance=Money(100, 'USD'))\nprint(f\"Created account: {account}\")\n\n# Querying\nexpensive_accounts = BankAccount.objects.filter(balance__gt=Money(50, 'USD'))\nprint(f\"Accounts with balance > $50: {list(expensive_accounts)}\")\n\n# Accessing amount and currency separately\nprint(f\"Account balance amount: {account.balance.amount}\")\nprint(f\"Account balance currency: {account.balance.currency}\")\n\n# Example of template tag usage (conceptual, as this is a console quickstart)\n# In a Django template:\n# {% load djmoney %}\n# <p>Current balance: {{ account.balance|money_localize }}</p>","lang":"python","description":"This quickstart demonstrates how to define a `MoneyField` in a Django model, create instances with `Money` objects, and perform basic queries. It also highlights the required `INSTALLED_APPS` entry and the use of localization settings for proper display. The template tag `money_localize` is conceptually shown for front-end rendering."},"warnings":[{"fix":"Review the official changelog and documentation for your specific upgrade path. Replace removed settings and update import paths (e.g., use `djmoney.money.Money` instead of `moneyed.Money`). Ensure your Django and Python versions meet the minimum requirements for `django-money` 3.x (Python >=3.7, Django 2.2, 3.2, 4.0, 4.1, 4.2 supported by 3.6.0).","message":"When upgrading to `django-money` 3.x from older versions (e.g., 2.x or 0.x), several features have been removed or renamed. Specifically, `Money.decimal_places_display` and `CURRENCY_DECIMAL_PLACES_DISPLAY` settings were removed in version 3.0. Additionally, support for older Python (2.6, 3.2) and Django (1.4-1.7, 1.9, 2.2, 3.0, 3.1, 4.0) versions has been dropped in various 3.x releases.","severity":"breaking","affected_versions":"<3.0"},{"fix":"Update all instances of `from moneyed import Money` to `from djmoney.money import Money`. Remove any usage of `MoneyPatched`.","message":"The import path `from moneyed import Money` has been deprecated in favor of `from djmoney.money import Money`. Similarly, `djmoney.models.fields.MoneyPatched` was deprecated.","severity":"deprecated","affected_versions":"0.12, 3.0"},{"fix":"Perform all monetary operations using `Money` objects, which internally rely on `Decimal`. For direct arithmetic with amounts, ensure you convert to `Decimal` first if not already a `Money` object.","message":"For money calculations, always use Python's `Decimal` type via `djmoney.money.Money` objects instead of floating-point numbers (`float`). Floats can introduce precision errors crucial for financial data.","severity":"gotcha","affected_versions":"All"},{"fix":"Add `'djmoney'` to `INSTALLED_APPS` and `USE_L10N = True` in your Django `settings.py` file.","message":"To ensure money fields are correctly displayed and integrated with Django's admin and localization features, you must add `'djmoney'` to your `INSTALLED_APPS` in `settings.py` and set `USE_L10N = True` for localization-aware formatting.","severity":"gotcha","affected_versions":"All"},{"fix":"Wrap your custom manager: `objects = money_manager(MyCustomManager())`.","message":"When working with custom model managers on models containing `MoneyField`, you need to explicitly wrap your manager using `djmoney.models.managers.money_manager` to enable proper filtering and querying based on money values.","severity":"gotcha","affected_versions":"All"},{"fix":"Prefer ORM operations with `Money` objects. If direct database column access is needed, use the automatically generated `fieldname_amount` and `fieldname_currency` columns.","message":"The `MoneyField` internally stores two values (`amount` and `currency`). While ORM queries generally work with the `Money` object, direct database interactions or complex custom queries might require referencing the underlying `_amount` and `_currency` fields (e.g., `myfield_amount`, `myfield_currency`).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}