Skip to main content

xpd

Run uvx xpd check . to find the lines of your Python code that are slow or give a wrong result, and add --fix to let xpd rewrite the ones it can. xpd checks code that uses pandas, NumPy, SciPy, scikit-learn, scikit-lego, MAPIE, Category Encoders, linearmodels, arch, pymoo, plotly or Apache Hamilton. It starts no Python, so a coding agent can run it after every edit.

$ uvx xpd check samples/bad.py
samples/bad.py:5:15: warning [pandas/row-loop] iterrows() builds a Series for every row. Compute on whole columns instead, such as df["a"] * df["w"]. When each row has to become a Python object, loop over itertuples() or to_dict("records").
samples/bad.py:6:5: error [pandas/chained-assignment] Chained assignment writes to a copy under copy-on-write, so the frame keeps its old values. Assign to df.loc[i, "a"] instead.
samples/bad.py:7:1: info [pandas/no-inplace] inplace=True gives no speedup and blocks chaining. Reassign instead.
samples/bad.py:8:5: warning [pandas/merge-without-validate] merge without validate= can silently duplicate rows.
samples/bad.py:11:5: warning [pandas/concat-in-loop] out grows by one concat per pass, and each concat copies every earlier row. Collect the frames in a list and concat once after the loop.
xpd: 5 issues, 2 more with --fix --unsafe-fixes

What a fix changes

xpd check samples/bad.py --fix --unsafe-fixes rewrites two of the five lines and reports the other three again.

 import pandas as pd

 df = pd.DataFrame({"a": [1, 2], "k": [1, 2]})
 other = df.copy()
 for i, row in df.iterrows():
-    df["a"][i] = row["a"] * 2
-df.dropna(inplace=True)
+    df.loc[i, "a"] = row["a"] * 2
+df = df.dropna()
 m = pd.merge(df, other, on="k")
 out = pd.DataFrame()
 for f in ["x.csv"]:
     out = pd.concat([out, pd.read_csv(f)])

Fix every error, and fix a warning unless you can say why the code is right in that place.

Word Meaning
error The code gives a wrong result or raises.
warning The code is slow or easy to get wrong.
info A shorter or newer form exists.
safe fix The rewrite keeps what the code does, and --fix writes it.
unsafe fix The rewrite may change what the code does. --fix --unsafe-fixes writes it, so read the diff afterwards.

xpd check exits with 0 when it finds no error, and with 1 when it finds one. It exits with 2 when it can't run.

Install

uv tool install xpd installs the xpd command, and uvx xpd check . runs it once without an install.

uv tool install xpd

Rules

Each library has one pack of rules, and the pack runs only on a file that imports the library. The Python pack runs on every file, and the plotly pack also runs on a file that makes plotly the plotting backend of pandas.

Pack One of its rules What the rule reports
pandas chained-assignment df["a"][i] = v writes to a copy, so the frame keeps its old values
NumPy append-flattens np.append without axis flattens both arrays
SciPy removed-keyword tol= on the sparse iterative solvers was removed and raises TypeError
scikit-learn fit-on-test A fit on the test rows scored 0.997 AUC on data with no signal
scikit-lego thresholder-score Thresholder.score ignores threshold, so a grid search over 0.1, 0.5 and 0.9 gave 0.887 three times
MAPIE calibrate-on-training-rows conformalize on the training rows covered 0.468 of the test rows where 0.9 was asked
Category Encoders ordinal-mapping-pairs An OrdinalEncoder mapping given as a list of pairs codes every row as -1.0
linearmodels clustered-without-clusters cov_type="clustered" without clusters gives the robust standard errors
arch unscaled-returns Returns as decimals stopped the optimizer with code 4 and gave a mean of 4.02 where 0.056 was right
pymoo objectives-stacked-by-row out["F"] = np.array([f1, f2]) in a Problem gives each solution the wrong values
plotly marker-size-diameter A marker's size is its diameter, so markers of size 10 and 20 had areas of 78.5 and 314.2 square pixels
Hamilton node-mutates-input A node writes to its input, and Hamilton hands the same object to other nodes
Python dict-str-any dict[str, Any] in a signature hides the keys the function uses

xpd rules lists every rule, and the rules page shows each one with code before and after.

Commands

xpd <command> -h lists the flags of a command, and the commands page shows the output and the exit codes of each one.

