Skills for working with Python using Astral tools.
- GitHub stars
- 319
Install
/plugin install astral@astral-shRun it inside Claude Code after adding the marketplace with /plugin marketplace add astral-sh/claude-code-plugins.
Contents
Discovered from sourceSkills 3
ruff
Ruff is an extremely fast Python linter and code formatter. It replaces Flake8, isort, Black, pyupgrade, autoflake, and dozens of other tools.
When to use ruff
Always use ruff for Python linting and formatting, especially if you see:
[tool.ruff]section inpyproject.toml- A
ruff.tomlor.ruff.tomlconfiguration file
However, avoid making unnecessary changes:
- Don't format unformatted code - If
ruff format --diffshows changes throughout an entire file, the project likely isn't using ruff for formatting. Skip formatting to avoid obscuring actual changes. - Scope fixes to code being edited - Use
ruff check --diffto see fixes relevant to the code you're changing. Only apply fixes to files you're modifying unless the user explicitly asks for broader fixes.
How to invoke ruff
uv run ruff ...- Use when ruff is in the project's dependencies to ensure you use the pinned versionuvx ruff ...- Use when ruff is not a project dependency, or for quick one-off checksruff ...- Use if ruff is installed globally
Commands
Linting
ruff check . # Check all files in current directory
ruff check path/to/file.py # Check specific file
ruff check --fix . # Auto-fix fixable violations
ruff check --fix --unsafe-fixes . # Include unsafe fixes (review changes!)
ruff check --watch . # Watch for changes and re-lint
ruff check --select E,F . # Only check specific rules
ruff check --ignore E501 . # Ignore specific rules
ruff rule E501 # Explain a specific rule
ruff linter # List available linters
Formatting
ruff format . # Format all files
ruff format path/to/file.py # Format specific file
ruff format --check . # Check if files are formatted (no changes)
ruff format --diff . # Show formatting diff without applying
uv format runs the Ruff formatter. Use uv format --check -- path/to/file.py
to check one file. By default, uv format selects a Ruff version independently
of the project's lockfile. When the project pins Ruff, use uv run ruff format
to match its formatter version.
Configuration
Ruff is configured in pyproject.toml or ruff.toml:
# pyproject.toml
[tool.ruff.lint]
extend-select = ["I", "UP"] # Add import sorting and pyupgrade to the defaults
[tool.ruff.lint.isort]
known-first-party = ["myproject"]
Migrating from other tools
Black → ruff format
black . → ruff format .
black --check . → ruff format --check .
black --diff . → ruff format --diff .
Flake8 → ruff check
flake8 . → ruff check .
flake8 --select E,F . → ruff check --select E,F .
flake8 --ignore E501 . → ruff check --ignore E501 .
isort → ruff check
isort . → ruff check --select I --fix .
isort --check . → ruff check --select I .
isort --diff . → ruff check --select I --diff .
Common patterns
Apply lint fixes before formatting
Run ruff check --fix before ruff format. Lint fixes can change code
structure (e.g., reordering imports), which formatting then cleans up.
ruff check --fix .
ruff format .
Applying and reviewing unsafe fixes
Ruff's full diagnostic output can show a suggested change even when --fix
would leave the code alone. Safe fixes can be applied with --fix. Unsafe fixes
may change behavior and also require --unsafe-fixes. A suggestion marked for
manual review, such as removing commented-out code for ERA001, requires a
manual edit.
ruff check --fix --unsafe-fixes --diff . # Preview changes first
ruff check --fix --unsafe-fixes . # Apply changes
Always review changes before applying --unsafe-fixes:
- Use
ruff rule <CODE>to understand why the fix is considered unsafe - Verify the fix doesn't violate those assumptions in your code
Documentation
For detailed information, read the official documentation:
ty
ty is an extremely fast Python type checker and language server. It replaces mypy, Pyright, and other type checkers.
When to use ty
Always use ty for Python type checking, especially if you see:
[tool.ty]section inpyproject.toml- A
ty.tomlconfiguration file
How to invoke ty
uv run ty ...- Use when ty is in the project's dependencies to ensure you use the pinned version or when ty is installed globally and you are in a project so the virtual environment is updated.uvx ty ...- Use when ty is not a project dependency, or for quick one-off checksty ...- Use if ty is installed globally
Commands
Type checking
ty check # Check all files in current directory
ty check path/to/file.py # Check specific file
ty check src/ # Check specific directory
In a uv project, uv check runs ty with the project's environment. Use
ty check path/to/file.py to select an individual project file. For a script
with inline dependencies, use uv check --script script.py.
Rule configuration
ty check --error possibly-unresolved-reference # Treat as error
ty check --warn division-by-zero # Treat as warning
ty check --ignore import-not-found # Disable rule
ty explain rule import-not-found # Explain the rule and its history
Python version targeting
ty check --python-version 3.12 # Check against Python 3.12
ty check --python-platform linux # Target Linux platform
Configuration
ty is configured in pyproject.toml or ty.toml:
# pyproject.toml
[tool.ty.environment]
python-version = "3.12"
[tool.ty.rules]
possibly-unresolved-reference = "warn"
division-by-zero = "error"
[tool.ty.src]
include = ["src/**/*.py"]
exclude = ["**/migrations/**"]
[tool.ty.terminal]
output-format = "full"
Per-file overrides
Use overrides to apply different rules to specific files, such as relaxing rules for tests or scripts that have different typing requirements than production code:
[[tool.ty.overrides]]
include = ["tests/**", "**/test_*.py"]
[tool.ty.overrides.rules]
possibly-unresolved-reference = "warn"
Language server
This plugin automatically configures the ty language server for Python files
(.py and .pyi).
Migrating from other tools
mypy → ty
mypy . → ty check
mypy path/to/file.py → ty check path/to/file.py
Pyright → ty
pyright . → ty check
pyright path/to/file.py → ty check path/to/file.py
Common patterns
Don't add ignore comments
Fix type errors instead of suppressing them. Only add ignore comments when
explicitly requested by the user. Use ty: ignore, not type: ignore, and
prefer rule-specific ignores:
# Good: rule-specific ignore
x = undefined_var # ty: ignore[unresolved-reference]
# Bad: blanket ty ignore
x = undefined_var # ty: ignore
# Bad: tool agnostic blanket ignore
x = undefined_var # type: ignore
Documentation
For detailed information, read the official documentation:
uv
uv is an extremely fast Python package and project manager. It replaces pip, pip-tools, pipx, pyenv, virtualenv, poetry, etc.
When to use uv
Always use uv for Python work, especially if you see:
- The
uv.lockfile - uv headers in
requirements*files, e.g., "This file was autogenerated by uv"
Don't use uv in projects managed by other tools:
- Poetry projects (identifiable by
poetry.lockfile) - PDM projects (identifiable by
pdm.lockfile)
Choosing the right workflow
Scripts
Use when: Running single Python files and standalone scripts.
Key commands:
uv run script.py # Run a script
uv run --with requests script.py # Run with additional packages
uv add --script script.py requests # Add dependencies inline to the script
Projects
Use when: There is a pyproject.toml or uv.lock
Key commands:
uv init # Create new project
uv add requests # Add dependency
uv remove requests # Remove dependency
uv sync # Sync the environment and update the lockfile if needed
uv sync --locked # Require an up-to-date lockfile
uv run <command> # Run commands in environment
uv run python -c "" # Run Python in project environment
uv run -p 3.12 <command> # Run with specific Python version
Tools
Use uv run for tools declared in the project, such as uv run pytest or
uv run ruff check .. This uses the project's locked tool versions and makes
its dependencies available to the command. Use uvx for standalone tools that
can run in an isolated environment.
Key commands:
uvx <tool> <args> # Run a tool in an isolated environment
uvx <tool>@<version> <args> # Run a specific version of a tool
Important:
uvxruns tools from PyPI by package name. This can be unsafe - only run well-known tools.- Only use
uv tool installonly when specifically requested by the user.
Type checking
Use uv check to type check a uv project with ty. It syncs the project
environment and uses the version of ty in uv.lock when ty is a project
dependency or a member of the dev dependency group. Otherwise, uv selects a
compatible version of ty.
For a PEP 723 script, use uv check --script script.py to check it with its
inline dependencies.
Pip interface
Use when: Legacy workflows with requirements.txt or manual environment
management, no uv.lock present.
Key commands:
uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt
# Platform independent resolution
uv pip compile --universal requirements.in -o requirements.txt
Important:
- Don't use the pip interface unless clearly needed.
- Don't introduce new
requirements.txtfiles. - Prefer
uv initfor new projects.
Migrating from other tools
pyenv → uv python
pyenv install 3.12 → uv python install 3.12
pyenv versions → uv python list --only-installed
pyenv local 3.12 → uv python pin 3.12
pyenv global 3.12 → uv python install 3.12 --default
pipx → uvx
pipx run ruff → uvx ruff
pipx install ruff → uv tool install ruff
pipx upgrade ruff → uv tool upgrade ruff
pipx list → uv tool list
pip and pip-tools → uv pip
pip install package → uv pip install package
pip install -r req.txt → uv pip install -r req.txt
pip freeze → uv pip freeze
pip-compile req.in → uv pip compile req.in
pip-sync req.txt → uv pip sync req.txt
virtualenv .venv → uv venv
Common patterns
Don't use pip in uv projects
# Bad
pip install requests
# Good
uv add requests
Don't run python directly
# Bad
python script.py
# Good
uv run script.py
# Bad
python -c "..."
# Good
uv run python -c "..."
# Bad
python3.12 -c "..."
# Good
uv run --python 3.12 python -c "..."
Use uvx python@3.12 when you explicitly want a standalone interpreter.
Don't manually manage environments in uv projects
# Bad
python -m venv .venv
source .venv/bin/activate
# Good
uv run <command>
Documentation
For detailed information, read the official documentation:
The documentation links to specific pages for each of these workflows.
Sponsors
Details
- Marketplace
- astral-sh/claude-code-plugins
- Source
- plugins/astral
- Category
- Community
