Install & Compatibility
Where this runs
tested against v5.1.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.920 runs
installs and imports cleanly · install 0.0s · import 0.012s · 26.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.012s · 25MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
try_float
✓ from fastnumbers import try_float
Recommended for fast float conversion with error handling.
try_int
✓ from fastnumbers import try_int
Recommended for fast integer conversion with error handling.
float (replacement)
✓ from fastnumbers import float
✗ import fastnumbers; fastnumbers.float('123.45')
This provides a faster drop-in replacement for the built-in `float`, but calling `fastnumbers.float()` is slower due to Python's namespace lookup. Note that this is a function, not a class, so `isinstance()` checks will not work directly.
fast_float (deprecated)
✓ from fastnumbers import try_float
✗ from fastnumbers import fast_float
The `fast_float` function was deprecated in v4.0.0; `try_float` is the preferred replacement with a more flexible API.
This quickstart demonstrates the core functionality of `fastnumbers` using `try_float` and `try_int` for robust number conversions. It shows how to handle unconvertible inputs by returning the original input (default), a specified default value, raising a `ValueError`, or executing a custom callback function.
from fastnumbers import try_float, try_int, RAISE, INPUT
# Basic conversion with default error handling (returns input on failure)
print(f"'123.45' -> {try_float('123.45')}")
print(f"'abc' -> {try_float('abc')}")
# Convert to float, returning a default value on failure
print(f"'abc' with default=0.0 -> {try_float('abc', default=0.0)}")
# Convert to int, raising an error on failure
try:
print(f"'123' -> {try_int('123')}")
print(f"'45.67' -> {try_int('45.67')}") # Truncates float strings to int
print(f"'xyz' -> {try_int('xyz', on_fail=RAISE)}")
except ValueError as e:
print(f"'xyz' with on_fail=RAISE -> {e}")
# Convert to float, using a custom function on failure
def handle_fail(val):
return f"Failed to convert: {val}"
print(f"'bad_num' with custom handler -> {try_float('bad_num', on_fail=handle_fail)}")
Debug
Known issues
breakingAs of fastnumbers version 4.0.0, Python versions older than 3.7 are no longer supported. Ensure your environment uses Python 3.7 or newer.fixUpgrade your Python interpreter to version 3.7 or later.
affects: >=4.0.0
deprecatedFunctions like `fast_real`, `fast_float`, `fast_int`, `fast_forceint`, `isreal`, `isfloat`, `isint`, and `isintlike` were deprecated in version 4.0.0. While they are still available, new development should use their more flexible replacements: `try_real`, `try_float`, `try_int`, `try_forceint`, `check_real`, `check_float`, `check_int`, and `check_intlike` respectively.fixRefactor code to use the `try_*` functions for error-handling conversions and `check_*` functions for type checking.
affects: >=4.0.0
gotchaDirectly calling `fastnumbers.int()` or `fastnumbers.float()` (e.g., `import fastnumbers; fastnumbers.int('5')`) is slower than importing them directly (e.g., `from fastnumbers import int; int('5')`). This is due to Python's internal namespace lookup overhead.fixAlways import the specific functions you intend to use directly, e.g., `from fastnumbers import int` or `from fastnumbers import float`.
affects: All versions
gotchaThe `denoise` option, available in some conversion functions, adds additional overhead to the calculation. While it provides `decimal.Decimal`-like accuracy for floats (especially from strings), it is significantly slower than conversions without `denoise`.fixEvaluate the trade-off between speed and the need for high-precision decimal conversion. Use `denoise` only when precise decimal behavior is critical and the performance impact is acceptable.
affects: All versions with `denoise` option
gotchaThe `float` and `int` functions provided by `fastnumbers` (e.g., `from fastnumbers import float`) are not class types like Python's built-in `float` and `int`. Therefore, they cannot be used with `isinstance()` (e.g., `isinstance(9.4, fastnumbers.float)` will raise a `TypeError`).fixWhen performing `isinstance` checks, use the built-in types explicitly: `import builtins; isinstance(9.4, builtins.float)`.
affects: All versions
Errors
Common errors & fixes
error: command '/usr/bin/clang' failed with exit code 1
Installation fails on macOS (and potentially other Unix-like systems) when trying to compile the C extension, often due to incompatibility between older `fastnumbers` versions and newer Python versions (e.g., Python 3.9+).
fixUpgrade `fastnumbers` to version 3.1.0 or higher (`pip install --upgrade fastnumbers`). If an upgrade is not possible, consider using a Python environment with version 3.8 or lower.
TypeError: isinstance() arg 2 must be a type or tuple of types
This error occurs when attempting to use `fastnumbers.int` or `fastnumbers.float` (imported as drop-in replacements for built-ins) in `isinstance()` checks. These are functions, not type objects.
fixFor type checking with `isinstance()`, use Python's built-in types by explicitly importing `builtins` or referencing them directly: `import builtins; isinstance(value, builtins.int)` or `isinstance(value, int)`.
ValueError: invalid literal for float(): 'some_string'
You are attempting to convert an input string that cannot be parsed as a number, and the `fastnumbers` function is configured to raise a `ValueError` on failure (e.g., `on_fail=RAISE` or `raise_on_invalid=True` in deprecated functions).
fixModify the `on_fail` parameter (or `default` for deprecated functions) to handle invalid inputs gracefully. Options include `on_fail=INPUT` (returns original input), `default=0.0` (returns a specific value), or `on_fail=my_custom_handler` (calls a function). Example: `try_float('bad_input', default=0.0)`. Upgrade
Version history
5.1.1latest on PyPI · released Dec 15, 2024
Audit
Dependencies
No dependency data recorded yet.