xpd
├── lint
│   ├── check [paths]          lint files and folders, and rewrite with --fix (alias: scan)
│   ├── rules                  list every rule with its documentation
│   └── hook                   lint the files that an agent's edit changed
├── look up a library
│   ├── find "<task>"          find library symbols, rules and worked recipes for a task
│   ├── api <name>             read one symbol, method or recipe in full
│   └── index <source>         build a search index from library source
├── read and rewrite code
│   ├── run [paths]            find a code pattern, and preview or apply a rewrite (alias: query)
│   ├── outline [paths]        show imports, definitions and members with line numbers
│   └── graph <files>          print the dataflow of step code or Hamilton modules
├── run the project's Python
│   ├── profile <data file>    print dtypes, nulls, unique counts and memory per column
│   ├── equiv old.py new.py    run two scripts and compare the `result` each one leaves
│   └── refit <contract>       refit a saved Pipeline on raw training rows and compare
├── write your own rules
│   ├── new                    create a rule project, a rule, a test case or a utility
│   └── test                   check rule examples and compare snapshots
└── connect a tool
    ├── mcp                    start the MCP server for agents
    ├── lsp                    start the language server for editors
    ├── skill                  print the agent skill for the installed version
    └── completions <shell>    print shell completion for bash, elvish, fish, powershell or zsh

profile, equiv and refit run the project's Python, and they need pandas in the project's environment. index runs it too, with Griffe, and the first find runs it once to download the search model. mcp starts the MCP server with the Python that the xpd package installs. Every other command only reads files.

Look up a library you don't know

xpd find "<task>" lists the classes, rules and recipes for a task in your own words, even for a library you haven't installed. A recipe is a worked example from the library's documentation. xpd api <name> then prints one entry in full, with each parameter's type annotation and default as the source writes them, so a default in a stub file shows as .... You can also name a method of a class, as the last call below does with mapie.subsample.BlockBootstrap.split.

$ xpd find "time series bootstrap for cross validation" --limit 1
Symbols
sklearn.model_selection.TimeSeriesSplit(n_splits, max_train_size, test_size, gap) [class]
Time Series cross-validator.
Rules: sklearn/groups-ignored, sklearn/removed-in-sklearn
Rules
sklego/group-time-series-split-folds [rule]
The rule reports `GroupTimeSeriesSplit` with 6 or more splits. The class tries every combination of
split points over the groups to find the most even folds, so each extra fold multiplies the time.
Recipes
mapie/recipe/generate-a-sampling-method-that-block-bootstraps-the [recipe]
Generate a sampling method, that block bootstraps the training set.

$ xpd api mapie.subsample.BlockBootstrap
mapie.subsample.BlockBootstrap(n_resamplings: int = 30, length: Optional[int] = None, n_blocks: Optional[int] = None, overlapping: bool = False, random_state: Optional[Union[int, RandomState]] = None) [class]
Generate a sampling method, that block bootstraps the training set. It can replace KFold, LeaveOneOut or SubSample as cv argument in the TimeSeriesRegressor class.
  get_n_splits(args, kargs) Returns the number of splitting iterations in the cross-validator.
  split(X, args, kargs) Generate indices to split data into training and test sets.
Rules: mapie/unseeded-resampling

$ xpd api mapie.subsample.BlockBootstrap.split
mapie.subsample.BlockBootstrap.split(X: NDArray, *args: Any, **kargs: Any) [method]
Generate indices to split data into training and test sets.
Fact about find Value
Results without --limit Up to 5 symbols, 3 rules and 3 recipes
Flags --kind symbol, --kind rule or --kind recipe selects one kind, and --package selects one library
Ranking By keywords and by meaning, so a task finds an entry whose documentation uses other words
Model for the meaning EmbeddingGemma, a 333 MB file that the first find downloads once
Without the model find says so on stderr and ranks by keywords only
Where recipes come from Library documentation and galleries. xpd keeps an example only when its own rules report nothing in it, and it never runs the example

The first find saves the model in the folder that the table below names for your system, and XDG_CACHE_HOME takes precedence on every system.

System Model folder
Any, with XDG_CACHE_HOME set $XDG_CACHE_HOME/xpd/models
Linux ~/.cache/xpd/models
macOS ~/Library/Caches/xpd/models
Windows %LOCALAPPDATA%\xpd\models

Use in an editor

xpd lsp starts a language server, so your editor shows each issue while you type, with a quick fix and the rule's documentation on hover. The language server page has the setup for Neovim, Helix, Zed and VS Code.

Use with a coding agent

Pick the plugin when your client supports it, because it sets up the MCP server and the skills together. Otherwise set up the parts you want one at a time.

