Install & Compatibility
Where this runs
tested against v3.13.0.0 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Vale
✓ import vale
✗ from vale import Vale
This quickstart demonstrates how to initialize the `Vale` object and lint a string. Note that Vale requires a `.vale.ini` configuration file and a `StylesPath` directory to operate correctly. This example creates minimal temporary configuration files. In a real application, you would manage these configuration files within your project structure. The Vale CLI binary is downloaded the first time `vale.lint()` is called, which might take a moment.
import os
from vale import Vale
# Vale requires a .vale.ini config file and a StylesPath directory.
# For a quickstart, we'll create minimal ones in a temporary directory.
# In a real project, these would be managed in your project structure.
config_content = """
StylesPath = styles
MinAlertLevel = warning
[*.md]
BasedOn = proselint
"""
style_content = """
# styles/proselint/SomeRule/Vocab.yml
# Minimal example rule (if you had a custom rule)
"""
# Create a temporary directory structure
# In a real application, you'd manage config_dir and style_dir appropriately
import tempfile
import shutil
try:
with tempfile.TemporaryDirectory() as temp_dir:
config_dir = os.path.join(temp_dir, ".vale")
styles_dir = os.path.join(config_dir, "styles", "proselint")
os.makedirs(styles_dir, exist_ok=True)
with open(os.path.join(config_dir, ".vale.ini"), "w") as f:
f.write(config_content)
# You'd typically install actual styles here or reference system-wide ones
# For this quickstart, we just need the directories to exist.
vale_instance = Vale(config_path=os.path.join(config_dir, ".vale.ini"))
text_to_lint = "This is a very simple test. I will be using bad grammar."
# Lint the text. Output format is typically JSON.
# The default output is a list of dictionaries, one for each alert.
alerts = vale_instance.lint(text_to_lint, syntax='md')
print(f"Found {len(alerts)} alerts:")
for alert in alerts:
print(f" - [{alert['Severity']}] {alert['Message']} (Rule: {alert['Check']})")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure Vale CLI is successfully downloaded on first run and config is valid.")
vale --version
Debug
Known issues
gotchaThe Vale CLI binary is not bundled with the Python package. It is automatically downloaded and installed on the user's system the first time any method requiring the Vale CLI is executed. This means the first run might take longer due to the download.fixBe aware that the first execution of a Vale operation will involve a download. Subsequent runs will use the cached binary.
affects: All versions
breakingThe versioning of the Python `vale` package (`X.Y.Z.P`) directly corresponds to the Vale CLI version (`X.Y.Z`). The fourth number (`P`) is specific to Python package fixes and is ignored when downloading the Vale CLI. Therefore, incrementing the fourth number does not update the underlying Vale CLI version.fixTo update the Vale CLI version, you must update the Python package to a version where the first three numbers (X.Y.Z) match the desired Vale CLI version. If only the Python wrapper needs fixing, increment the fourth number.
affects: All versions
breakingBreaking changes in new versions of the underlying Vale CLI tool can silently alter linting behavior or cause errors, especially if not pinning the exact version. For example, Vale CLI v3.11.0 introduced changes to linting Front Matter fields that could break existing CI pipelines.fixAlways pin the exact version of the `vale` Python package in your `requirements.txt` or `pyproject.toml` to ensure consistent behavior across environments. For example, `vale==3.13.0`.
affects: Vale CLI v3.11.0 and later (as reflected in `vale` Python package versions)
Upgrade
Version history
3.13.0.0latest on PyPI · released Oct 28, 2025
Audit
Dependencies
No dependency data recorded yet.