Dio HTTP cache interceptor with multiple stores respecting HTTP directives (or not).

HTTP directives:

Cache triggersETag
max-age (Cache-Control)
Cache freshnessDate (response date otherwise)
max-age (Cache-Control)
Cache commutatorsno-cache (Cache-Control)
no-store (Cache-Control)


  • BackupCacheStore: Combined store with primary and secondary.
  • DbCacheStore: Cache with database (Moor).
  • FileCacheStore: Cache with file system (no web support obviously).
  • HiveCacheStore: Cache using Hive package (available on all platforms).
  • MemCacheStore: Volatile cache with LRU strategy.


  • Android - iOS support: Add sqlite3_flutter_libs as dependency in your app (version 0.4.0+1 or later).
  • Desktop support: Follow Moor install documentation.
  • Web support: You must include 'sql.js' library. Follow Moor install documentation for further info.


import 'package:dio_cache_interceptor/dio_cache_interceptor.dart';

// Global options
final options = const CacheOptions(
  // A default store is required for interceptor.
  store: MemCacheStore(),
  // Default.
  policy: CachePolicy.request,
  // Optional. Returns a cached response on error but for statuses 401 & 403.
  hitCacheOnErrorExcept: [401, 403],
  // Optional. Overrides any HTTP directive to delete entry past this duration.
  maxStale: const Duration(days: 7),
  // Default. Allows 3 cache sets and ease cleanup.
  priority: CachePriority.normal,
  // Default. Body and headers encryption with your own algorithm.
  cipher: null,
  // Default. Key builder to retrieve requests.
  keyBuilder: CacheOptions.defaultCacheKeyBuilder,
  // Default. Allows to cache POST requests.
  // Overriding [keyBuilder] is strongly recommended.
  allowPostMethod: false,

// Add cache interceptor with global/default options
final dio = Dio()..interceptors.add(DioCacheInterceptor(options: options));

// ...

// Requesting with global options => status(200)
var response = await dio.get('');
// Requesting with global options => status(304)
response = await dio.get('');

// Requesting by modifying policy with refresh option
// for this single request => status(200)
response = await dio.get('',
  options: options.copyWith(policy: CachePolicy.refresh).toOptions(),


CacheOptions is widely available on interceptor and on requests to take precedence.

See documentation for all properties.


Optionally, you can encrypt body and headers with your own algorithm via CacheCipher.

Cache policy

enum CachePolicy {
  /// Forces to return the cached value if available.
  /// Requests otherwise.
  /// Caches response regardless directives.

  /// Requests regardless cache availability.
  /// Caches response regardless directives.
  /// In short, you'll save every successful GET requests.

  /// Requests and skips cache save even if
  /// response has cache directives.

  /// Requests regardless cache availability.
  /// Caches if response has cache directives.

  /// Returns the cached value if available (and un-expired).
  /// Checks against origin server otherwise and updates cache freshness
  /// with returned headers.
  /// Requests otherwise and caches if response has directives.

Features and bugs

Please file feature requests and bugs at the issue tracker.