vsg-rs

A fast Rust-native VHDL formatter and style checker with the command line, rules and configuration of VSG.

vsg-rs is an independent Rust implementation of a VHDL formatter and style checker that aims for compatibility with the rules and configuration of the VHDL Style Guide (VSG). It is not affiliated with, endorsed by, or maintained by the VHDL Style Guide project or its maintainers.

vsg-rs was inspired by the VHDL Style Guide (VSG) project by Jeremiah Leary and contributors. vsg-rs contains no VSG code; VSG is used only as a behavioural reference.

Status: beta. vsg-rs is tested against more than 11,000 real-world files. 192 VSG rules are implemented as rules with fixes (structure, identifier case and consistency, naming, comments, length_001). The other 779 rules are layout rules covered by the formatter: whitespace, indentation (including indent.tokens), blank lines, alignment, keyword case and line structure. Expect layout changes before 1.0.

Why

  • Drop-in for VSG. Same arguments, same configuration files, same report formats and exit codes. Existing scripts and CI jobs keep working.
  • One phase. All violations are reported at once, and --fix fixes everything in one run: no repeated --fix runs, no rule-order dependencies.
  • A real formatter. Source is parsed once into a lossless syntax tree and printed in one canonical layout, like rustfmt or Black. Running --fix twice changes nothing.
  • Long lines are folded, not just reported. Calls, maps, aggregates, expressions, conditions, declarations and signatures fold at structural boundaries (line folding).
  • Safe to run on save. Formatted output is re-parsed and must contain exactly the same tokens and comments; fixed output must parse. Files with syntax errors are never changed. Fixes that VSG does not apply by default, or that could break code, need --unsafe_fixes.
  • Fast. A typical file takes a few milliseconds; real-world VHDL is checked at about 3.4 MB/s on one core, and files are processed in parallel worker processes (performance).

Installation

pip install vsg-rs            # Linux, Windows and macOS wheels, Python 3.10+ (or: uv tool install vsg-rs)
cargo install --path .        # from source (Rust 1.95 or newer)

Standalone binaries for Linux (static, x86_64 and aarch64), Windows (x64 and arm64) and macOS (arm64 and x86_64) are attached to each GitHub release, with a SHA256SUMS file.

Usage

vsg-rs takes VSG's arguments:

