{"id":4430,"library":"aquarel","title":"aquarel: Lightweight templating engine for matplotlib","description":"Aquarel is a lightweight templating engine and wrapper around Matplotlib's rcparams designed to simplify plot styling. It enables programmatic definition and JSON serialization of themes, facilitating sharing and consistent visualization across projects. Beyond standard Matplotlib stylesheets, Aquarel introduces 'transforms' for aesthetics not achievable via rcparams alone, such as trimmed axes. The library is actively maintained with frequent minor updates.","status":"active","version":"0.0.7","language":"en","source_language":"en","source_url":"https://github.com/lgienapp/aquarel","tags":["matplotlib","theming","plotting","data visualization","templates","styling","data science"],"install":[{"cmd":"pip install aquarel","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency as Aquarel acts as a styling wrapper for Matplotlib plots.","package":"matplotlib","optional":false},{"reason":"Aquarel builds on top of Matplotlib and Seaborn for enhanced data visualization capabilities.","package":"seaborn","optional":true}],"imports":[{"symbol":"load_theme","correct":"from aquarel import load_theme"}],"quickstart":{"code":"import matplotlib.pyplot as plt\nimport numpy as np\nfrom aquarel import load_theme\n\n# Define a sample plotting function\ndef create_plot():\n    fig, ax = plt.subplots(figsize=(8, 6))\n    x = np.linspace(0, 10, 100)\n    y = np.sin(x)\n    ax.plot(x, y, label='Sine Wave')\n    ax.set_title('Sample Plot')\n    ax.set_xlabel('X-axis')\n    ax.set_ylabel('Y-axis')\n    ax.legend()\n    return fig\n\n# Apply a theme using a context manager\nwith load_theme('arctic_light'):\n    fig = create_plot()\n    plt.savefig('arctic_light_plot.png')\n    # In a non-script environment (e.g., Jupyter), you might call plt.show() here if needed\n\nprint('Plot with arctic_light theme saved to arctic_light_plot.png')","lang":"python","description":"This quickstart demonstrates how to apply an Aquarel theme using a context manager. The `load_theme()` function fetches a predefined theme, which is then applied within the `with` block. All plotting commands inside this block will adopt the specified theme. Remember that `plt.savefig()` or `plt.show()` should be called *outside* the context manager if transforms are used, to ensure they are correctly applied."},"warnings":[{"fix":"Use the context manager (`with load_theme(...):`) for automatic transform application, or ensure `theme.apply_transforms()` is explicitly called after plot creation when applying themes globally.","message":"Aquarel 'transforms' (e.g., for trimming axes) must be applied after the plot objects (figure/axes) are created. While the context manager (`with load_theme(...)`) handles this automatically on exit, if applying a theme globally (`theme.apply()`), you must manually call `theme.apply_transforms()` after all plotting commands for the effects to take place.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Place `plt.show()` or `fig.savefig()` after the `with load_theme(...):` block.","message":"When using a theme with transforms via the context manager, ensure `plt.show()` or `fig.savefig()` is called *outside* the `with` block. This guarantees that transforms, which modify the finished figure, are correctly applied before rendering or saving.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `aquarel` version 0.0.6 or newer to ensure compatibility with recent Matplotlib changes and avoid deprecation warnings.","message":"Version 0.0.6 addressed an incompatibility with `MatplotlibDeprecationWarning`. Users on older `aquarel` versions might encounter issues or warnings with newer Matplotlib releases, or conversely, `aquarel` updates might require a specific Matplotlib version to resolve internal warnings.","severity":"breaking","affected_versions":"<0.0.6"},{"fix":"Understand that Aquarel's context manager provides scoped styling. For persistent global styling, `theme.apply()` can be used, but remember the implications for transforms.","message":"Unlike standard Matplotlib stylesheets that are applied once globally for the current plotting context, Aquarel aims to provide per-plot styling with temporary changes. The style applied within an Aquarel context manager is only active inside that block and reverts outside of it, which differs from how global `plt.style.use()` typically functions.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}