Way What the agent gets Setup
Plugin The MCP server and the skills together Load the xpd repository in a client that supports Agent Plugins, such as Codex
Hook The issues of each file, right after the edit xpd hook in the Claude Code settings
MCP server Typed tools, the rules, the skills and prompts xpd mcp
Skills When to run each command, and Python style that a linter cannot check npx skills add bjoernaagaard/xpd

Plugin

Run the commands below to install the plugin in Codex. The plugin starts xpd with uvx, so the machine needs uv.

codex plugin marketplace add bjoernaagaard/xpd
codex plugin add xpd@xpd

The repository is a plugin in the Agent Plugins format, version 1.0.0. Version 1.0.0 has no hooks, so you add the hook below yourself.

xpd, loaded as a plugin
├── plugin.json                         the name and version of the plugin
├── skills/                             xpd, python-best-practices and python-review
├── mcp.json                            starts the MCP server of the same xpd version with uvx
└── .agents/plugins/marketplace.json    lists the plugin for Codex

Hook

Add the hook below to .claude/settings.json in your project, and Claude Code shows the agent the issues of each .py file it edits, in the same turn.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "xpd hook" }]
      }
    ]
  }
}
Claude Code edits features.py
└── the PostToolUse hook runs xpd hook
    ├── no issues: exit code 0
    ├── issues: exit code 2, and Claude Code shows them to the agent
    └── xpd can't run: exit code 1, and Claude Code shows the message to you

MCP server

The command below adds the MCP server to Claude Code, so the agent calls xpd through typed tools and needs no shell.

claude mcp add xpd -- uvx xpd mcp
xpd mcp
├── tools
│   ├── check, fix                         lint, and write fixes after the user confirms unsafe ones
│   ├── graph, profile, equiv, refit       the commands of the same names
│   ├── find, api                          look up a library for a task and read its API
│   ├── query, rewrite                     search code, preview replacements and confirm edits
│   ├── outline                            read the project's symbols and imports
│   ├── new, test                          create rules, and check their examples and snapshots
│   ├── rules, rule                        list the rules, and read one with its examples
│   ├── discovery_gate, contract, gates    judge a run from a data file to a saved model
│   └── show_issues, show_dataflow, show_columns    tables and a chart, in hosts that draw them
├── resources
│   ├── xpd://rules/{package}/{rule}       one rule's documentation
│   └── skill://<name>/SKILL.md            each skill that ships with xpd
└── prompts
    └── lint_and_fix, review, refactor_data_logic, add_to_dataflow, build_pipeline

The server takes every rule and every result from the xpd binary, so it matches the installed version. The MCP page covers other clients, the settings and how to serve xpd over HTTP. The code mode page shows a run from a data file to a saved scikit-learn model, with checks that xpd runs itself.

Skills

The command below installs the three Agent Skills in skills/. The two Python skills work without xpd, and they run xpd when it is installed.

npx skills add bjoernaagaard/xpd
Skill What it does
xpd Says when to run each xpd command. xpd skill prints it for the installed version.
python-best-practices Holds the rules an agent follows when it writes or changes Python.
python-review Reviews a file, package or diff, and cites the rule for every finding.

Documentation

The full guide is at https://bjoernaagaard.github.io/xpd/, and its rules page also explains how to write a rule.

License

You may use xpd's own code under the MIT license or the Apache-2.0 license, and the other parts that ship with xpd keep the licenses in the table.

Part License Where the text is
xpd's own code MIT or Apache-2.0, as you choose LICENSE-MIT and LICENSE-APACHE
Recipes, which are examples taken from library documentation The license of the library, which is MIT, BSD-3-Clause, Apache-2.0 or NCSA licenses/, one file per library. xpd api <recipe> prints the license name and the source link with the code
option-ext, a dependency shipped unmodified MPL-2.0 licenses/option-ext-LICENSE.txt, with the complete source in licenses/option-ext-0.2.0-source.tar.gz and at https://crates.io/api/v1/crates/option-ext/0.2.0/download
libcst, the parser that checks a fixed file MIT, with parts of CPython under PSF-2.0 licenses/libcst-LICENSE
EmbeddingGemma, the model that find downloads The Gemma Terms of Use at https://ai.google.dev/gemma/terms Not shipped with xpd

The licenses/ folder ships in the crate, the sdist and the wheel, and the package metadata lists the combined licenses.

Metadata

