Install & Compatibility
Where this runs
tested against v1.22.1 · 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.028s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.028s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ from parse import parse
search
✓ from parse import search
findall
✓ from parse import findall
with_pattern
✓ from parse import with_pattern
compile
✓ from parse import compile
✗ from parse import *; compile(...)
The `compile` function is explicitly excluded from `from parse import *` to avoid overriding Python's built-in `compile()` function. It must be imported directly or accessed via `parse.compile` if doing `import parse`.
This quickstart demonstrates basic string parsing, extracting named fields, searching for patterns, finding all occurrences, and compiling a pattern for repeated use, which improves performance. It also shows how to use type specifiers like `:g` for floats.
from parse import parse, search, findall, compile
# Basic parsing
result = parse("Hello {name}!", "Hello World!")
if result: # Check if parsing was successful
print(f"Name (basic): {result['name']}")
# Named fields
log_line = "User {user_id} logged in from {ip_address} at {timestamp}"
parsed_log = parse(log_line, "User 123 logged in from 192.168.1.1 at 2023-01-01 10:00:00")
if parsed_log:
print(f"User ID: {parsed_log['user_id']}, IP: {parsed_log['ip_address']}")
# Searching for patterns
text = "The quick brown fox jumps over the lazy dog. Another fox is here."
found = search("fox", text)
if found:
print(f"Found 'fox' at position: {found.span}")
# Finding all occurrences
all_foxes = findall("fox", text)
print(f"All 'fox' matches: {[m.span for m in all_foxes]}")
# Compiling a pattern for efficiency
parser = compile("Sensor {sensor_id} reading: {value:g}")
sensor_data = "Sensor A1 reading: 25.5\nSensor B2 reading: 99.123"
for line in sensor_data.split('\n'):
data = parser.parse(line)
if data:
print(f"Compiled - Sensor ID: {data['sensor_id']}, Value: {data['value']} (Type: {type(data['value'])})")
Debug
Known issues
gotchaBy default, the `parse` and `search` functions perform case-insensitive matching. If case-sensitive matching is required, you must explicitly set the `case_sensitive=True` argument.fixUse `parse(pattern, text, case_sensitive=True)` or `search(pattern, text, case_sensitive=True)`.
affects: All versions
gotchaThe library does not support numbered fields (e.g., `{0}`, `{1}`) like Python's `format()` method. Fields are either anonymous (`{}`) or named (`{field_name}`). The order of anonymous fields in the `Result.fixed` tuple corresponds to their appearance in the pattern.fixUse named fields (`{field_name}`) for clarity or rely on the positional order of anonymous fields. Avoid attempting to use numbered field syntax. affects: All versions
gotchaThe `compile()` function for `parse` is intentionally not exported when using `from parse import *` to avoid conflicting with Python's built-in `compile()` function. Attempting to use `compile` directly after `import *` will likely call the built-in function, not the library's.fixImport `compile` explicitly (e.g., `from parse import compile`) or import the module directly (e.g., `import parse` and then use `parse.compile()`).
affects: All versions
deprecatedThe standard library's `parser` module (for accessing Python's internal parse trees) was deprecated in Python 3.9 and removed in Python 3.10. Users often confuse this with the `parse` PyPI library. The `parse` PyPI library is distinct and remains active.fixEnsure you are installing and importing the `parse` PyPI library (`pip install parse`, `from parse import parse`). If you intended to parse Python code's AST, use the `ast` module instead of the removed `parser` module.
affects: Python 3.9 (deprecated), Python 3.10+ (removed)
gotchaThe `Result` object returned by `parse()` or `search()` does not have a `span` attribute. Unlike Python's `re` module `MatchObject`, the `parse` library's `Result` objects primarily provide access to the matched fields themselves, not their start and end character positions within the original text.fixAccess matched data through named fields (e.g., `result.field_name`) or positional access (e.g., `result[0]`, `result.fixed`). If character span information (start and end indices of the match) is required, consider using Python's built-in `re` module, which provides `span()` on its match objects.
affects: All versions
gotchaThe `Result` object returned by `parse` and `search` functions provides a `spans` attribute (plural) which is a list of (start, end) tuples for matched fields. It does not have a `span` (singular) attribute. Attempting to access `Result.span` will raise an `AttributeError`.fixUse `Result.spans` (plural) to access the span information for matched fields.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'parse'
The 'parse' library is not installed in the Python environment, or the environment where it is installed is not the one being used.
fixInstall the library using pip: `pip install parse`
AttributeError: 'Result' object has no attribute 'group'
The user is attempting to access parsed data using a method (like `group()`) commonly found on `re.Match` objects, but the `parse` library's `Result` object stores extracted data in its `fixed` (tuple) or `named` (dictionary) attributes.
fixAccess the matched data using `result.fixed` for positional matches or `result.named` for named matches.
Example:
```python
import parse
result = parse.parse("Hello {}", "Hello World")
# print(result.group(0)) # Incorrect
print(result.fixed) # Correct
``` ValueError: invalid literal for int() with base 10: 'not_a_number'
The format string used with `parse()` specifies a type conversion (e.g., `:d` for integer), but the corresponding part of the input string cannot be successfully converted to that type.
fixEnsure the input string's data matches the expected type in the format specification, or handle the `ValueError` with a `try-except` block.
Example:
```python
import parse
# result = parse.parse("ID: {:d}", "ID: not_a_number") # Causes ValueError
try:
result = parse.parse("ID: {:d}", "ID: 123")
print(result.fixed)
except ValueError as e:
print(f"Parsing failed: {e}")
``` NameError: name 'parse' is not defined
The 'parse' module was imported using `import parse`, but the user attempted to call the `parse` function directly (e.g., `parse("...")`) without qualifying it with the module name (`parse.parse("...")`).
fixEither call the function using `parse.parse(...)` or change the import statement to `from parse import parse`.
Example:
```python
import parse
# result = parse("Item: {}", "Item: Apple") # Causes NameError
result = parse.parse("Item: {}", "Item: Apple") # Correct
print(result.fixed)
# Alternative fix:
# from parse import parse
# result = parse("Item: {}", "Item: Apple") # This now works
# print(result.fixed)
``` Upgrade
Version history
1.22.1latest on PyPI · released May 26, 2026
Audit
Dependencies
No dependency data recorded yet.