Stop Writing Compose Files by Hand: Let Composerize Do It for You

You've got a docker run command that works. Maybe you copied it from a README, maybe you've been tweaking it for weeks. Now you want to move it into a compose file—and suddenly you're translating flags into YAML by hand, hoping you didn't mangle the volume syntax. Composerize exists to make that translation unnecessary. It takes a docker run command and turns it into a compose.yaml file, and it can even merge the result into a compose file you already have.

What It Does

Composerize is a tool that converts docker run commands into Docker Compose configuration. It's available as a website at composerize.com, as a CLI you can install through npm, and as a Node.js library you can call from your own code. The core operation is straightforward: give it a docker run command, get back a compose file.

The library side is where it gets more flexible. You can pass in an existing compose configuration as a string and Composerize will merge your new service into it rather than producing a standalone file. You can also target a specific compose format version—v2x, v3x, or latest for the Compose Specification—and control the indentation level of the output.

The project also points to a couple of related tools in the same family: Decomposerize, which goes the other direction (compose file back to docker run), and Composeverter, which converts between Docker Compose file formats. There's a Docker image available that bundles the composerize, decomposerize, and composeverter websites together, credited to a contributor named Oaklight.

Why It's Cool

The merge feature is the real differentiator here. Plenty of tools can spit out a compose file from a run command, but how often do you actually start from a blank slate? More often you've got an existing compose.yaml with a few services already defined, and you want to add one more without hand-editing YAML and getting the indentation wrong. Passing your existing config as a second argument and getting back a merged result is genuinely useful—and it's not something you'd expect from a simple converter.

• Version targeting is thoughtful. Docker Compose has gone through several format generations, and what's valid in one isn't necessarily valid in another. Being able to specify v2x, v3x, or latest means you're not stuck with output that doesn't match the rest of your stack.

• Three ways to use it. The web interface is fine for a one-off. The CLI is what you'll want if you're doing this regularly. And the Node.js API means you can wire it into a script or a build step if you're generating compose files programmatically.

• Indentation control. It sounds minor, but if you're merging into a file that uses two-space indents and the tool defaults to four, you've got a diff full of noise. Being able to set the indent level keeps your output clean.

• It plays well with the ecosystem. Rather than being a one-trick converter, the project acknowledges the related problems—decomposing and format converting—and links to tools that solve them. That's a sign the maintainers understand the space rather than just building the one thing they needed.

How to Try It

The fastest way is the web interface at composerize.com—paste your docker run command and copy the output.

For the CLI, install it globally through npm:

npm install composerize -g

Then run it against any docker run command:

composerize docker run -p 80:80 -v /var/run/docker.sock:/tmp/docker.sock:ro --restart always --log-opt max-size=1g nginx

Run composerize --help to see the available options.

To use it as a library, install it in your project:

npm install composerize

Then call it with a run command:

const composerize = require('composerize');

const dockerRunCommand = 'docker run -d -p 8080:80 --name my-web-app nginx:latest';
const composeConfig = composerize(dockerRunCommand);

console.log(composeConfig);

If you want to merge with an existing compose file, pass that config as the second argument. To target a specific compose version, pass 'v2x', 'v3x', or 'latest' as the third. To set indentation, pass a number as the fourth.

The source is at github.com/composerize/composerize. If you want to contribute, fork the repo, install dependencies with yarn, make your changes, then run make build and make test.

Final Thoughts

Composerize solves a narrow problem well. If you're converting docker run commands to compose files occasionally, the website will do. If you're doing it often—or you need to merge into existing configs or generate compose files as part of a workflow—the CLI and Node.js API are where the value is. It's not trying to be a full compose management platform, and it doesn't need to be. For developers who move between docker run and compose regularly, it removes a tedious translation step that's easy to get wrong. Worth keeping in your toolkit.