vsg-rs -f src/fifo.vhd src/fifo_pkg.vhd      # report violations
vsg-rs src/*.vhd                             # file names can also be given without -f
vsg-rs -f src/*.vhd --fix                    # fix and format the files in place
vsg-rs -f src/*.vhd --fix -b                 # ... keeping a .bak copy of each changed file
vsg-rs -f src/*.vhd -c vsg.yaml              # with a VSG configuration file
vsg-rs -f src/*.vhd -of summary -js report.json -j junit.xml --quality_report gl.json
vsg-rs --stdin < src/fifo.vhd                # read from stdin
vsg-rs -rc entity_015                        # the configuration of one rule
vsg-rs -oc effective.json                    # the whole effective configuration
vsg-rs --style indent_only -f src/*.vhd --fix  # only re-indent
vsg-rs --recursive src                       # every .vhd/.vhdl file below src

As in VSG, files can also be listed in the configuration (file_list), and directories are not searched unless --recursive is given. The exit code is 0 when no error-severity violations were found and 1 otherwise.

What is reported

  • Rule violations, with VSG's rule ids and solution texts, in VSG's console layout (-of vsg, the default), as -of syntastic lines or as an -of summary.
  • Layout violations: every place where --fix would change the layout (indentation, spacing, line breaks, blank lines, trailing whitespace, keyword case, comment columns), under the VSG rule that reports it. vsg-rs decides the whole layout at once; the rule for each kind of change was learned by comparing with VSG on real code. Changes without a known VSG rule are reported as format.

When several files are checked together, uses of names declared in another file's package, or of another file's entity ports and generics, are checked for consistent capitalization too.

Fixes

--fix applies the fixes VSG applies by default and then formats the file. Rules that VSG does not fix by default (for example adding a missing port mode, port_023, or removing a signal's default value, signal_007) are left alone unless their configuration sets fixable: true or --unsafe_fixes is given. --fix_only FILE limits fixing to the listed rules and lines, as in VSG.

Additions to VSG's command line

Option Meaning
--unsafe_fixes with --fix, also apply fixes VSG does not apply by default; they may change behaviour or remove information, so review the result
--diff with --fix, print a unified diff instead of changing files
--stdin_filename PATH name of the --stdin input, used to find the configuration and in reports
--range START:END with --stdin --fix, change only these lines (1-based)
--sarif FILE write a SARIF 2.1.0 report (GitHub code scanning)
--list_rules list every VSG rule and how vsg-rs handles it
--recursive check the .vhd / .vhdl files in directories given as inputs, and in their subdirectories

With --stdin --fix, the fixed source is written to stdout and the report to stderr (VSG 3.35 cannot fix stdin). -fp and -ap are accepted and have no effect, --force_fix has no effect (files with syntax errors are never changed), and local rules (-lr, VSG's Python rule plugins) are run by an installed VSG (see below). See compatibility for the details.

Configuration

Configuration files use VSG's format (YAML or JSON) and are passed with -c; later files override earlier ones. Without -c, vsg-rs uses the nearest vsg-rs.yaml / .vsg-rs.yaml (or .json) next to the first input or in a parent directory, which VSG itself ignores.

rule:
  global:
    indent_style: spaces
    indent_size: 2
  group:
    case::name:
      case: lower
  length_001:
    length: 100
  process_016:
    disable: true
  port_023:
    fixable: true          # also add missing port modes with --fix
indent:
  tokens:
    case_statement_alternative:
      when_keyword: {after: current, token: current}
file_rules:
  legacy/**/*.vhd:
    rule:
      length_001:
        disable: true

Local rules (-lr DIR or local_rules: DIR) are VSG Python plugins, so vsg-rs runs them with an installed VSG (vsg on the path, or the command in VSG_RS_VSG, for example uvx --from vsg==3.35.0 vsg) with all built-in rules disabled, and merges their findings; with --fix, their fixes are applied first.

Blank-line, alignment, keyword-case and indentation rules configure the formatter (formatting). Formatting can be switched off for a region with -- vsg-rs: fmt off / -- vsg-rs: fmt on; VSG's -- vsg_off [rule ...] / -- vsg_on comments suppress rules (and, without rule names, formatting).

Editor integration

Configure your editor to pipe the buffer through vsg-rs --stdin --fix --stdin_filename <path> (add --range START:END to format selected lines). With exit code 0 the buffer is replaced with stdout; otherwise stdout is empty, stderr explains why, and the buffer should be left unchanged. See editor integration for VS Code, Neovim, Helix and Emacs.

GitHub Action

vsg-rs is also a GitHub Action. Add a workflow such as .github/workflows/vhdl-style.yml:

name: VHDL style
on:
  push:
    branches: [main]
  pull_request:

jobs:
  vsg:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # only needed for sarif-upload
    steps:
      - uses: actions/checkout@v5
      - uses: ru551n/vsg-rs@v0.9.3
        with:
          args: -c vsg.yaml --recursive src   # any vsg-rs arguments
          sarif-upload: true                  # optional: code scanning alerts

The action downloads the vsg-rs release of its own tag (checked against SHA256SUMS) and runs vsg-rs with args. Then:

  • Annotations: each violation is shown on its line in the pull request's Files changed tab and in the run (GitHub shows at most 10 errors and 10 warnings per step).
  • Job summary: a table of violations per rule on the run page.
  • Code scanning (sarif-upload: true): violations become alerts under Security → Code scanning. Pull requests get review comments for the alerts they introduce; alerts close when fixed. Free for public repositories. Running the workflow on pushes to the default branch gives pull requests a baseline to compare with.
  • Result: the step fails when vsg-rs reports error-severity violations (fail-on-violations: false only reports them).

