# composerize: turn a docker run command into a compose.yaml file

> composerize converts a docker run command into a Docker Compose service definition, and can merge the result into an existing compose.yaml. It ships as a CLI, a Node.js package and a website, and it is the right tool when you are pasting flags by hand.

**composerize/composerize** — 🏃→🎼  docker run asdlksjfksdf > docker-composerize up

- Repository: https://github.com/composerize/composerize
- Website: http://composerize.com
- Stars: 3,769 · Forks: 258
- Language: JavaScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/composerize-composerize

## What composerize converts, and for whom

The README states the goal plainly: composerize "Turns `docker run` commands into `compose.yaml` files and even merge with existing `compose.yaml`". That is a narrow job, and the narrowness is the point. A docker run invocation carries its configuration in flags: port mappings, bind mounts, restart policy, log options, environment variables. A Compose file carries the same configuration in YAML keys under a service name. Moving between the two by hand is mechanical work with a high chance of a typo, and composerize does the mechanical part.

The people who get value from it are the ones who copy a docker run line out of a README, a blog post or a colleague's shell history and want that container declared in a project file. It is also useful in the other direction of thought: you have a working command, you want to see what the equivalent Compose service looks like before you commit to running it under Compose. The project is not aimed at orchestrating clusters, and it does not inspect running containers. It reads a string and emits YAML.

## The conversion runs on the command string, not on your Docker daemon