Release files for xpd 0.35.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xpd 0.35.0
File Size Uploaded Provenance Actions
xpd-0.35.0.tar.gz 5.8 MB Without provenance Details for xpd-0.35.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for xpd 0.35.0
File Actions
xpd-0.35.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for xpd-0.35.0-py3-none-win_amd64.whl
xpd-0.35.0-py3-none-musllinux_1_2_x86_64.whl Python 3 none Linux musl 1.2+ x86-64 Details for xpd-0.35.0-py3-none-musllinux_1_2_x86_64.whl
xpd-0.35.0-py3-none-musllinux_1_2_aarch64.whl Python 3 none Linux musl 1.2+ ARM64 Details for xpd-0.35.0-py3-none-musllinux_1_2_aarch64.whl
xpd-0.35.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for xpd-0.35.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
xpd-0.35.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for xpd-0.35.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
xpd-0.35.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for xpd-0.35.0-py3-none-macosx_11_0_arm64.whl
xpd-0.35.0-py3-none-macosx_10_15_x86_64.whl Python 3 none macOS 10.15+ x86-64 Details for xpd-0.35.0-py3-none-macosx_10_15_x86_64.whl

Total release size: 124.6 MB

Release files / xpd-0.35.0.tar.gz

Download URL xpd-0.35.0.tar.gz
Size 5.8 MB
Tags Source
SHA-256 checksum
How to use checksums
2fa869ec51daeaca5e5b50aa858fd1a51a6d9c20b9ebde0d7c989e792825cce7
BLAKE2b-256 checksum
How to use checksums
7dc73d3f139966fc81de1f1abeb869c7d933bf26e9380778e4f421584e6fa4bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.35.0-py3-none-win_amd64.whl

Download URL xpd-0.35.0-py3-none-win_amd64.whl
Size 17.2 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
066a0974a80bdd2e5e0d6a86a0e7ad4f0c92e846b1ab8f0f3b552e4678397c91
BLAKE2b-256 checksum
How to use checksums
adc8e0370f876bbf325408ff4e24ae49aaa3887ea97dd61d81b1049dfc50534f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.35.0-py3-none-musllinux_1_2_x86_64.whl

Download URL xpd-0.35.0-py3-none-musllinux_1_2_x86_64.whl
Size 17.0 MB
Tags Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum
How to use checksums
b10854eaae2a763d7444c557f09797dfd9cafb9339de19b8b15218fcae3ad8a7
BLAKE2b-256 checksum
How to use checksums
9d9c233d101773a85822e2b9d5ff4f732eca35eae50d82680227355d1c121d6a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.35.0-py3-none-musllinux_1_2_aarch64.whl

Download URL xpd-0.35.0-py3-none-musllinux_1_2_aarch64.whl
Size 16.6 MB
Tags Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum
How to use checksums
ec83279dcf169a322217de4ab81a12266cf9cfce0e50696ed7bc0eb82b17f109
BLAKE2b-256 checksum
How to use checksums
e33d2b07e451c68a9fcb53f0539e8aa7a7f56ce3c429748d8501cfb57ca90093
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.35.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL xpd-0.35.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 17.2 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
145482279c52f18e69c533481d82a66c2dae1ee9b3fba5923bd8be616dc6b770
BLAKE2b-256 checksum
How to use checksums
ad5c8bf5f0db444f0fb060b6be2278a7985a0e289d32d3ccf0d895b2ea820370
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.35.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL xpd-0.35.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 16.8 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
a3bde6189b8c3031690d7dbdb4ebf555caae02bc0b1f4b6e303f5f4e7c030256
BLAKE2b-256 checksum
How to use checksums
7a6e549e3c29a6838c67bc129a38430044d9cdad2f42e5b7eecf6910b230df5d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.35.0-py3-none-macosx_11_0_arm64.whl

Download URL xpd-0.35.0-py3-none-macosx_11_0_arm64.whl
Size 17.0 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
1ce30f3c3067874dc0cee445861c868dc07278d46bd2053ce38cc3f9900df1e3
BLAKE2b-256 checksum
How to use checksums
4710e3eded8e5225d20837d2732211dcfdedda5c923a2935929d8cc828d0247f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.35.0-py3-none-macosx_10_15_x86_64.whl

Download URL xpd-0.35.0-py3-none-macosx_10_15_x86_64.whl
Size 17.0 MB
Tags Python 3 macOS 10.15+ x86-64
SHA-256 checksum
How to use checksums
b7745f910dfdde5a80a65cbd2ae8737b50dd77cc4f778e5f9fe0f3c9f67b375b
BLAKE2b-256 checksum
How to use checksums
d599c4dbf6fb73a707412af684024317e37b5b8000cad8d5bee835238261d3be
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for xpd 0.35.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.35.0 This release

8 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page