Other inputs: version (a release tag or latest), working-directory, annotations: false, and token. Outputs: exit-code, sarif-file and version. Linux, Windows and macOS runners are supported. To fix the reported violations locally, run the same arguments with --fix. See GitHub Action for details, and ru551n/vhdl-ai-test#7 for an example pull request.

Python

The wheels install the vsg-rs executable. python -m vsg_rs ... runs it too, and vsg_rs.find_vsg_rs_bin() returns its path.

Documentation

Development

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo run --release --example corpus -- --width 80 path/to/vhdl   # stability and overflow report
FIX=1 cargo run --release --example corpus -- path/to/vhdl         # the same for --fix (FIX=unsafe: --unsafe_fixes; CONFIG=file)
cargo run --release --example bench                                # timing on generated inputs
python scripts/compare_vsg.py FILE...                              # findings per rule, vsg-rs vs VSG 3.35
python scripts/learn_layout_rules.py FILE...                       # relearn src/layout_rules.json
python scripts/gen_spacing_rules.py VSG_CHECKOUT/docs              # regenerate src/spacing_rules.json
UPDATE_EXPECT=1 cargo test --test golden                           # re-bless golden files (review the diff)

The library (vsg_rs) can also be used directly: Parsed::new, format_parsed, fix_with, rules::check_with and the range variants format_range / fix_range.

License

vsg-rs is licensed under either of Apache License, Version 2.0 or MIT license, at your option. Third-party dependencies are listed in THIRD_PARTY_LICENSES.md. The VHDL parser, vhdl_syntax from the rust_hdl project, is MPL-2.0 and is used as an unmodified dependency.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in vsg-rs, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Project links

Data verified by PyPI on Sep 17, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.9.6)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ru551n from gravatar.com ru551n

GitHub Statistics

Data verified by PyPI on Sep 17, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT OR Apache-2.0
View SPDX License List

Requires

Python >=3.10

Tags