The repository is a JavaScript monorepo. package.json declares workspaces over packages/**, and the Makefile drives the build with yarn lerna exec make build and the tests with yarn lerna exec make test. The published npm package is the converter; the website at composerize.com is a separate package in the same tree, which is why the README can offer both a CLI and a browser form for the same operation.

The public entry point is a function that takes the docker run command as its first argument. The README shows a second argument for merging with an existing Compose file, a third for the target Compose version, and a fourth for indentation. The version parameter accepts 'v2x', 'v3x' or 'latest', where 'latest' targets the Compose Specification. That matters because the schema changed between generations: what is valid under v2x is not always what the current Compose Specification expects, and the converter will not silently upgrade a file for you if you ask for the older target.

Because the input is a string, the converter only knows what the command line contains. It cannot discover that the image you referenced has a newer tag, and it cannot see environment variables that were set in your shell rather than passed with -e. The output is a faithful transcription of the flags, nothing more.

## Installing composerize and converting your first docker run command

The README gives the global install path first. The package name is composerize, and the binary is also called composerize, so once npm finishes you can invoke it directly from your shell.

```bash
npm install composerize -g
```

With the CLI on your PATH, pass the docker run command as arguments. The README's own example includes a socket bind mount and a log option, which is exactly the kind of command where hand-writing the YAML is tedious.

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

You should see a compose.yaml document on stdout with a single service whose image is nginx, a ports entry for 80:80, a volumes entry for the socket with the ro suffix preserved, a restart value of always, and a logging block carrying max-size. The README points to composerize --help for the remaining options, so check that output rather than guessing at flags.

If you would rather call it from code, the package exports a function. The README's Node.js example passes a command with a name and a tag and logs the result.

```javascript
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);
```

Merging is the second argument. Pass an existing Compose document as a string and the converted service is added to it, which is how you fold a one-off docker run line into a file that already declares other services. The third and fourth arguments, 'v2x', 'v3x' or 'latest' and an indentation level, control the shape of the emitted YAML.

## Where the converter stops being the right tool

The input is a single command line, so anything that is not on that line is invisible. A container started with docker run and then modified at runtime, or a service whose real configuration lives in a separate env file, will not be reconstructed. The README does not document reading a running container's inspect output, and the project's own description frames it as a converter rather than a discovery tool. If you need to describe a container that is already running, that is a different problem.

Merge behaviour is the second sharp edge. Merging writes the converted service into a Compose document you supply, and the README does not document how name collisions between the new service and an existing one are resolved. Treat the merge as an additive operation and inspect the result before using it. The README also does not document rollback, so keep the original file in version control rather than overwriting it in place.

Version targeting is a third constraint. Choosing 'v2x' produces output for an older schema, and the Compose Specification has moved on. If you pick a target version because a tutorial used it, you may be generating a file that your installed docker compose rejects. The converter is doing what you asked, not what you meant.

## composerize compared with reading a running container back into YAML

The RELATED searches that bring people to this project include phrases about creating a Compose file from a running container, and that is a genuinely different task. composerize starts from a command string you already have. The other direction starts from a container that exists on a host and asks Docker what it was configured with, then writes that out. Those tools need access to the Docker daemon and produce output that reflects reality, including defaults that were never written on a command line.

composerize needs none of that. It runs anywhere Node.js runs, including in a browser, which is why the website exists. The trade-off is that it can only be as complete as the command you paste. If you are reconstructing a stack you inherited from a machine you no longer have, a container-inspection approach is the better fit. If you are holding a docker run line from a README and want it in your project file, composerize is faster and does not need a daemon socket.

The project also points at two sibling sites for adjacent jobs: decomposerize for the reverse direction, and composeverter for converting between Compose file formats. Those are separate projects, not modes of this one.

## Maintenance, licence and what to check before depending on it

The repository is not archived, and the last push was on 2026-05-17. The most recent tagged release in the list is v1.4.1 from 2023-10-21, with v1.2.0 before it in March 2023 and v1.1.0 in August 2022. So the commit history and the release history tell different stories: work continues on master, but the published version has not moved in a while. If you pin composerize in a project, pin the npm version and read the changelog rather than assuming the tag matches the tip.

The licence is MIT, declared in package.json at the repository root and in the LICENSE file. That is permissive and imposes no obligation on the YAML you generate, but the usual caveat applies: this is a description of the licence text, not legal advice, and your organisation's own policy governs.

Upgrade cost is low by construction. The converter is a pure function over a string, with no daemon dependency and no state, so a version bump changes the emitted YAML or it changes nothing. The one thing worth re-checking after an upgrade is the default Compose version target, because output shape is the entire surface area of this tool.

## Conclusion

Adopt composerize if you have a docker run command with several flags and want a compose.yaml skeleton instead of typing it out. Do not use it as a general migration tool for a running stack, and do not expect it to resolve an image tag for you. Before trusting the output, run the generated file through docker compose config and diff it against the flags you typed, because the converter only knows what the command line told it.

## FAQ

### How can I convert a docker command to a Docker Compose file with composerize?

Install the CLI with npm install composerize -g and pass the docker run command as arguments, for example composerize docker run -p 80:80 nginx. The converted Compose document is printed to stdout.

### Can composerize merge the result into an existing compose.yaml?

Yes. The Node.js API takes the existing Compose file content as a second argument, and the converted service is merged into it. The README does not document how conflicting service names are resolved, so review the output.

### Which Compose versions can composerize target?

The third parameter of the conversion function accepts 'v2x', 'v3x' or 'latest', where 'latest' targets the Compose Specification. A fourth parameter sets the indentation level of the emitted YAML.

### Does composerize inspect a running container to build the Compose file?

No. It converts the docker run command string you provide, so anything not present on that command line is not reflected in the output. Describing a container that is already running is a different task.

### What is a compose file?

In this project's terms it is the YAML document that composerize emits, where a docker run command's flags become keys under a named service, such as ports, volumes, restart and logging. composerize can also merge that service into a compose.yaml you already have.

## Sources

- [composerize/composerize on GitHub](https://github.com/composerize/composerize)
- [License: MIT](https://github.com/composerize/composerize/blob/master/LICENSE)
- [Project website](http://composerize.com)
- [README](https://github.com/composerize/composerize/blob/master/README.md)
- [Releases](https://github.com/composerize/composerize/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/composerize-composerize