Skip to main content

VHDL Style Guide

Project description

Coding style enforcement for VHDL.

Github Release PyPI Version Build Status Test Coverage Read The Docs Codacy


Update 04/22/2022

The Release 3.11.0 will include a change to comment indenting. Prior to this release comments were indented at the current indent level. This would result in comment indents being enforced like this:

architecture rtl of fifo is

  -- Define FIFO control signals
  signal wr_en : std_logic;
  signal rd_en : std_logic;

  -- Comment


Release 3.11.0 will employ a forward looking comment indent. The rationale being that comments are describing what comes next and therefore should be indented to match the code that comes next. The code snippet above will now be formatted as:

architecture rtl of fifo is

  -- Define FIFO control signals
  signal wr_en : std_logic;
  signal rd_en : std_logic;

-- Comment


With the comment – Comment matching the indent of the begin keyword.

There are existing rules in 3.10.0 which enforce this behavior, for example case_021. These will eventually be deprecated in a future release as they are no longer required.



Table of Contents


VSG was created after participating in a code review where a real issue in the code was masked by a coding style issue. A finding was created for the style issue, while the real issue was missed. When the code was re-reviewed, the real issue was discovered.

Depending on your process, style issues can take a lot of time to resolve.

  1. Create finding/ticket/issue

  2. Disposition finding/ticket/issue

  3. Fix

  4. Verify fix

Spending less time on style issues leaves more time to analyze the substance of the code. This ultimately reduces the amount of time performing code reviews. It also allows reviewers to focus on the substance of the code. This will result in a higher quality code base.

Key Benefits

  • Define VHDL coding standards

  • Makes coding standards visible to everyone

  • Improve code reviews

  • Quickly bring code up to current standards

VSG allows the style of the code to be defined and enforced over part or the entire code base. Configurations allow for multiple coding standards.

Key Features

  • Command line tool

    • integrate into continuous integration flow with JUnit output

  • Reports and fixes issues found

    • whitespace

      • horizontal

      • vertical

    • upper and lower case

    • keyword alignments

    • etc…

  • Fully configurable rules via JSON or YAML configuration file

    • Disable rules

    • Alter behavior of existing rules

  • Localize rule sets

    • Create your own rules using python

    • Use existing rules as a template

    • Fully integrates into base rule set

  • Built in styles

    • Use existing style or create your own

Known Limitations

VSG is a continual work in progress. As such, this version has the following known limitations:

  • Parser will not process configurations

  • Parser will not process embedded PSL

  • Parser will not process VHDL 2019


You can get the latest released version of VSG via pip.

pip install vsg

The latest development version can be cloned…

git clone

…and then installed locally…

python install


VSG is a both a command line tool and a python package. The command line tool can be invoked with:

$ vsg
usage: VHDL Style Guide (VSG) [-h] [-f FILENAME [FILENAME ...]] [-lr LOCAL_RULES] [-c CONFIGURATION [CONFIGURATION ...]] [--fix]
                              [-fp FIX_PHASE] [-j JUNIT] [-js JSON] [-of {vsg,syntastic,summary}] [-b] [-oc OUTPUT_CONFIGURATION]
                              [-rc RULE_CONFIGURATION] [--style {indent_only,jcl}] [-v] [-ap] [--fix_only FIX_ONLY] [-p JOBS]

Analyzes VHDL files for style guide violations. Reference documentation is located at:

optional arguments:
  -h, --help            show this help message and exit
  -f FILENAME [FILENAME ...], --filename FILENAME [FILENAME ...]
                        File to analyze
  -lr LOCAL_RULES, --local_rules LOCAL_RULES
                        Path to local rules
                        JSON or YAML configuration file(s)
  --fix                 Fix issues found
  -fp FIX_PHASE, --fix_phase FIX_PHASE
                        Fix issues up to and including this phase
  -j JUNIT, --junit JUNIT
                        Extract Junit file
  -js JSON, --json JSON
                        Extract JSON file
  -of {vsg,syntastic,summary}, --output_format {vsg,syntastic,summary}
                        Sets the output format.
  -b, --backup          Creates a copy of input file for comparison with fixed version.
                        Write configuration to file name.
                        Display configuration of a rule
  --style {indent_only,jcl}
                        Use predefined style
  -v, --version         Displays version information
  -ap, --all_phases     Do not stop when a violation is detected.
  --fix_only FIX_ONLY   Restrict fixing via JSON file.
  -p JOBS, --jobs JOBS  number of parallel jobs to use, default is the number of cpu cores
  --debug               Displays verbose debug information

Here is an example output running against a test file:


All documentation for VSG is hosted at read-the-docs.


I welcome any contributions to this project. No matter how small or large.

There are several ways to contribute:

  • Bug reports

  • Code base improvements

  • Feature requests

  • Pull requests

Please refer to the documentation hosted at read-the-docs for more details on contributing.

Project details

Release history Release notifications | RSS feed

Download files

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

Source Distribution

vsg-3.12.2.tar.gz (274.3 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page