How to Search MLflow Runs by Parameter Value
Parameters are the settings a run was trained with, such as a model type or a tree depth, and searching by them answers "which runs used this setting?". MLflow stores every parameter as text, which shapes every search: values go in quotes, a setting of None is the text 'None', and > and < don't work. This guide searches three runs by parameter four ways, with real results from MLflow 3.18.0.
Syntax
params.<name> = '<value>'
params.<name> != '<value>'
params.<name> LIKE '<pattern>'
params.<name> IS NULL
| Part | What it means |
|---|---|
params.<name> | The parameter to look at, such as params.max_depth |
'<value>' | The value as text, in single or double quotes, even when it's a number: '3' |
LIKE '<pattern>' | A pattern, where % stands for any number of characters: 'tr%' matches tree. ILIKE does the same but ignores case |
IS NULL | Runs that never logged this parameter. IS NOT NULL is the opposite |
The same strings work in the UI's search box and in mlflow.search_runs(filter_string=...).
Prerequisites
- An MLflow tracking server at
http://127.0.0.1:8080. MLflow's tracking server guide shows how to start one.
Step 1: Create Three Runs
The example is three models: a tree limited to depth 3, a tree with no depth limit, logged as None, and a linear model that has no depth setting at all. Create depth_runs.py:
import mlflow
mlflow.set_tracking_uri("http://127.0.0.1:8080")
mlflow.set_experiment("param-search-demo")
with mlflow.start_run(run_name="shallow-tree"):
mlflow.log_params({"model": "tree", "max_depth": 3})
with mlflow.start_run(run_name="deep-tree"):
mlflow.log_params({"model": "tree", "max_depth": None})
with mlflow.start_run(run_name="linear"):
mlflow.log_param("model", "linear")
uv run python depth_runs.py
It prints a View run link for each run.
Step 2: Search by Parameter
Create param_search.py. It tries five searches and prints either the matching runs or MLflow's error:

import mlflow
from mlflow.exceptions import MlflowException
mlflow.set_tracking_uri("http://127.0.0.1:8080")
for search in [
"params.max_depth = '3'",
"params.model LIKE 'tr%'",
"params.max_depth = 'None'",
"params.max_depth IS NULL",
"params.max_depth = 3",
]:
try:
runs = mlflow.search_runs(experiment_names=["param-search-demo"], filter_string=search)
print(f"{search:28} -> {sorted(runs['tags.mlflow.runName'])}")
except MlflowException as error:
print(f"{search:28} -> {error.message}")
uv run python param_search.py
params.max_depth = '3' -> ['shallow-tree']
params.model LIKE 'tr%' -> ['deep-tree', 'shallow-tree']
params.max_depth = 'None' -> ['deep-tree']
params.max_depth IS NULL -> ['linear']
params.max_depth = 3 -> INVALID_PARAMETER_VALUE: Expected a quoted string value for parameter (e.g. 'my-value'). Got value 3

Step 3: Read the Results
| Search | Result | Why |
|---|---|---|
params.max_depth = '3' | shallow-tree | log_params turned the number 3 into the text '3', so the value must be quoted |
params.model LIKE 'tr%' | both trees | tr% is any value starting with tr |
params.max_depth = 'None' | deep-tree | Logging Python's None stored the text 'None': the run has the parameter |
params.max_depth IS NULL | linear | Only the run that never logged max_depth |
params.max_depth = 3 | an error | A number without quotes isn't accepted for a parameter |
The difference between 'None' and IS NULL matters when a setting is optional: "no limit" logged as None is a value you can search for, while a parameter that was never logged is missing.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
A number without quotes, params.max_depth = 3 | Expected a quoted string value for parameter (e.g. 'my-value'). Got value 3 | Quote it: params.max_depth = '3' |
Comparing with > or <, such as params.max_depth > '2' | Invalid comparator '>' not one of ...: the fix | Use =, != or LIKE |
Searching for a None setting with IS NULL | No match: the run logged the text 'None' | Use params.max_depth = 'None' |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| A search by a parameter returns nothing, with no error | The name or the value differs in spelling or case | Check both on the run's Overview |
| You need runs with a setting above some number | Parameters can't be compared as numbers | Log the value as a metric as well, or filter the results in Python |
FAQ
Why are parameters text?
MLflow stores every parameter value as a string, whatever type you logged. Metrics are the numbers.
Can I search several parameters at once?
Yes, with AND: params.model = 'tree' AND params.max_depth = '3'.
Does IN work for parameters?
No. params.model IN ('tree', 'linear') fails with Expected a quoted string value for parameter. In MLflow, IN works for dataset fields and run IDs only.
Conclusion
params.max_depth = '3' found the run by its setting, with the number in quotes because parameters are text. LIKE matched a pattern, = 'None' found the run that logged None, and IS NULL the one that never logged the parameter.
Additional Resources
- Search Runs — MLflow's guide, with its section on parameters.
- mlflow.log_params — how parameters are logged.
