Skip to main content
Open Spaced Repetition logo

Py-FSRS

🧠🔄 Build your own Spaced Repetition System in Python 🧠🔄


Py-FSRS is a python package that allows developers to easily create their own spaced repetition system using the Free Spaced Repetition Scheduler algorithm.

Table of Contents

Installation

You can install the fsrs python package from PyPI using pip:

pip install fsrs

Quickstart

Import and initialize the FSRS scheduler

from fsrs import Scheduler, Card, Rating, ReviewLog

scheduler = Scheduler()

Create a new Card object

# NOTE: all new cards are due immediately upon creation
card = Card()

Choose a rating and review the card with the scheduler

# Rating.Again (==1) forgot the card
# Rating.Hard (==2) remembered the card with serious difficulty
# Rating.Good (==3) remembered the card after a hesitation
# Rating.Easy (==4) remembered the card easily

rating = Rating.Good

card, review_log = scheduler.review_card(card, rating)

print(f"Card rated {review_log.rating} at {review_log.review_datetime}")
# > Card rated 3 at 2024-11-30 17:46:58.856497+00:00

See when the card is due next

from datetime import datetime, timezone

due = card.due

# how much time between when the card is due and now
time_delta = due - datetime.now(timezone.utc)

print(f"Card due on {due}")
print(f"Card due in {time_delta.seconds} seconds")

# > Card due on 2024-11-30 18:42:36.070712+00:00
# > Card due in 599 seconds

Usage

Custom parameters

You can initialize the FSRS scheduler with your own custom parameters.

from datetime import timedelta

# NOTE: the following arguments are also the defaults
scheduler = Scheduler(
    parameters = (
            0.212,
            1.2931,
            2.3065,
            8.2956,
            6.4133,
            0.8334,
            3.0194,
            0.001,
            1.8722,
            0.1666,
            0.796,
            1.4835,
            0.0614,
            0.2629,
            1.6483,
            0.6014,
            1.8729,
            0.5425,
            0.0912,
            0.0658,
            0.1542,
    ),
    desired_retention = 0.9,
    learning_steps = (timedelta(minutes=1), timedelta(minutes=10)),
    relearning_steps = (timedelta(minutes=10),),
    maximum_interval = 36500,
    enable_fuzzing = True
)

Explanation of parameters

parameters are a set of 21 model weights that affect how the FSRS scheduler will schedule future reviews. If you're not familiar with optimizing FSRS, it is best not to modify these default values.

desired_retention is a value between 0 and 1 that sets the desired minimum retention rate for cards when scheduled with the scheduler. For example, with the default value of desired_retention=0.9, a card will be scheduled at a time in the future when the predicted probability of the user correctly recalling that card falls to 90%. A higher desired_retention rate will lead to more reviews and a lower rate will lead to fewer reviews.

learning_steps are custom time intervals that schedule new cards in the Learning state. By default, cards in the Learning state have short intervals of 1 minute then 10 minutes. You can also disable learning_steps with Scheduler(learning_steps=())

relearning_steps are analogous to learning_steps except they apply to cards in the Relearning state. Cards transition to the Relearning state if they were previously in the Review state, then were rated Again - this is also known as a 'lapse'. If you specify Scheduler(relearning_steps=()), cards in the Review state, when lapsed, will not move to the Relearning state, but instead stay in the Review state.

maximum_interval sets the cap for the maximum days into the future the scheduler is capable of scheduling cards. For example, if you never want the scheduler to schedule a card more than one year into the future, you'd set Scheduler(maximum_interval=365).

enable_fuzzing, if set to True, will apply a small amount of random 'fuzz' to calculated intervals. For example, a card that would've been due in 50 days, after fuzzing, might be due in 49, or 51 days.

Timezone

Py-FSRS uses UTC only.

You can still specify custom datetimes, but they must use the UTC timezone.

Retrievability

You can calculate the current probability of correctly recalling a card (its 'retrievability') with

retrievability = scheduler.get_card_retrievability(card)

print(f"There is a {retrievability} probability that this card is remembered.")
# > There is a 0.94 probability that this card is remembered.

