Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

A concrete syntax tree with AST-like properties for Python 3.5, 3.6, 3.7 and 3.8 programs.

Project description


A Concrete Syntax Tree (CST) parser and serializer library for Python

Documentation CircleCI CodeCov PYPI PYPI Download Notebook

LibCST parses Python 3.0, 3.1, 3.3, 3.5, 3.6, 3.7 or 3.8 source code as a CST tree that keeps all formatting details (comments, whitespaces, parentheses, etc). It’s useful for building automated refactoring (codemod) applications and linters.

LibCST creates a compromise between an Abstract Syntax Tree (AST) and a traditional Concrete Syntax Tree (CST). By carefully reorganizing and naming node types and fields, we’ve created a lossless CST that looks and feels like an AST.

You can learn more about the value that LibCST provides and our motivations for the project in our documentation. Try it out with notebook examples.

Example expression:

1 + 2

CST representation:

            value=' ',
            value=' ',

Getting Started

Examining a sample tree

To examine the tree that is parsed from a particular file, do the following:

python -m libcst.tool print <>

Alternatively, you can import LibCST into a Python REPL and use the included parser and pretty printing functions:

>>> import libcst as cst
>>> from libcst.tool import dump
>>> print(dump(cst.parse_expression("(1 + 2)")))

For a more detailed usage example, see our documentation.


LibCST requires Python 3.6+ and can be easily installed using most common Python packaging tools. We recommend installing the latest stable release from PyPI with pip:

pip install libcst


Start by setting up and activating a virtualenv:

git clone libcst
cd libcst
python3 -m venv ../libcst-env/  # just an example, put this wherever you want
source ../libcst-env/bin/activate
pip install --upgrade pip  # optional, if you have an old system version of pip
pip install -r requirements.txt -r requirements-dev.txt
# If you're done with the virtualenv, you can leave it by running:

We use isort and black to format code. To format changes to be conformant, run the following in the root:

tox -e autofix

To run all tests, you’ll need to install tox and do the following in the root:

tox -e py37

You can also run individual tests by using unittest and specifying a module like this:

python -m unittest libcst.tests.test_batched_visitor

See the unittest documentation for more examples of how to run tests.

We use Pyre for type-checking.

To set up pyre check environment:

  1. Copy the example Pyre config: cp .pyre_configuration.example .pyre_configuration.
  2. In the config file, add your venv site-packages dir to “search_path”. (e.g. add “/workspace/libcst-env/lib/python3.7/site-packages”) Note: venv dir must not be inside the libcst dir
  3. Remove installed LibCST and install from the source code:
pip uninstall -y libcst
pip install -e .

To verify types for the library, do the following in the root:

pyre check

To generate documents, do the following in the root:

tox -e docs


  • Advanced full repository facts providers like fully qualified name and call graph.


LibCST is MIT licensed, as found in the LICENSE file.

Privacy Policy and Terms of Use


  • Guido van Rossum for creating the parser generator pgen2 (originally used in lib2to3 and forked into parso).
  • David Halter for parso which provides the parser and tokenizer that LibCST sits on top of.
  • Zac Hatfield-Dodds for hypothesis integration which continues to help us find bugs.
  • Zach Hammer improved type annotation for Mypy compatibility.

Project details

Download files

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

Files for libcst, version 0.3.19
Filename, size File type Python version Upload date Hashes
Filename, size libcst-0.3.19-py3-none-any.whl (513.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size libcst-0.3.19.tar.gz (418.4 kB) File type Source Python version None Upload date Hashes View

Supported by

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