A command-line tool for validating and enforcing best practices in Docker Compose files.
Note: Docker Compose configurations vary greatly between different projects and setups. While DCLint is stable, there may be edge cases or unique setups that cause issues. If you encounter any problems or have suggestions, please feel free to open an issue or submit a pull request. Your feedback is highly appreciated!
Docker Compose Linter (DCLint) is a utility designed to analyze, validate and fix Docker Compose files. It helps identify errors, style violations, and potential issues, ensuring your configurations are robust, maintainable, and free from common pitfalls.
You can explore the online version here: https://dclint-website.vercel.app/ (thanks to BenRoe for the implementation). Note that this site is not official. I have no control over it and take no responsibility for its contents, uptime, or any potential issues.
You can install Docker Compose Linter globally or use it directly with npx.
Note: DCLint requires Node.js version 20.19.0 or higher.
To install it globally:
npm install --g dclint
And then run by command:
dclint .
If you prefer not to install it globally, you can run the linter directly using npx:
npx dclint .
This command will lint your Docker Compose files in the current directory.
To lint a specific Docker Compose file or a directory containing such files, specify the path relative to your project directory:
npx dclint /path/to/docker-compose.yml
To lint all Docker Compose files in a specific directory, use the path to the directory:
npx dclint /path/to/directory
In this case, dclint will search the specified directory for files matching the following pattern
/^(docker-)?compose.*\.ya?ml$/.
It will handle all matching files within the directory and, if recursive search is enabled, also in any subdirectories.
Files and directories like node_modules, .git, or others specified in the exclusion list will be ignored.
To display help and see all available options:
npx dclint -h
For more details about available options and formatters, please refer to the CLI Reference and Formatters Reference.
First, pull the Docker image from the repository:
docker pull zavoloklom/dclint
To lint your Docker Compose files, use the following command. This command mounts your current working directory
${PWD} to the /app directory inside the container and runs the linter:
docker run -t --rm -v ${PWD}:/app zavoloklom/dclint .
If you want to lint a specific Docker Compose file or a directory containing such files, specify the path relative to your project directory:
docker run -t --rm -v ${PWD}:/app zavoloklom/dclint /app/path/to/docker-compose.yml
docker run -t --rm -v ${PWD}:/app zavoloklom/dclint /app/path/to/directory
To display help and see all available options:
docker run -t --rm -v ${PWD}:/app zavoloklom/dclint -h
For more information about available options and formatters, please refer to the CLI Reference and Formatters Reference.
The dclint can be integrated directly into your JS code, allowing you to run linting checks programmatically and
format the results as desired. Below are examples of how to use dclint as a library in both CommonJS and ES module
formats.
First you need to install it:
npm install --save-dev dclint
const { DCLinter } = require('dclint');
(async () => {
const linter = new DCLinter();
const lintResults = linter.lintFiles(['.'], true);
const formattedResults = await linter.formatResults(lintResults, 'stylish');
console.log(formattedResults);
})();
import { DCLinter } from 'dclint';
const linter = new DCLinter();
const lintResults = linter.lintFiles(['.'], true);
const formattedResults = await linter.formatResults(lintResults, 'stylish');
console.log(formattedResults);
Docker Compose Linter includes set of rules to ensure your Docker Compose files adhere to best practices. Detailed documentation for each rule and the errors that can be detected by the linter is available here:
DCLint uses the yaml library for linting and formatting Docker Compose files. This ensures that any configuration files you check are compliant with YAML standards. Before any rule checks are applied, two important validations are performed, which cannot be disabled - YAML Validity Check and Docker Compose Schema Validation.
You can disable specific linting rules or all rules in your Docker Compose files using comments. These comments can be used either to disable rules for the entire file or for individual lines. For detailed instructions on how to use these comments, check out the full documentation here: Using Configuration Comments.
Docker Compose Linter provides support for YAML anchors specifically during schema validation, which enables the reuse of configuration sections across different services for cleaner and more maintainable files.
However, note that anchors are neither validated by individual linting rules nor automatically fixed when using the
--fix flag.
When multiple anchors are required in a Docker Compose file, use the following syntax:
x-anchor1: &anchor1
ports:
- 80
x-anchor2: &anchor2
ports:
- 81
services:
image: image
<<: [ *anchor1, *anchor2 ]
This approach, which combines anchors in a single << line, is preferable to defining each anchor on separate lines (
e.g., << : *anchor1 followed by << : *anchor2).
More information on YAML merge syntax is available in the official YAML documentation and in known issue with Docker Compose.
For an example of anchor usage, refer to the sample Compose file in tests/mocks/docker-compose.anchors.yml.
DCLint allows you to customize the set of rules used during linting to fit your project's specific needs. You can configure which rules are applied, their severity levels, and additional behavior settings using a configuration file.
Note: Command-line options always take precedence over values defined in the configuration file.
DCLint supports flexible configuration options through the use of cosmiconfig. This means you can use various formats to configure the linter, including JSON, YAML, and JavaScript files.
For example:
.dclintrc (JSON, YAML, or JavaScript)dclint.config.js (JavaScript)dclint key inside your package.jsonHere is an example of a configuration file using JSON format:
{
"rules": {
"no-version-field": 0,
"require-quotes-in-ports": 1,
"services-alphabetical-order": 2
},
"quiet": false,
"debug": true,
"exclude": [
"tests"
]
}
0 - Disabled, 1 - Warning, 2 - Error).true.true.To enable editor autocompletion in a JSON configuration file, add a $schema property. If you have installed dclint:
{
"$schema": "./node_modules/dclint/schemas/linter-config.schema.json"
}
Otherwise:
{
"$schema": "https://raw.githubusercontent.com/zavoloklom/docker-compose-linter/refs/heads/main/schemas/linter-config.schema.json"
}
In addition to enabling or disabling rules, some rules may support custom parameters to tailor them to your specific needs. For example, the require-quotes-in-ports rule allows you to configure whether single or double quotes should be used around port numbers. You can configure it like this:
{
"rules": {
"require-quotes-in-ports": [
2,
{
"quoteType": "double"
}
]
}
}
In this example, the require-quotes-in-ports rule is enabled at the error level and configured to enforce double quotes around ports.
You can integrate DCLint into your GitHub Actions workflow to automatically lint Docker Compose files on every push or
pull request.
The official GitHub Action
docker-compose-linter/dclint-github-action provides
three variants:
| Variant | Action | Description |
|---|---|---|
| Base | docker-compose-linter/dclint-github-action | Runs dclint via npx (requires Node.js in the runner) |
| Docker | docker-compose-linter/dclint-github-action/docker-action | Runs dclint inside a Docker container (requires Docker in the runner) |
| Reviewdog | docker-compose-linter/dclint-github-action/reviewdog-action | Integrates dclint with reviewdog for inline annotations in pull requests |
name: Lint Docker Compose
on:
push:
branches:
- main
pull_request:
jobs:
dclint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker-compose-linter/dclint-github-action@v{$ACTION_VERSION}
with:
path: ./path-to-compose-files/
recursive: true
For more details and advanced configuration, see the dclint-github-action repository and example-github-action repository.
Automate linting as part of your CI/CD pipeline by adding the Docker run command to your pipeline script or by adding DCLint as CI Component.
This ensures that your Docker Compose files are always checked for errors before deployment.
Use the Docker image directly:
lint-docker-compose:
image:
name: zavoloklom/dclint:alpine
entrypoint: [ '' ]
script:
- /bin/dclint . -r -f codeclimate -o gl-codequality.json
artifacts:
reports:
codequality: gl-codequality.json
Minimal working example of DCLint integration in GitLab CI, including widget output and failure handling: dclint/gitlab-ci-example.
Use the GitLab Component:
include:
- component: $CI_SERVER_FQDN/dclint/ci-component/dclint@v{$COMPONENT_VERSION}
Full reference for inputs, usage patterns, and advanced configuration: catalog/dclint/ci-component.
pre-commit hookDCLint can be used as a pre-commit hook to automatically lint your Compose files before
each commit.
To enable it, add the following to your .pre-commit-config.yaml:
repos:
- repo: https://github.com/docker-compose-linter/pre-commit-dclint
rev: v3.0.0 # Matches the dclint version, use the sha or tag you want to point at
hooks:
- id: dclint
# Optional: regex override for compose files
files: ^(docker-)?compose\.ya?ml$
# Optional: enable autofix on commit
args: [ --fix ]
For additional options and docker-based integration, see pre-commit-dclint.
MegaLinterDCLint can also be used as a MegaLinter plugin to integrate Compose file
linting into your CI pipelines.
For more details, see the plugin repository: mega-linter-plugin-dclint.
Consider these alternative tools for Docker Compose linting and validation:
And this tools for Docker Compose formatting and fixing:
If you encounter any issues or have suggestions for improvements, feel free to open an issue or submit a pull request.
If you'd like to contribute to this project, please read through the CONTRIBUTING.md file.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project, you agree to abide by its terms.
Thanks goes to these wonderful people (emoji keys explanation):
 Szymon Filipiak 💻 |  Ben Rexin 💻 📖 ⚠️ |  Ádám Liszkai 💡 |  Adam Vigneaux 💻 📖 |  Sebastian Weigand 💡 |  Jan Eil 💡 |  Mandy Schoep 💻 |
 Ben 💡 |  Wes Dean 💡 |
This project follows the all-contributors specification. Contributions of any kind welcome!
The changelog is automatically generated based on semantic-release and conventional commits.
See the CHANGELOG.md file for detailed lists of changes for each version.
This project is licensed under the MIT License. See the LICENSE file for more information.
If you find this repository helpful, kindly consider showing your appreciation by giving it a star ⭐.
If you have any questions or suggestions, feel free to reach out:
A detailed devlog and roadmap for DCLint is available on Patreon: patreon.com/c/zavoloklom
Also, you can support this project with a one-time donation or becoming a sponsor:
3.1.0 (2025-07-24)
FAQs
A command-line tool for validating and enforcing best practices in Docker Compose files.
The npm package dclint receives a total of 2,140 weekly downloads. As such, dclint popularity was classified as popular.
We found that dclint demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A flawed sandbox in @nestjs/devtools-integration lets attackers run code on your machine via CSRF, leading to full Remote Code Execution (RCE).
Product
Customize license detection with Socket’s new license overlays: gain control, reduce noise, and handle edge cases with precision.
Product
Socket now supports Rust and Cargo, offering package search for all users and experimental SBOM generation for enterprise projects.
