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 -lr (VSG's Python rule plugins) is not supported. 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

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.

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:
Latest release

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.8.0.tar.gz (250.8 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.8.0-py3-none-win_arm64.whl (1.8 MB view details)

Uploaded Python 3Windows ARM64

vsg_rs-0.8.0-py3-none-win_amd64.whl (1.9 MB view details)

Uploaded Python 3Windows x86-64

vsg_rs-0.8.0-py3-none-musllinux_1_2_x86_64.whl (2.0 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

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

Uploaded Python 3musllinux: musl 1.2+ ARM64

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

Uploaded Python 3manylinux: glibc 2.28+ x86-64

vsg_rs-0.8.0-py3-none-manylinux_2_28_aarch64.whl (1.8 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ ARM64

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

Uploaded Python 3macOS 11.0+ ARM64

vsg_rs-0.8.0-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.8.0.tar.gz.

File metadata

  • Download URL: vsg_rs-0.8.0.tar.gz
  • Upload date:
  • Size: 250.8 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.8.0.tar.gz
Algorithm Hash digest
SHA256 979c115eb247048853867931b3e77134779f7fb9e805ca9d64e621be1d535b39
MD5 337dc27dfbcf0a3858c807ade0279c2e
BLAKE2b-256 e6e5489e08dfcae4e37ac12c651dcfb26ed79f40838c19d5a8b29d6a07dd3c69

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.8.0.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.8.0-py3-none-win_arm64.whl.

File metadata

  • Download URL: vsg_rs-0.8.0-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.8.0-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 92ee8dfe94992f4fc68c6ee2c67f52e06bc945600f6487278fb824e61fe4155e
MD5 4c320567a0eb8bf8223ccd57fa6d93ee
BLAKE2b-256 22ae99bc476d53024b1760f85741b435741d69918c96f216f63e93ddbded367c

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.8.0-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.8.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: vsg_rs-0.8.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 1.9 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.8.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 2a03c95e6b5113136bb61d7b974672b004caa42372aba3f57cd8d03e8ea44a78
MD5 6daa03b70a5fbacdd81bd9b6b55c88da
BLAKE2b-256 69f2b648e807b1a64cae67342d1b8d214c26ee24e97c9aad093c7175c40b8b01

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.8.0-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.8.0-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.8.0-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 a8cf2aefb941b51ae7db1f2cd41b76d85191f469365166287eb3cc2d50ca7866
MD5 7065b34ae60471995f223b57b89da826
BLAKE2b-256 4899a44b42578f91e37b7ee7576b60907e1bece5f9349bc29d8d22dc36c6ddb1

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.8.0-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.8.0-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.8.0-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 9bf89eb69b2f737303db77adc2dbf65f6836ac2f9565a3e1a7f60e9e47d52cac
MD5 5303b04b3588f36c98f149d1216e11a9
BLAKE2b-256 8e7a1fa22bc585a939c0bb3d7f01c0e6485f8c3be8a734cd7ac0921c970ceb7e

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.8.0-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.8.0-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.8.0-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 7c383a9aa4702ce3ccae0ae90fda1d5c3c328c0ccc831f016dd9ddfa30ce1649
MD5 2bcc52aa949b7e3c23fa5ffd24f5408c
BLAKE2b-256 4ee496d043b9e458abe4a4bcd82bec44e7e4b4c6acb361e6d4335302bce5ef5b

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.8.0-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.8.0-py3-none-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.8.0-py3-none-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 f5c1efe80873fbc06f457e40e41cf9d244f6b68b99b380bc68d19c236c4bf5d9
MD5 db0c461372534a089b5db90f66a26173
BLAKE2b-256 59b06348c5338aa2ad8747e735cdeeafb1302fbbe2db42ef70f24295f466a857

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.8.0-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.8.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.8.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 18f1c634ff85cc947daac45e6ed88a0c85a839744cb541f6017b2c0eefd90bbc
MD5 26ac3cd57ec5c6d80d2043be0bae7091
BLAKE2b-256 bfebf867e9f53fe13fdd76bea9aee8f021d5901e7dd8432c879eb9994e036e3f

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.8.0-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.8.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for vsg_rs-0.8.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 1eee29319469b154dd40a4d9029aecbeb9954ecf0324fd558daaefd4fe85f13b
MD5 c2c8c963d753d36b364437834bf6f8e7
BLAKE2b-256 3d0b79f0ab66848d17017bb08fa33ecaae68bb66a9173ca6bcbf4a04d56e0469

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsg_rs-0.8.0-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

This release

0.8.0 This release

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