JSON-Serialization

Scheduler, Card and ReviewLog objects are all JSON-serializable via their to_json and from_json methods for easy database storage, network requests, etc:

# serialize
scheduler_json = scheduler.to_json()
card_json = card.to_json()
review_log_json = review_log.to_json()

# deserialize
scheduler = Scheduler.from_json(scheduler_json)
card = Card.from_json(card_json)
review_log = ReviewLog.from_json(review_log_json)

Optimizer (optional)

If you have a collection of ReviewLog objects, you can optionally reuse them to compute an optimal set of parameters for the Scheduler to make it more accurate at scheduling reviews. You can also compute an optimal retention rate to reduce the future workload of your reviews.

Installation

pip install "fsrs[optimizer]"

Optimize scheduler parameters

from fsrs import ReviewLog, Optimizer, Scheduler

# load your ReviewLog objects into a list (order doesn't matter)
review_logs = [ReviewLog1, ReviewLog2, ...]

# initialize the optimizer with the review logs
optimizer = Optimizer(review_logs)

# compute a set of optimized parameters
optimal_parameters = optimizer.compute_optimal_parameters()

# initialize a new scheduler with the optimized parameters
scheduler = Scheduler(optimal_parameters)

Optimize desired retention

optimal_retention = optimizer.compute_optimal_retention(optimal_parameters)

# initialize a new scheduler with both optimized parameters and retention
optimal_scheduler = Scheduler(optimal_parameters, optimal_retention)

Reschedule cards after optimization

After creating a new scheduler with optimized parameters, you may want to reschedule/update each of your previous cards with this new scheduler.

# repeat the following for each of your cards
rescheduled_card = optimal_scheduler.reschedule_card(card, review_logs_for_that_card)

Reference

Card objects have one of three possible states

State.Learning # (==1) new card being studied for the first time
State.Review # (==2) card that has "graduated" from the Learning state
State.Relearning # (==3) card that has "lapsed" from the Review state

There are four possible ratings when reviewing a card object:

Rating.Again # (==1) forgot the card
Rating.Hard # (==2) remembered the card with serious difficulty
Rating.Good # (==3) remembered the card after a hesitation
Rating.Easy # (==4) remembered the card easily

API Documentation

You can find additional documentation for py-fsrs here.

Interactive Demo

Developers who'd like a visual understanding of how py-fsrs works can check out this interactive-demo.

Other FSRS implementations

You can find various other FSRS implementations and projects here.

Other SRS python packages

The following spaced repetition schedulers are also available as python packages:

Contribute

If you encounter issues with py-fsrs or would like to contribute code, please see CONTRIBUTING.

Metadata

Release files for fsrs 6.3.3

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

Source distribution (sdist)

Source distribution for fsrs 6.3.3
File Size Uploaded Provenance Actions
fsrs-6.3.3.tar.gz 33.7 kB Without provenance Details for fsrs-6.3.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fsrs 6.3.3
File Interpreter ABI Platform Actions
fsrs-6.3.3-py3-none-any.whl Python 3 none any Details for fsrs-6.3.3-py3-none-any.whl

Total release size: 56.6 kB

Release files / fsrs-6.3.3.tar.gz

Download URL fsrs-6.3.3.tar.gz
Size 33.7 kB
Tags Source
SHA-256 checksum
How to use checksums
916ef5c7de96508c9077e1888b9786ef33babb3f59ac3108926cebfcaadccff6
BLAKE2b-256 checksum
How to use checksums
4e4da18d9850b883977ec445a69464aa0bb852910c98c42e2adabc8e0519ba00
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Release files / fsrs-6.3.3-py3-none-any.whl

Download URL fsrs-6.3.3-py3-none-any.whl
Size 22.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0e06323c564fdb429bf65f8d0d3d5ace05b19e005ac080f015dc8631ad3901e2
BLAKE2b-256 checksum
How to use checksums
54a9a3a2a3c423ee08ced77906a2456631a50d10054c27f83fdf415c02198f93
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Security for fsrs 6.3.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

6.3.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page