vhdl formatter linter vsg fpga

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vsg_rs-0.9.3.tar.gz (262.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

vsg_rs-0.9.3-py3-none-win_arm64.whl (1.8 MB view details)

Uploaded Python 3Windows ARM64

vsg_rs-0.9.3-py3-none-win_amd64.whl (2.0 MB view details)

Uploaded Python 3Windows x86-64

vsg_rs-0.9.3-py3-none-musllinux_1_2_x86_64.whl (2.1 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

vsg_rs-0.9.3-py3-none-musllinux_1_2_aarch64.whl (1.9 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

vsg_rs-0.9.3-py3-none-manylinux_2_28_x86_64.whl (2.0 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

vsg_rs-0.9.3-py3-none-manylinux_2_28_aarch64.whl (1.9 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ ARM64

vsg_rs-0.9.3-py3-none-macosx_11_0_arm64.whl (1.8 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

vsg_rs-0.9.3-py3-none-macosx_10_12_x86_64.whl (1.9 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file vsg_rs-0.9.3.tar.gz.

File metadata

  • Download URL: vsg_rs-0.9.3.tar.gz
  • Upload date:
  • Size: 262.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vsg_rs-0.9.3.tar.gz
Algorithm Hash digest
SHA256 7691136ebaa6126d2ed4bfa7d0406bb8ef7a559267201241dc2e4cb5eab8c428
MD5 f985a6f0adb0e487b022949e64ccc75d
BLAKE2b-256 a7982a1ba247b0d799a96fc2a510ca5604b95cabae912f552b02ec8d7b0cdeb9

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.9.3.tar.gz:

Publisher: release.yml on ru551n/vsg-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsg_rs-0.9.3-py3-none-win_arm64.whl.

File metadata

  • Download URL: vsg_rs-0.9.3-py3-none-win_arm64.whl
  • Upload date:
  • Size: 1.8 MB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vsg_rs-0.9.3-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 f1957aedf82e2d24c5fa12f22fb4b70a51bdf0880829752e484970b5fa09ed91
MD5 a7a734c218e82ceccdfcc4c6806de8b0
BLAKE2b-256 c106b10de153d10e2a2f118de7fed36ee7bd324f37da1774e8d93e17fb6263aa

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.9.3-py3-none-win_arm64.whl:

Publisher: release.yml on ru551n/vsg-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsg_rs-0.9.3-py3-none-win_amd64.whl.

File metadata

  • Download URL: vsg_rs-0.9.3-py3-none-win_amd64.whl
  • Upload date:
  • Size: 2.0 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vsg_rs-0.9.3-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 f5626442532f22e6337b33e6592c549e993962a0939e5fe024fe7c7349c8124d
MD5 b33e0dc1f462b795b0d3151d8458fa83
BLAKE2b-256 78027b5397b0cc8ba720cc3a3d07549d4b9bee16facbdee047b30cf8aa8f821a

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.9.3-py3-none-win_amd64.whl:

Publisher: release.yml on ru551n/vsg-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsg_rs-0.9.3-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.9.3-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 e92b4eed0f4389b05792e63c9d379c6502e30ed6f5b91ad76480f54f348cfabb
MD5 8d9d1a54c4b9ef655d72137989451e5a
BLAKE2b-256 cd089c974fda579ccfd3ce50c69368c9f32ec185f621752ba0d020ae02eabe11

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.9.3-py3-none-musllinux_1_2_x86_64.whl:

Publisher: release.yml on ru551n/vsg-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsg_rs-0.9.3-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.9.3-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 20a851832097780234ad875eccb92b838233c997c3210200c547cde2ca799130
MD5 5102bac5e4dbc5ff9051e5340d279ba4
BLAKE2b-256 5e899fa7e60c0f0a7d50dc6f02ae1a3fd1a0b8945f6aad1db179c2b82196e4ed

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.9.3-py3-none-musllinux_1_2_aarch64.whl:

Publisher: release.yml on ru551n/vsg-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsg_rs-0.9.3-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.9.3-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 965f5c9c476a38de316bd27dc76cacfb86217dd69a53afca39b1eedfd4d0d7de
MD5 796b0c1086bc8615e1d2a6391d574a3a
BLAKE2b-256 1c7c5f22ca5b7a77dd413bac2a8962ad7d4a2fc7a3aebfafc1332e6e7acac436

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.9.3-py3-none-manylinux_2_28_x86_64.whl:

Publisher: release.yml on ru551n/vsg-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsg_rs-0.9.3-py3-none-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.9.3-py3-none-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 1ea3a03c1d26121dbfd7d0ce1c382bc235e186c78b259a7834839608cee33a8b
MD5 93997559e21fc214e33ec4bd35e53ab4
BLAKE2b-256 546d12b7393685e317e05c3c7923658f2e25b3a86f4756fd59489091735362f9

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.9.3-py3-none-manylinux_2_28_aarch64.whl:

Publisher: release.yml on ru551n/vsg-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsg_rs-0.9.3-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.9.3-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ccafeb11976495a9ca4960f862dd66f35abb7d6c777a8a0e5405cc140d032aee
MD5 c739d06223ceb8e174f8e1a8239cd309
BLAKE2b-256 c0837095a1eb79d5f373df1d67c8a1866c42303285af087e09d18e0315db7492

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.9.3-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on ru551n/vsg-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsg_rs-0.9.3-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.9.3-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 82f9831e753a02223c1f738f14baa5b429c9c9a4d573f850b855e6c8de3cf5bf
MD5 f42837c9e9d5df412e3186eec76b9475
BLAKE2b-256 831f4882e3dd64293d565b857ac1efb3c13936134357452f57a72951fe37725f

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.9.3-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on ru551n/vsg-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.9.6

5 files

0.9.5

9 files

0.9.4

9 files

This release

0.9.3 This release

9 files

0.9.2

9 files

0.9.1

9 files

0.9.0

9 files

0.8.0

9 files

0.7.0

9 files

0.6.0

7 files

0.5.0

7 files

0.4.0

7 files

0.3.0

7 files

0.2.0

7 files

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