Skip to main content

Python 3.12 (Amazon Linux 2023) AMI Administrator Guide

1. Quick Start Information​

Connection Methods:

  • Access the instance via SSH using the ec2-user user. Use sudo to run commands requiring root privileges. To switch to the root user, use sudo su - root.

Install Information:

  • OS: Amazon Linux 2023
  • Python 3.12 version: 3.12.12 (accessed via python3.12)
  • System Python: 3.9.25 (default python3 — preserved for system use)
  • pip: Latest (for Python 3.12, use python3.12 -m pip)
  • virtualenv: Pre-installed (use python3.12 -m virtualenv)
  • Poetry: Pre-installed at /home/ec2-user/.local/bin/poetry

Quick Verification Commands:

  • Check Python 3.12: python3.12 --version
  • Check system Python: python3 --version
  • Check pip for 3.12: pip3.12 --version
  • Check Poetry: poetry --version
  • Check virtualenv: python3.12 -m virtualenv --version

Important Note on Python Versions:

  • python3 → Python 3.9.25 (system default, used by dnf and cloud-init)
  • python3.12 → Python 3.12.12 (use this for all development work)

Using Python 3.12 and pip:

TaskCommand
Run Python 3.12python3.12 script.py
Install a packagepip3.12 install requests
Install a package (alternative)python3.12 -m pip install requests
List installed packagespip3.12 list
Upgrade pip itselfpip3.12 install --upgrade pip

Both pip3.12 and python3.12 -m pip target the same Python 3.12 environment and can be used interchangeably.

Firewall Configuration:

  • Please allow SSH port 22.
  • For security, it is recommended to limit SSH access to trusted IPs only.
  • Open additional ports only if running a Python web application (e.g., 8000, 8080).

2. First Launch & Verification​

Step 1: Connect to Your Instance​

  1. Launch your instance in your cloud provider's console (e.g., AWS EC2)
  2. Ensure SSH port 22 is allowed in your security group
  3. Connect via SSH: 
    ssh -i your-key.pem ec2-user@YOUR_PUBLIC_IP

Step 2: Verify Python 3.12​

python3.12 --version

Expected Output:

Python 3.12.12

Step 3: Verify System Python 3.9 is Preserved​

python3 --version

Expected Output:

Python 3.9.25

python3 remains 3.9 — this is intentional. System tools (dnf, cloud-init) depend on it.

Step 4: Verify pip for Python 3.12​

python3.12 -m pip --version

Expected Output:

pip 24.x.x from /usr/local/lib/python3.12/... (python 3.12)

Step 5: Verify Poetry​

source ~/.bashrc
poetry --version

Expected Output:

Poetry (version 1.x.x)

Step 6: Run a Quick Python 3.12 Test​

python3.12 -c "import sys; print(f'Hello from Python {sys.version}')"

Expected Output:

Hello from Python 3.12.12 (main, ...) [GCC ...]

3. Architecture & Detailed Configuration​

This AMI provides Python 3.12 alongside the system Python 3.9 on Amazon Linux 2023. Both versions coexist safely — Python 3.9 remains the system default (python3) to preserve compatibility with dnf and cloud-init, while Python 3.12 is available as python3.12 for all development work.

Version Coexistence Architecture:

[Amazon Linux 2023]
         |
         ├── /usr/bin/python3      → Python 3.9.25  (system default)
         │       Used by: dnf, cloud-init, system scripts
         │       Do NOT change this pointer
         │
         └── /usr/bin/python3.12  → Python 3.12.12  (for development)
                 Used by: your applications, pip, virtualenv, Poetry

Why python3 Stays as 3.9:

On Amazon Linux 2023, dnf (the package manager) uses python3 internally. Changing the python3 symlink to point to 3.12 — even via the alternatives system — can cause dnf to malfunction. To avoid breaking the system, Python 3.12 is accessed exclusively through the python3.12 command.

