Skip to main content
This guide walks you through creating a new project on Modrinth, from setting up basic information to uploading your first version.

​
Project Creation Overview

When you create a project on Modrinth, you’ll need to provide essential metadata, upload project files, and configure settings. Projects can be created as mods, modpacks, resource packs, shaders, plugins, or data packs.

​
Prerequisites

  • A Modrinth account with PROJECT_CREATE permissions
  • At least one version file ready to upload
  • Project icon (recommended, 256KB max, PNG/JPEG format)
You must have at least one initial version when submitting a project for review. Draft projects can be created without versions.

​
Required Project Information

1
Basic Details
2
Provide the core information about your project:
3
The display name of your project (3-64 characters)Must not contain special characters or excessive formatting.
4
URL-friendly identifier for your project (3-64 characters)
  • Must be unique across Modrinth
  • Can only contain lowercase letters, numbers, and hyphens
  • Used in your project URL: modrinth.com/mod/{slug}
Slugs that are valid base62 IDs will be rejected to prevent conflicts with project IDs.
5
Short description of your project (3-255 characters)This appears in search results and project listings.
6
Full project description in Markdown (up to 65,536 characters)Supports:
  • Standard Markdown formatting
  • Images (you can upload images via the API first)
  • Code blocks
  • Links
7
Categories and Tags
8
Help users discover your project:
9
Primary categories for your project (1-3 categories)Categories must match your project type. Available categories can be fetched from:
GET /v3/tag/category
Example categories:
  • Mods: technology, adventure, decoration
  • Modpacks: combat, magic, multiplayer
10
Secondary categories (up to 256 additional categories)Used for more specific categorization beyond the primary categories.
11
License Information
12
SPDX license identifier for your projectCommon licenses:
  • MIT - MIT License
  • GPL-3.0 - GNU General Public License v3.0
  • Apache-2.0 - Apache License 2.0
  • LGPL-3.0 - GNU Lesser General Public License v3.0
  • ARR - All Rights Reserved (default)
Get full list:
GET /v3/license
13
Optional URL to your license file or pageUseful for custom licenses or additional terms.
14
Project Icon
15
Upload an icon to represent your project:
16
  • Format: PNG or JPEG
  • Maximum size: 256 KiB
  • Recommended dimensions: 256x256 pixels or larger
  • Aspect ratio: Square (1:1) recommended
    • 17
    The icon will be automatically optimized and resized to 96x96 pixels for display. A dominant color will be extracted for theming.
    18
    Icons are uploaded as part of the multipart form data with the field name icon.
    20
    Showcase your project with gallery images:

    ​
    Initial Versions

    You must include at least one version when creating a project for review. See Managing Versions for detailed information about version requirements.
    ​
    initial_versions
    array
    required
    Versions to create with your project (1-32 versions)Each version requires:
    • Version number
    • Version title
    • File uploads
    • Supported loaders (e.g., Fabric, Forge)
    • Loader-specific fields (game versions, etc.)
    • Release channel (release, beta, alpha)

    ​
    Project Status

    ​
    is_draft
    boolean
    Create as a draft project
    • true - Save as draft without submitting for review
    • false - Submit for moderation review (default)
    Draft projects:
    • Not visible to the public
    • Can be edited freely
    • Must have at least one version to submit for review
    ​
    requested_status
    string
    Desired status after approvalOptions:
    • approved - Listed and searchable (default)
    • unlisted - Accessible via direct link only
    • private - Only visible to team members

    ​
    Organization Projects

    ​
    organization_id
    string
    Create project under an organizationRequirements:
    • You must be a member of the organization
    • You need ADD_PROJECT organization permission
    • Project owner will be the organization, not you

    ​
    API Example

    Here’s a complete example of creating a project via the API: 
    curl -X POST https://api.modrinth.com/v3/project \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'data={
    "name": "My Awesome Mod",
    "slug": "awesome-mod",
    "summary": "A mod that makes Minecraft more awesome",
    "description": "# My Awesome Mod\n\nThis mod adds amazing features...",
    "categories": ["technology", "utility"],
    "license_id": "MIT",
    "initial_versions": [{
      "version_number": "1.0.0",
      "version_title": "Initial Release",
      "version_body": "First release of the mod",
      "file_parts": ["file"],
      "loaders": [{"0": "fabric"}],
      "fields": {
        "game_versions": ["1.20.1", "1.20.2"]
      },
      "release_channel": "release",
      "featured": true,
      "dependencies": []
    }],
    "is_draft": false,
    "requested_status": "approved"
  }' \
  -F '[email protected]' \
  -F '[email protected]'

    ​
    Project Limits

    Users have a maximum project limit based on their account standing. If you’ve reached your limit, you’ll receive a limit_reached error.
    To check your current usage: 
    GET /v3/user/{id}/projects

    ​
    Validation and Errors

    Common errors when creating projects:
    • Slug collision - The slug is already taken or conflicts with a project ID
    • Invalid category - Category doesn’t exist or doesn’t match project type
    • Invalid loader - Loader not supported by Modrinth
    • Invalid game version - Game version not recognized
    • Missing required fields - Name, slug, summary, description, or license not provided
    • File validation failed - Uploaded files don’t pass security/format checks
    • Duplicate files - File hash already exists in another project

    ​
    After Creation

    Once your project is created:
    1. Processing - Your project enters moderation queue
    2. Automated checks - Files are scanned for security issues
    3. Manual review - Moderators review your project (if needed)
    4. Approval - Project becomes visible at your requested status
    Most projects are approved within 24-48 hours. You’ll receive notifications about your project’s status.

    ​
    Next Steps