Frequently Asked Questions¶

General¶

What Python versions does MoltPy support?¶

MoltPy supports Python 3.10, 3.11, 3.12, and 3.13.

Can I use pip instead of UV?¶

Yes, MoltPy can be installed with pip. However, generated projects use UV for dependency management. You can manually switch to pip if preferred.

Is MoltPy free to use?¶

Yes, MoltPy is distributed under the MIT license.

Modules¶

How do I know which modules to select?¶

Start with the standard preset — it includes the most commonly needed modules (auth, database, docker, testing, etc.). You can always add more modules later by modifying your project.

Can I preview a project before generating it?¶

Yes. Use the --dry-run flag:

moltpy new --name my_api --preset standard --dry-run --no-interactive

This renders the entire project pipeline without writing any files and prints a table showing what would be created.

Can I add modules to an existing project?¶

MoltPy generates projects, but does not modify them after creation. To add a module to an existing project, you can:

Create a new project with the desired modules
Copy the relevant files into your existing project
Or manually implement the module's functionality

What if two modules conflict?¶

The registry will prevent you from selecting conflicting modules. For example, arq and celery conflict because they are both job queue systems. You will need to choose one.

How do implied dependencies work?¶

When you select a module, its implied dependencies are automatically included. For example, selecting auth automatically includes users and database.

What are advanced configuration options?¶

Some modules expose fine-grained settings that are hidden by default to keep the wizard streamlined. When you enable "Advanced configuration options", the wizard will prompt for these settings. When disabled, sensible defaults are used. Examples include Celery queue routing, Docker multi-worker mode, and GraphQL query depth limiting. See the Module Catalog for a full list of advanced variables per module.

Configuration Files¶

Can I use a configuration file instead of CLI flags?¶

Yes. Use moltpy init-config to generate a starter config file, edit it, then pass it to moltpy new:

moltpy init-config --preset standard --output moltpy.yaml
# Edit moltpy.yaml
moltpy new --config-file moltpy.yaml --no-interactive

Both JSON and YAML formats are supported. The file extension determines the parser (.json, .yaml, .yml).

Can I mix config files and CLI flags?¶

Yes. CLI flags override values from the config file. For example:

moltpy new --config-file moltpy.yaml --name different_name --no-interactive

--modules and --preset always override the modules list from the config file.

What is the difference between presets and config files?¶

Presets are reusable module lists stored in ~/.config/moltpy/presets/. They are lightweight and focused on module selection.
Config files are full project configurations (name, description, modules, variables, post-generation flags) that can be version-controlled. They are ideal for team workflows and CI/CD pipelines.

Customization¶

Can I create my own modules?¶

Yes. See the Custom Modules guide. Modules are self-contained directories that the registry auto-discovers.

Can I modify generated projects?¶

Absolutely. Generated projects are standard FastAPI applications — you are free to modify them however you like.

What happens if the target directory already exists?¶

MoltPy refuses to overwrite non-empty directories by default. Use --force to override:

moltpy new --name my_api --preset standard --force --no-interactive

Can I use my own templates?¶

Yes. Use the --template-dir flag to provide a directory of templates that override built-ins:

moltpy new --preset standard --template-dir ./my-templates --no-interactive

Both core templates and module templates can be overridden. Override templates must be valid Jinja2 syntax — MoltPy validates them before writing any files.

Can I load modules from GitHub or external directories?¶

Yes. MoltPy supports external modules from two sources:

Local directory: Place modules in ~/.config/moltpy/modules/<name>/
GitHub: Reference with github:user/repo#module-name

# Load a module from GitHub
moltpy new --modules auth,github:user/repo#my-module --no-interactive

# With version pinning
moltpy new --modules github:user/repo@v1.0.0#my-module --no-interactive

# Force re-fetch cached modules
moltpy new --modules github:user/repo#my-module --refresh-modules --no-interactive

External modules follow the same manifest.json + templates/ convention as built-in modules.

Can I skip post-generation hooks?¶

Yes. Use --skip-post-generation to bypass uv sync, git init, and pre-commit install regardless of wizard selections:

moltpy new --name my_api --preset standard --skip-post-generation --no-interactive

This is useful when generating into an existing monorepo or running in a container without network access.

Troubleshooting¶

`moltpy` command not found¶

Make sure your Python scripts directory is in your PATH. With UV:

uv tool install moltpy

Generated project fails to start¶

Check that .env file exists (it should be auto-generated)
Run uv sync to install dependencies
Check database connection settings in .env

Module not found in registry¶

Ensure the module directory exists under src/moltpy/modules/ and contains a valid manifest.json.

Syntax error in generated code¶

MoltPy validates all generated Python files with py_compile before finishing. If you encounter a syntax error, it is a bug in MoltPy's templates. Please open an issue with the module list and preset you used.

Presets¶

Where are custom presets stored?¶

User-defined presets are stored in ~/.config/moltpy/presets/ as JSON files.

Yes. Presets are simple JSON files. You can version control them and share the files:

# On one machine
moltpy preset save --name team-standard --modules auth,database,docker,testing

# Copy the file to another machine
cp ~/.config/moltpy/presets/team-standard.json /shared/location/

# On the other machine
cp /shared/location/team-standard.json ~/.config/moltpy/presets/