Key Design Decisions:

  1. python3 = 3.9 (unchanged): Protects system tools from version conflicts
  2. python3.12 for all development: Explicit versioned command avoids ambiguity
  3. python3.12-devel installed: Enables compilation of C-extension packages (numpy, pandas, cryptography)
  4. gcc installed: Required for compiling native Python extensions
  5. Poetry pre-installed: Modern dependency management using pyproject.toml

4. How-To-Create: Reproduce This Environment​

This section explains how this AMI was built, allowing you to reproduce the installation on any Amazon Linux 2023 system.

Step 1: Update the System​

sudo dnf update -y

How This Works:

Ensures all system packages are up to date before adding new software, preventing dependency conflicts.

Step 2: Install Python 3.12 and Development Components​

sudo dnf install -y python3.12
sudo dnf install -y python3.12-pip
sudo dnf install -y python3.12-devel
sudo dnf install -y gcc

How This Works:

  • python3.12: The Python 3.12 interpreter, installed as /usr/bin/python3.12
  • python3.12-pip: pip package manager for Python 3.12
  • python3.12-devel: Header files required to compile Python C extensions — without this, pip install numpy or pip install pandas will fail
  • gcc: GNU C Compiler — required when pip builds packages with native C code

Why python3.12-devel Matters:

Many popular packages (numpy, pandas, cryptography, Pillow) include C extensions compiled at install time. Without the development headers, users will see errors like:

error: command 'gcc' failed: No such file or directory

Pre-installing python3.12-devel and gcc prevents this entirely.

Step 3: Upgrade pip for Python 3.12​

python3.12 -m pip install --upgrade pip

How This Works:

Upgrades pip specifically for Python 3.12 (not the system pip). Using python3.12 -m pip ensures operations target the correct Python version.

Step 4: Install virtualenv​

python3.12 -m pip install virtualenv

How This Works:

While Python 3.12 includes the built-in venv module, virtualenv offers additional features and is widely used in existing projects. Pre-installing it prevents a common "command not found" error.

Usage:

# Using virtualenv with Python 3.12
python3.12 -m virtualenv myproject
source myproject/bin/activate

# Or using built-in venv
python3.12 -m venv myproject
source myproject/bin/activate

Step 5: Install Poetry​

curl -sSL https://install.python-poetry.org | python3.12 -
echo 'export PATH="/home/ec2-user/.local/bin:$PATH"' >> /home/ec2-user/.bashrc

How This Works:

  • Poetry is installed via its official installer using python3.12 explicitly — ensuring it targets Python 3.12, not the system 3.9
  • Installed to ~/.local/bin/ (user-level, not system-wide)
  • The PATH entry in .bashrc makes poetry available in all future shell sessions

Step 6: Clean Up and Verify​

python3.12 -c "import sys; print(f'Hello from Python {sys.version}')"
python3.12 -m pip cache purge

How This Works:

  • Confirms Python 3.12 is working correctly
  • pip cache purge removes downloaded package caches, reducing the final AMI image size

5. Using the Python 3.12 Environment​

5.1. Always Use python3.12 for Development​

# Check version
python3.12 --version

# Run a script
python3.12 myscript.py

# Interactive REPL
python3.12

# Install packages
python3.12 -m pip install requests flask numpy

5.2. Working with Virtual Environments​

Using venv (built-in):

python3.12 -m venv myproject
source myproject/bin/activate
pip install requests flask    # pip now targets 3.12 inside venv
deactivate

Using virtualenv:

python3.12 -m virtualenv myproject
source myproject/bin/activate
pip install requests flask
deactivate

5.3. Managing Packages with pip​

Use either pip3.12 or python3.12 -m pip — both target Python 3.12:

# Install a package (two equivalent ways)
pip3.12 install requests
python3.12 -m pip install requests

# Install from requirements file
pip3.12 install -r requirements.txt

# List installed packages
pip3.12 list

# Upgrade a package
pip3.12 install --upgrade requests

# Uninstall a package
pip3.12 uninstall requests

Tip: Do not use pip or pip3 alone — they may target Python 3.9 and install packages to the wrong environment.

5.4. Working with Poetry​

# Activate Poetry in PATH (if new session)
source ~/.bashrc

# Create a new project
poetry new myproject
cd myproject

