Install & Compatibility
Where this runs
tested against v1.0.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.178s · 19.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.168s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
run, eq, membero, var, lall
✓ from kanren import run, eq, membero, var, lall
✗ from minikanren import ...
The PyPI package name is `minikanren`, but the Python importable package is `kanren`.
This quickstart demonstrates basic relational programming with `minikanren`. It shows how to declare logic variables (`var`), express equality relations (`eq`), and run a query to find solutions. The first example finds `x` such that `x` equals 5. The second finds `y` and `z` such that both are 3. The third shows unification of a structure. [2, 3]
from kanren import run, eq, var
x = var()
results = run(1, x, eq(x, 5))
print(results)
y, z = var(), var()
results_multi = run(1, (y, z), eq(y, z), eq(z, 3))
print(results_multi)
# Example with unification of structures
results_struct = run(1, x, eq((1, 2), (1, x)))
print(results_struct)
Debug
Known issues
gotchaThe PyPI package is `minikanren`, but the Python module to import is `kanren`. Importing from `minikanren` directly will result in an `ImportError`. [2, 3]fixAlways use `from kanren import ...` for imports.
affects: All versions
gotchaLike other logic programming languages, `minikanren` queries may enter an infinite loop if no solution exists within an infinite search tree. The interleaved search strategy guarantees finding solutions if they exist, but cannot guarantee termination if no solution is found and the search space is unbounded. [16]fixCarefully design goals to constrain the search space or be aware of potential non-termination for certain queries.
affects: All versions
gotchaWhile `minikanren`'s interleaving search provides completeness, the order of goals can still impact performance, especially in complex scenarios. Inefficient goal ordering might lead to longer execution times or seemingly non-terminating searches if favorable branches are explored later. [18, 20]fixExperiment with different goal orderings, prioritizing more restrictive goals earlier in conjunctions (`lall`) to prune the search space faster.
affects: All versions
breakingThe `kanren` project is a fork of `logpy` and while aiming for syntactic parity, it deviates significantly in 'core mechanics and offerings'. Users migrating from `logpy` should be aware that internal behaviors and potential extensions might differ substantially. [2]fixConsult `minikanren` documentation and examples when migrating from `logpy` to understand the differences in core implementation and available features.
affects: From 1.0.0 onwards, compared to `logpy`
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'kanren'
The `minikanren` library in Python is actually published under the package name `kanren`.
fixInstall the library using `pip install kanren` or `conda install -c conda-forge kanren`, and then import with `from kanren import ...`.
ImportError: cannot import name 'Iterator' from 'collections'
This error occurs in newer Python versions (e.g., Python 3.10+) because `collections.Iterator` was deprecated and moved to `collections.abc.Iterator`.
fixUpgrade the `kanren` library to a version compatible with your Python interpreter, or, if using an older `kanren` version with Python 3.10+, manually patch the import in your environment (though upgrading is recommended). Some users report success after `conda install -c conda-forge miniKanren` and restarting the kernel.
TypeError: 'list' object is not callable
This often happens when trying to use a list directly as a goal function in `kanren` without proper goal construction (e.g., trying to use `my_list(var())` instead of `membero(var(), my_list)` or `eq(var(), my_list[0])`). Goals must be created by calling `kanren` goal constructors like `eq`, `membero`, `lall`, `lany`, or user-defined relations.
fixEnsure that arguments passed to `run` and within goal compositions are actual `kanren` goal objects, created by functions like `eq`, `membero`, `lall`, `lany`, or custom `Relation` instances, not raw Python types used as functions.
AttributeError: 'State' object has no attribute 'reify'
This error indicates an attempt to call `reify` directly on a `State` object, which is an internal representation of the search process. `reify` is usually implicitly handled by the `run` function when it extracts results.
fixInstead of manually calling `reify`, use the `run` function to execute goals and retrieve the reified results. `run` manages the state and reification automatically, returning the desired solutions.
Upgrade
Version history
1.0.5latest on PyPI · released Jun 24, 2025
Audit
Dependencies
multipledispatchrequiredUsed internally for supporting pattern matching on user-defined types. [2]
logical-unificationrequiredUsed internally for supporting pattern matching on user-defined types. [2]