diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 00000000..e3fbb57b
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,121 @@
+# Installation Guide for ecs_composex
+
+## Standard Installation
+
+For most Python versions (3.9-3.11), installation is straightforward:
+
+```bash
+pip install ecs-composex
+```
+
+## Python 3.12+ Installation
+
+### Issue Background
+
+The `flatdict` package (version 4.0.1), which is a transitive dependency through `compose-x-common`, has a build issue with Python 3.12+. The package's `setup.py` imports `pkg_resources`, which is deprecated and no longer available by default in Python 3.12's setuptools.
+
+### Solution 1: Using the Provided Pre-built Wheel (Recommended)
+
+If you've cloned this repository, use the pre-built wheel provided in the `vendor-wheels/` directory:
+
+```bash
+git clone https://github.com/compose-x/ecs_composex.git
+cd ecs_composex
+python3 -m venv venv
+source venv/bin/activate
+pip install --upgrade pip setuptools
+
+# Install flatdict from the provided wheel
+pip install vendor-wheels/flatdict-4.0.1-py3-none-any.whl
+
+# Now install ecs-composex
+pip install .
+```
+
+### Solution 2: Install from PyPI
+
+When installing from PyPI (not from source), you can install setuptools first:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install --upgrade pip setuptools
+pip install ecs-composex
+```
+
+**Note**: If you still encounter issues, try installing flatdict separately first:
+
+```bash
+# Install setuptools as a prerequisite
+pip install setuptools>=65.5.0
+
+# Download flatdict source
+pip download --no-deps --no-binary=:all: flatdict==4.0.1
+tar -xzf flatdict-4.0.1.tar.gz
+cd flatdict-4.0.1
+
+# Patch the setup.py to remove pkg_resources requirement
+cat > setup.py << 'EOF'
+import setuptools
+setuptools.setup()
+EOF
+
+# Create proper build configuration
+cat > pyproject.toml << 'EOF'
+[build-system]
+requires = ["setuptools>=39.2", "wheel"]
+build-backend = "setuptools.build_meta"
+EOF
+
+# Build and install
+pip install .
+cd ..
+
+# Now install ecs-composex
+pip install ecs-composex
+```
+
+### Solution 3: Using Poetry
+
+If you're using Poetry for dependency management:
+
+```bash
+poetry install
+```
+
+Poetry should handle the dependency resolution automatically with the setuptools dependency we've added.
+
+## Verification
+
+After installation, verify that ecs-composex is installed correctly:
+
+```bash
+ecs-compose-x --version
+```
+
+## Troubleshooting
+
+If you encounter the error:
+```
+ModuleNotFoundError: No module named 'pkg_resources'
+```
+
+This confirms the flatdict build issue. Use Solution 1 or Solution 2 above to resolve it.
+
+## Development Installation
+
+For development purposes:
+
+```bash
+git clone https://github.com/compose-x/ecs_composex.git
+cd ecs_composex
+python3 -m venv venv
+source venv/bin/activate
+pip install --upgrade pip setuptools
+
+# Install flatdict from provided wheel
+pip install vendor-wheels/flatdict-4.0.1-py3-none-any.whl
+
+# Install in development mode
+pip install -e .
+```
diff --git a/MANIFEST.in b/MANIFEST.in
index fd8bd5bc..fc199259 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -13,3 +13,4 @@ recursive-exclude * *.py[co]
 recursive-include tests *
 recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif
 recursive-include ecs_composex *spec.json *perms.json *.j2
+recursive-include vendor-wheels *.whl
diff --git a/README.rst b/README.rst
index 0852cdd7..8d4f72e7 100644
--- a/README.rst
+++ b/README.rst
@@ -53,15 +53,25 @@ Useful Links
 Installation
 =====================
 
+.. note::
+
+    **Python 3.12+ Users**: Due to a dependency issue with ``flatdict`` 4.0.1, you may need to install it separately first.
+    A pre-built wheel is provided in the ``vendor-wheels/`` directory of this repository.
+
 .. code-block:: bash
 
     # Inside a python virtual environment
     python3 -m venv venv
     source venv/bin/activate
-    pip install pip -U
+    pip install pip setuptools -U
+    
+    # For Python 3.12+, install flatdict first using the provided wheel
+    pip install vendor-wheels/flatdict-4.0.1-py3-none-any.whl  # If installing from repository
+    
     pip install ecs-composex
 
     # For your user only
+    pip install --upgrade setuptools
     pip install ecs-composex --user
 
 Usage
diff --git a/poetry.lock b/poetry.lock
index 8d2a8df0..cdb8cb9a 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 2.1.4 and should not be changed by hand.
+# This file is automatically @generated by Poetry 2.3.2 and should not be changed by hand.
 
 [[package]]
 name = "alabaster"
@@ -98,7 +98,7 @@ win_unicode_console = {version = "*", markers = "python_version <= \"3.9\""}
 
 [package.extras]
 develop = ["PyHamcrest (<2.0) ; python_version < \"3.0\"", "PyHamcrest (>=2.0.2) ; python_version >= \"3.0\"", "build (>=0.5.1)", "coverage (>=5.0)", "invoke (>=1.7.0) ; python_version >= \"3.6\"", "invoke (>=1.7.0,<2.0) ; python_version < \"3.6\"", "mock (<4.0) ; python_version < \"3.6\"", "mock (>=4.0) ; python_version >= \"3.6\"", "modernize (>=0.5)", "path (>=13.1.0) ; python_version >= \"3.5\"", "path.py (>=11.5.0) ; python_version < \"3.5\"", "pycmd", "pylint", "pytest (>=4.2,<5.0) ; python_version < \"3.0\"", "pytest (>=5.0) ; python_version >= \"3.0\"", "pytest-cov", "pytest-html (>=1.19.0,<2.0) ; python_version < \"3.0\"", "pytest-html (>=2.0) ; python_version >= \"3.0\"", "ruff ; python_version >= \"3.7\"", "tox (>=3.28.0,<4.0)", "twine (>=1.13.0)", "virtualenv (<20.22.0) ; python_version < \"3.7\"", "virtualenv (>=20.26.6) ; python_version >= \"3.7\""]
-docs = ["furo (>=2024.04.27) ; python_version >= \"3.8\"", "sphinx (>=1.6,<4.4) ; python_version < \"3.7\"", "sphinx (>=7.4.0) ; python_version >= \"3.7\"", "sphinx-copybutton (>=0.5.2) ; python_version >= \"3.7\"", "sphinxcontrib-applehelp (>=1.0.8) ; python_version >= \"3.7\"", "sphinxcontrib-htmlhelp (>=2.0.5) ; python_version >= \"3.7\""]
+docs = ["furo (>=2024.4.27) ; python_version >= \"3.8\"", "sphinx (>=1.6,<4.4) ; python_version < \"3.7\"", "sphinx (>=7.4.0) ; python_version >= \"3.7\"", "sphinx-copybutton (>=0.5.2) ; python_version >= \"3.7\"", "sphinxcontrib-applehelp (>=1.0.8) ; python_version >= \"3.7\"", "sphinxcontrib-htmlhelp (>=2.0.5) ; python_version >= \"3.7\""]
 formatters = ["behave-html-formatter (>=0.9.10) ; python_version >= \"3.6\"", "behave-html-pretty-formatter (>=1.9.1) ; python_version >= \"3.6\""]
 testing = ["PyHamcrest (<2.0) ; python_version < \"3.0\"", "PyHamcrest (>=2.0.2) ; python_version >= \"3.0\"", "assertpy (>=1.1)", "chardet", "freezegun (>=1.5.1) ; python_version > \"3.7\"", "mock (<4.0) ; python_version < \"3.6\"", "mock (>=4.0) ; python_version >= \"3.6\"", "path (>=13.1.0) ; python_version >= \"3.5\"", "path.py (>=11.5.0,<13.0) ; python_version < \"3.5\"", "pytest (<5.0) ; python_version < \"3.0\"", "pytest (>=5.0) ; python_version >= \"3.0\"", "pytest-html (>=1.19.0,<2.0) ; python_version < \"3.0\"", "pytest-html (>=2.0) ; python_version >= \"3.0\""]
 
@@ -1547,7 +1547,7 @@ files = [
 
 [package.dependencies]
 attrs = ">=22.2.0"
-jsonschema-specifications = ">=2023.03.6"
+jsonschema-specifications = ">=2023.3.6"
 referencing = ">=0.28.4"
 rpds-py = ">=0.7.1"
 
@@ -2785,10 +2785,10 @@ files = [
 ]
 
 [package.dependencies]
-botocore = ">=1.37.4,<2.0a.0"
+botocore = ">=1.37.4,<2.0a0"
 
 [package.extras]
-crt = ["botocore[crt] (>=1.37.4,<2.0a.0)"]
+crt = ["botocore[crt] (>=1.37.4,<2.0a0)"]
 
 [[package]]
 name = "schema"
@@ -2802,6 +2802,27 @@ files = [
     {file = "schema-0.7.8.tar.gz", hash = "sha256:e86cc08edd6fe6e2522648f4e47e3a31920a76e82cce8937535422e310862ab5"},
 ]
 
+[[package]]
+name = "setuptools"
+version = "82.0.0"
+description = "Easily download, build, install, upgrade, and uninstall Python packages"
+optional = false
+python-versions = ">=3.9"
+groups = ["main"]
+files = [
+    {file = "setuptools-82.0.0-py3-none-any.whl", hash = "sha256:70b18734b607bd1da571d097d236cfcfacaf01de45717d59e6e04b96877532e0"},
+    {file = "setuptools-82.0.0.tar.gz", hash = "sha256:22e0a2d69474c6ae4feb01951cb69d515ed23728cf96d05513d36e42b62b37cb"},
+]
+
+[package.extras]
+check = ["pytest-checkdocs (>=2.4)", "pytest-ruff (>=0.2.1) ; sys_platform != \"cygwin\"", "ruff (>=0.13.0) ; sys_platform != \"cygwin\""]
+core = ["importlib_metadata (>=6) ; python_version < \"3.10\"", "jaraco.functools (>=4)", "jaraco.text (>=3.7)", "more_itertools", "more_itertools (>=8.8)", "packaging (>=24.2)", "platformdirs (>=4.2.2)", "tomli (>=2.0.1) ; python_version < \"3.11\"", "wheel (>=0.43.0)"]
+cover = ["pytest-cov"]
+doc = ["furo", "jaraco.packaging (>=9.3)", "jaraco.tidelift (>=1.4)", "pygments-github-lexers (==0.0.5)", "pyproject-hooks (!=1.1)", "rst.linker (>=1.9)", "sphinx (>=3.5)", "sphinx-favicon", "sphinx-inline-tabs", "sphinx-lint", "sphinx-notfound-page (>=1,<2)", "sphinx-reredirects", "sphinxcontrib-towncrier", "towncrier (<24.7)"]
+enabler = ["pytest-enabler (>=2.2)"]
+test = ["build[virtualenv] (>=1.0.3)", "filelock (>=3.4.0)", "ini2toml[lite] (>=0.14)", "jaraco.develop (>=7.21) ; python_version >= \"3.9\" and sys_platform != \"cygwin\"", "jaraco.envs (>=2.2)", "jaraco.path (>=3.7.2)", "jaraco.test (>=5.5)", "packaging (>=24.2)", "pip (>=19.1)", "pyproject-hooks (!=1.1)", "pytest (>=6,!=8.1.*)", "pytest-home (>=0.5)", "pytest-perf ; sys_platform != \"cygwin\"", "pytest-subprocess", "pytest-timeout", "pytest-xdist (>=3)", "tomli-w (>=1.0.0)", "virtualenv (>=13.0.0)", "wheel (>=0.44.0)"]
+type = ["importlib_metadata (>=7.0.2) ; python_version < \"3.10\"", "jaraco.develop (>=7.21) ; sys_platform != \"cygwin\"", "mypy (==1.18.*)", "pytest-mypy"]
+
 [[package]]
 name = "six"
 version = "1.17.0"
@@ -3335,4 +3356,4 @@ ecrscan = ["ecr-scan-reporter"]
 [metadata]
 lock-version = "2.1"
 python-versions = ">=3.9,<4.0"
-content-hash = "0ec3a69aa867c459471ccd014a227e267c6f30cd858a7f5dc426524ce764b096"
+content-hash = "a041b7857116c05cd76f3d38439724a8e553907566ef5099d754d096dd8e8714"
diff --git a/pyproject.toml b/pyproject.toml
index bbad4c0d..35c305ab 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -28,7 +28,8 @@ include = [
   "MANIFEST.in",
   "NOTICES.rst",
   "ecs_composex/**/*.json",
-  "ecs_composex/**/*.j2"
+  "ecs_composex/**/*.j2",
+  "vendor-wheels/**/*.whl"
 ]
 exclude = ["*.pyc", "*~", "*pycache*"]
 
@@ -54,6 +55,7 @@ retry2 = "^0.9"
 Jinja2 = "^3.1.2"
 docker = ">=6.0.1,<8.0"
 troposphere-awscommunity-applicationautoscaling-scheduledaction = "^0.1.1"
+setuptools = ">=65.5.0"
 
 [tool.poetry.group.dev.dependencies]
 isort = "^5.13"
diff --git a/vendor-wheels/flatdict-4.0.1-py3-none-any.whl b/vendor-wheels/flatdict-4.0.1-py3-none-any.whl
new file mode 100644
index 00000000..2637ac07
Binary files /dev/null and b/vendor-wheels/flatdict-4.0.1-py3-none-any.whl differ