# Add dependencies
poetry add requests flask

# Install all dependencies
poetry install

# Run a script within the Poetry environment
poetry run python main.py

# Activate the Poetry shell
poetry shell

5.5. Running a Simple Web Server​

Using Flask (example):

python3.12 -m pip install flask

cat > app.py << 'EOF'
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    return 'Hello from Python 3.12 on Amazon Linux 2023!'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)
EOF

python3.12 app.py

Remember to open port 8080 in your security group if accessing from outside.

6. Important File Locations​

File PathPurpose
/usr/bin/python3.12Python 3.12 interpreter
/usr/bin/python3System Python 3.9 (do not change)
/usr/bin/python3.9System Python 3.9 explicit path
/usr/lib/python3.12/Python 3.12 standard library
/usr/local/lib/python3.12/pip-installed packages for Python 3.12
/usr/include/python3.12/Development headers (from python3.12-devel)
/home/ec2-user/.local/bin/poetryPoetry executable
/home/ec2-user/.local/share/pypoetry/Poetry installation directory
/home/ec2-user/.bashrcShell config (PATH for Poetry)

7. Troubleshooting​

Issue 1: poetry: command not found​

Symptoms:

$ poetry --version
bash: poetry: command not found

Solution:

Load the updated PATH:

source ~/.bashrc
poetry --version

If Poetry is missing entirely, reinstall using Python 3.12:

curl -sSL https://install.python-poetry.org | python3.12 -
source ~/.bashrc

Issue 2: pip Install Fails with Compilation Error​

Symptoms:

error: command 'gcc' failed with exit code 1

Diagnosis:

Check if development tools are installed:

rpm -q python3.12-devel gcc

Solution:

Install missing packages:

sudo dnf install -y python3.12-devel gcc

Then retry the pip install.

Issue 3: dnf Broken​

Symptoms:

$ sudo dnf update
ImportError: No module named ...

Cause:

The python3 symlink was changed to point to Python 3.12 (e.g., via alternatives), breaking dnf.

Solution:

Restore python3 to point to 3.9:

sudo alternatives --set python3 /usr/bin/python3.9
# or, if alternatives is not configured:
sudo ln -sf /usr/bin/python3.9 /usr/bin/python3

Verify dnf works:

sudo dnf check-update

Issue 4: Virtual Environment Uses Python 3.9 Instead of 3.12​

Symptoms:

After activating the virtual environment, python --version shows 3.9.

Cause:

The virtual environment was created with python3 -m venv instead of python3.12 -m venv.

Solution:

Always create virtual environments with the explicit version:

python3.12 -m venv myproject
# or
python3.12 -m virtualenv myproject

Issue 5: python3.12 -m pip Targets Wrong Python​

Symptoms:

Packages installed via pip are not found when running python3.12.

Solution:

Always install packages using python3.12 -m pip (not pip or pip3):

python3.12 -m pip install requests

To confirm which Python a pip targets:

python3.12 -m pip --version

8. Final Notes​

Key Takeaways​

  1. Python 3.12.12 installed and available as python3.12
  2. Python 3.9 remains the python3 default — system tools (dnf, cloud-init) work normally
  3. Always use python3.12 explicitly for development to avoid version confusion
  4. python3.12-devel + gcc pre-installed — pip packages with C extensions compile without errors
  5. Poetry + virtualenv pre-installed — ready for modern Python workflows

Python Use Cases​

  • Web Development: Flask, FastAPI, Django applications
  • Data Science: NumPy, Pandas, Scikit-learn, Jupyter
  • Automation & Scripting: System automation, AWS SDK (boto3)
  • Machine Learning: TensorFlow, PyTorch (with appropriate instance)
  • DevOps: Ansible, infrastructure tooling
WorkloadInstanceReason
Development / Scriptingt3.micro / t3.smallLightweight, low cost
Web applicationst3.small / t3.mediumBalanced compute and memory
Data processingt3.large / m5.largeMore memory for pandas/numpy
ML trainingc5.xlarge+Compute-intensive workloads

Additional Resources​

For support or questions, please contact the Easycloud team.