How to Install Odoo 18 Development Environment: Step-by-Step Guide

The Difference Between a Frustrating Odoo Learning Experience and a Smooth One? Your Development Environment Setup.

Every experienced Odoo developer has battle scars from their first installation attempt. Maybe PostgreSQL wouldn't start. Perhaps Python dependencies failed halfway through. Or worse—everything seemed to work until they tried creating their first module, only to discover their environment was silently misconfigured.

Here's the truth: 90% of "Odoo isn't working" problems are actually "environment isn't configured correctly" problems.

The good news? Once you set up your odoo 18 development environment properly the first time, you'll rarely touch it again. It becomes your reliable foundation for everything you build. The bad news? Skip a step or misconfigure something now, and you'll waste hours debugging phantom issues that have nothing to do with your code.

This guide walks you through every single step of setting up Odoo 18 on your machine. We're not taking shortcuts. We're not assuming you know anything beyond basic terminal usage. By the end of this tutorial, you'll have:

            What You'll Achieve:
            ✅ Odoo 18 running smoothly on your local machine
✅ PostgreSQL database configured and tested
✅ Python virtual environment with all dependencies
✅ IDE (VS Code or PyCharm) configured for Odoo development
✅ Your first Odoo database created and accessible
✅ Developer mode enabled and ready to use

        

Let's build your Odoo development environment the right way—once and done.

System Requirements: What You Need Before Starting

Before we begin installing anything, let's verify your system meets Odoo's requirements. Nothing kills momentum like discovering halfway through installation that your system doesn't have enough RAM or the wrong Python version.

Required Software and Specifications

✅ Python 3.10 or Higher (3.11 Recommended)

Why 3.11 specifically? Odoo 18 supports Python 3.10, 3.11, and 3.12, but 3.11 offers the best balance of compatibility and performance. Python 3.11 is up to 25% faster than 3.10 for many operations, and all Odoo 18 dependencies are thoroughly tested with it.

✅ PostgreSQL 12 or Higher (15+ Recommended)

Why PostgreSQL matters: Unlike many frameworks where you can swap databases, Odoo is deeply integrated with PostgreSQL. It's not optional—Odoo will not work with MySQL or SQLite. PostgreSQL 15 brings significant performance improvements for queries common in business applications.

✅ Hardware Requirements

RAM: 4GB minimum, 8GB+ recommended (comfortable development with multiple apps open)
Disk Space: 10GB free (Odoo source + dependencies + databases)
Processor: Any modern dual-core CPU is sufficient

✅ Additional Required Software

Git: For version control and downloading Odoo source
Text Editor/IDE: VS Code (recommended for beginners), PyCharm, or Sublime Text
Node.js and npm: For compiling LESS/SCSS stylesheets

Operating System Support

Ubuntu 22.04 / 24.04 LTS (Highly Recommended for Beginners): This tutorial focuses primarily on Ubuntu because it's the most straightforward for Odoo development. Most production Odoo servers run on Ubuntu, so developing on Ubuntu ensures maximum compatibility.

macOS 12+ (Monterey or Later): Fully supported with Homebrew. We'll provide macOS-specific commands where they differ from Ubuntu.

Windows 10 / 11: Works well with WSL2 (Windows Subsystem for Linux). We strongly recommend using WSL2 with Ubuntu rather than native Windows installation—you'll encounter fewer problems and better performance.

💡 Pro tip: This guide covers Ubuntu primarily, with notes for macOS and Windows users at each step. If you're on Windows, follow our WSL2 setup instructions first, then continue with Ubuntu commands.

Pre-Installation Checklist: Are You Ready?

Before diving into terminal commands, let's make sure you have everything prepared. Trust me—stopping mid-installation to fix something unrelated is frustrating.

✓ Pre-Installation Requirements:

[ ] Terminal/command line familiarity: You should be comfortable navigating directories, running commands, and editing files in terminal
[ ] Text editor installed: Download VS Code, PyCharm Community Edition, or have your preferred editor ready
[ ] Stable internet connection: You'll download several GB of software and dependencies
[ ] Admin/sudo access: You'll need permission to install system packages
[ ] 2-3 hours of uninterrupted time: Don't rush this. Take breaks between sections if needed
[ ] Backup your system: Always good practice before major software installations

📸 Pro tip: Take screenshots during installation, especially of any error messages you encounter. When asking for help in forums, these screenshots are invaluable. Also screenshot your successful configurations—you'll reference them when setting up future environments.

Ready? Let's start with Python.

Step 1: Install Python 3.10+ (3.11 Recommended)

Python is Odoo's backbone. The entire backend framework, business logic, and ORM are written in Python. Let's install the right version.

For Ubuntu Users:

First, check if Python 3.11 is already installed:

# Check current Python version
python3 --version

If you see "Python 3.11.x", you're good! Skip to verification below. If not:

# Update package list
sudo apt update

# Install Python 3.11 and development tools
sudo apt install python3.11 python3.11-dev python3.11-venv python3-pip -y

What each package does:

python3.11 → The Python interpreter itself
python3.11-dev → Development headers needed for compiling Python packages
python3.11-venv → Virtual environment support (critical for isolated development)
python3-pip → Python package manager

For macOS Users:

Using Homebrew (if you don't have Homebrew, install it from brew.sh):

# Install Python 3.11
brew install python@3.11

# Add to PATH (add this to your ~/.zshrc or ~/.bash_profile)
export PATH="/opt/homebrew/opt/python@3.11/bin:$PATH"

For Windows Users (WSL2):

First, set up WSL2 if you haven't:

Open PowerShell as Administrator
Run: wsl --install Ubuntu-22.04
Restart your computer
Open Ubuntu from Start menu
Follow the Ubuntu installation steps above

For detailed WSL2 setup: Microsoft WSL Documentation

Verification:

# Verify Python installation
python3.11 --version

# Should output: Python 3.11.x

# Verify pip
python3.11 -m pip --version

⚠️ Common Issue: "command not found"

If you see "python3.11: command not found":

Ubuntu: Run sudo apt install python3.11 again and check for errors
macOS: Make sure you added Python to PATH (see export command above)
Try: which python3.11 to see if it's installed but not in PATH

Step 2: Install and Configure PostgreSQL

PostgreSQL is Odoo's database engine. Every piece of data—from customers to invoices to products—lives in PostgreSQL. This is not optional, and it must be configured correctly.

Why PostgreSQL (and ONLY PostgreSQL)?

Odoo's ORM (Object-Relational Mapping) uses PostgreSQL-specific features like:

JSONB fields for flexible data storage
Array fields for many2many relationships
Advanced indexing for performance
Transaction isolation levels for data consistency

MySQL or SQLite simply won't work.

Ubuntu Installation:

# Install PostgreSQL 15 (latest stable)
sudo apt install postgresql postgresql-client postgresql-contrib -y

# Verify installation and start service
sudo systemctl status postgresql

# Enable PostgreSQL to start on boot
sudo systemctl enable postgresql

Create Odoo Database User:

Odoo needs a PostgreSQL user to create and manage databases. We'll create a superuser with your system username:

# Switch to postgres user and create your user
sudo -u postgres createuser -s $USER

# Create a database for your user (required for psql access)
createdb $USER

# Test PostgreSQL access
psql -l

The psql -l command lists all databases. If you see a list without errors, PostgreSQL is working correctly!

macOS Installation:

# Install PostgreSQL 15
brew install postgresql@15

# Start PostgreSQL service
brew services start postgresql@15

# Create your user
createuser -s $USER
createdb $USER

# Verify
psql -l

Understanding PostgreSQL Setup:

What we just did:

createuser -s $USER → Creates a PostgreSQL superuser with your username. The -s flag gives superuser privileges (needed to create databases)
createdb $USER → Creates a default database so you can use psql commands
PostgreSQL is now running as a service, automatically starting with your system

⚠️ Troubleshooting PostgreSQL

Issue: "psql: command not found"

PostgreSQL binaries aren't in PATH. Add to your ~/.bashrc or ~/.zshrc:

# For Ubuntu
export PATH="/usr/lib/postgresql/15/bin:$PATH"

# For macOS
export PATH="/opt/homebrew/opt/postgresql@15/bin:$PATH"

Issue: Connection errors

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Restart if needed
sudo systemctl restart postgresql

# Check listening ports
sudo netstat -plunt | grep postgres

Step 3: Install System Dependencies

Odoo isn't just Python code—it needs various system libraries to handle XML processing, PDF generation, image manipulation, and more. Missing even one dependency can cause cryptic errors later.

Ubuntu - Complete Dependencies:

sudo apt install -y python3-pip python3-dev libxml2-dev libxslt1-dev \
    libldap2-dev libsasl2-dev libtiff5-dev libjpeg8-dev libopenjp2-7-dev \
    zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev libharfbuzz-dev \
    libfribidi-dev libxcb1-dev libpq-dev git node-less npm

What each dependency group does:

XML/HTML Processing: libxml2-dev, libxslt1-dev → Parse and generate XML/HTML (used in views and reports)
Database Connection: libpq-dev → PostgreSQL client library for Python
Image Handling: libjpeg8-dev, libopenjp2-7-dev, libtiff5-dev, libwebp-dev → Process product images, user avatars, report logos
Authentication: libldap2-dev, libsasl2-dev → LDAP integration for enterprise authentication
Frontend Assets: node-less, npm → Compile CSS from LESS files
Version Control: git → Essential for downloading Odoo and managing code

macOS Dependencies:

# Install image and XML libraries
brew install jpeg libpng libtiff webp freetype libxml2 libxslt

# Install PostgreSQL development files
brew install postgresql@15

# Install Node.js and less
brew install node
npm install -g less less-plugin-clean-css

# Install Git (usually pre-installed on macOS)
brew install git

💡 Good to know: This step takes 5-10 minutes on a fast connection. The terminal will show installation progress for each package. Don't interrupt—let it complete fully.

Step 4: Download Odoo 18 Source Code

Now for the main event—downloading Odoo itself. We're cloning the official Odoo repository from GitHub.

Why Source Installation (vs Docker or Package)?

Full Control: You can modify any file, understand how everything works
Easy Debugging: Set breakpoints, step through code, inspect variables
Access to All Modules: Core modules and framework source all available
Version Control: Use Git to track changes, switch versions, contribute back
Standard Practice: This is how most professional Odoo developers work

Clone the Repository:

# Create a directory for all Odoo development
mkdir ~/odoo-dev
cd ~/odoo-dev

# Clone Odoo 18 from GitHub
git clone https://github.com/odoo/odoo.git --depth 1 --branch 18.0 --single-branch odoo

Understanding the Git flags:

--depth 1 → Downloads only the latest commit, not entire history (saves ~1GB and 10+ minutes)
--branch 18.0 → Specifically gets Odoo version 18, not master or other versions
--single-branch → Only download the 18.0 branch, ignoring others
odoo → Name the directory "odoo" (you'll have ~/odoo-dev/odoo)

This download takes 5-15 minutes depending on your internet speed. You'll see Git progress as it downloads.

Understanding Odoo's Directory Structure:

Once downloaded, let's explore what you got:

cd odoo
ls -la

Key directories and files:

odoo/
├── addons/              ← Core Odoo modules (accounting, sales, inventory, etc.)
├── odoo/                ← Framework core (ORM, HTTP, models, fields)
│   ├── addons/          ← Base framework modules (base, web, mail)
│   ├── tools/           ← Utility functions
│   └── cli/             ← Command-line interface
├── setup/               ← Installation and packaging files
├── odoo-bin             ← Main server executable (this is what you run!)
├── requirements.txt     ← Python dependencies list
└── debian/              ← Debian/Ubuntu packaging files

The two most important locations:

odoo-bin → The script that starts Odoo server
addons/ → Where core modules live (you'll study these constantly)

Step 5: Create Python Virtual Environment

Virtual environments are Python development best practice. Think of them as isolated bubbles where you can install specific package versions without affecting your system Python or other projects.

Why Virtual Environments?

Isolation: Odoo's dependencies won't conflict with other Python projects
Clean System: Your system Python stays pristine
Easy Reset: If something breaks, delete the venv and recreate it in 10 minutes
Version Control: Each project can use different package versions
No Sudo: Install packages without root permissions

Create and Activate Virtual Environment:

# Navigate to your odoo-dev directory
cd ~/odoo-dev

# Create virtual environment named 'odoo-venv'
python3.11 -m venv odoo-venv

# Activate the virtual environment
source odoo-venv/bin/activate

# Your prompt should change to show (odoo-venv) at the beginning
# (odoo-venv) user@computer:~/odoo-dev$

What just happened:

Python created a new directory odoo-venv/ with its own Python interpreter
When activated, python and pip commands use this isolated environment
You'll see (odoo-venv) prefix in your terminal prompt

Install Odoo Python Dependencies:

Now we install all Python packages Odoo needs. This is the longest step (10-15 minutes):

# Make sure you're in the activated virtual environment
# You should see (odoo-venv) in your prompt

cd ~/odoo-dev/odoo

# Upgrade pip and install wheel (prevents errors)
pip install --upgrade pip
pip install wheel

# Install all Odoo requirements
pip install -r requirements.txt

What's being installed? (key packages explained)

psycopg2: PostgreSQL database adapter for Python
Werkzeug: WSGI web application framework (handles HTTP requests)
lxml: XML/HTML processing library
Pillow: Image processing (resize, crop, format conversion)
reportlab: PDF generation
Babel: Internationalization and localization
python-dateutil: Date/time manipulation
requests: HTTP library for API calls
...and 40+ more packages!

You'll see installation progress for each package. Some compile C extensions (like lxml, psycopg2), which takes longer.

⚠️ Common Installation Issues:

Issue: "Failed building wheel for X"

Usually means missing system dependencies. Go back to Step 3 and reinstall dependencies, especially dev packages.

Issue: "ERROR: Could not find a version that satisfies the requirement"

# Update pip to latest version
pip install --upgrade pip

# Try installation again
pip install -r requirements.txt

Issue: psycopg2 won't install

Install libpq-dev (Ubuntu) or PostgreSQL development headers (macOS).

Verify Installation:

# Check if key packages installed
pip list | grep psycopg2
pip list | grep Werkzeug
pip list | grep lxml

# Should show version numbers for each

💡 Activating your virtual environment: Every time you open a new terminal to work on Odoo, you must run source ~/odoo-dev/odoo-venv/bin/activate first. Get used to this—it's essential!

Step 6: Create Odoo Configuration File

Odoo can run with command-line arguments, but using a configuration file is cleaner and more professional. You'll reference this config file every time you start Odoo.

Why Use a Configuration File?

Persistent Settings: Database credentials, ports, paths saved in one place
Multiple Configs: Different files for development, testing, production
Easy Debugging: Enable verbose logging, set specific options
Team Sharing: Share configurations with teammates (minus passwords)

Create the Configuration File:

cd ~/odoo-dev
nano odoo.conf

# Or use your preferred editor:
# code odoo.conf     (VS Code)
# vim odoo.conf      (Vim)
# gedit odoo.conf    (Gedit)

Basic Configuration Template:

[options]
; Database settings
db_host = localhost
db_port = 5432
db_user = YOUR_USERNAME
db_password = False
; If PostgreSQL requires password, set it here

; Server settings
http_port = 8069
xmlrpc_port = 8069

; Addon paths (where Odoo looks for modules)
addons_path = /home/YOUR_USERNAME/odoo-dev/odoo/addons,/home/YOUR_USERNAME/odoo-dev/odoo/odoo/addons

; Logging
logfile = /home/YOUR_USERNAME/odoo-dev/odoo.log
log_level = info
; Options: debug, info, warn, error, critical

; Development settings
dev_mode = reload,qweb,werkzeug,xml
; Auto-reload on code changes

; Performance (for development)
workers = 0
; 0 = single process (better for debugging)
; In production, use: workers = (CPU_cores * 2) + 1

⚠️ IMPORTANT: Replace YOUR_USERNAME with your actual username!

# Find your username
echo $USER

# Example: if output is "chamal", replace:
# /home/YOUR_USERNAME/odoo-dev/odoo/addons
# with:
# /home/chamal/odoo-dev/odoo/addons

Configuration Options Explained:

Database Settings:

db_host → Where PostgreSQL runs (localhost for local development)
db_port → PostgreSQL port (5432 is default)
db_user → Your PostgreSQL username (created in Step 2)
db_password → Password if required (False for no password)

Server Settings:

http_port → Web interface port (8069 is Odoo default)
xmlrpc_port → API port (usually same as http_port)

Addon Paths:

Comma-separated list of directories where Odoo looks for modules
First path: odoo/addons (core modules like accounting, sales)
Second path: odoo/odoo/addons (framework modules like base, web)
Later you'll add: /home/user/odoo-dev/custom_addons (your modules)

Logging:

logfile → Where Odoo writes logs (critical for debugging)
log_level → How verbose: debug (everything), info (normal), warn (problems only)

Development Mode:

dev_mode → Special development features
reload → Auto-restart when Python files change
qweb → Don't cache templates (see changes immediately)
werkzeug → Better debugging for HTTP errors
xml → Don't cache XML views

💡 Pro tip: Save this configuration file! Copy it to a safe location or commit it to Git (without passwords). When setting up Odoo on another machine, you'll save hours by reusing this config.

Save the file (Ctrl+O in nano, then Ctrl+X to exit).

Download link: odoo.conf template file

Step 7: Start Odoo for the First Time

This is the moment of truth. Let's start Odoo and see if everything works!

Launch Odoo Server:

# Make sure you're in the activated virtual environment
# (you should see (odoo-venv) in your prompt)
source ~/odoo-dev/odoo-venv/bin/activate

# Navigate to Odoo directory
cd ~/odoo-dev/odoo

# Start Odoo with your configuration file
./odoo-bin -c ../odoo.conf

What You Should See:

If everything is configured correctly, you'll see output like this:

INFO ? odoo: Odoo version 18.0
INFO ? odoo: Using configuration file at /home/user/odoo-dev/odoo.conf
INFO ? odoo: addons paths: ['/home/user/odoo-dev/odoo/addons', ...]
INFO ? odoo: database: user@localhost:5432
INFO ? odoo.modules.loading: loading 1 module
INFO ? odoo.modules.loading: 1 module loaded in 0.01s
INFO ? odoo.service.server: HTTP service (werkzeug) running on 0.0.0.0:8069

Key indicators of success:

✅ "Odoo version 18.0" confirms you're running correct version
✅ "Using configuration file" shows your config is loaded
✅ "addons paths" lists where Odoo searches for modules
✅ "HTTP service running on 0.0.0.0:8069" means web server started

Access Odoo in Your Browser:

Open your web browser and navigate to:

http://localhost:8069

You should see the Odoo database manager screen!

Create Your First Database:

Fill in the database creation form:

Master Password: Create a strong password (you'll need this for database management operations). Example: admin123master
Database Name: odoo18-dev (use lowercase, no spaces)
Email: Your email address (becomes admin username)
Password: Admin user password (different from master password)
Language: English (US) or your preference
Country: Select your country
Demo Data: ❌ Unchecked (we don't want demo data for development)

Click "Create Database" and wait 2-3 minutes. Odoo is:

Creating PostgreSQL database
Installing base modules
Setting up initial data
Configuring your admin user

Success! 🎉

After creation completes, you'll see Odoo's main dashboard with apps like Contacts, Calendar, Discuss. You're now inside Odoo 18!

✨ Congratulations! You've successfully installed Odoo 18 and created your first database.

⚠️ Common Startup Issues:

Issue: "Address already in use" or port 8069 busy

# Find process using port 8069
sudo lsof -i :8069

# Kill the process (replace PID with actual number)
kill -9 PID

# Or change port in odoo.conf to 8070 and try again

Issue: "Could not connect to database" errors

# Check PostgreSQL is running
sudo systemctl status postgresql

# Restart PostgreSQL
sudo systemctl restart postgresql

# Verify your db_user in odoo.conf matches PostgreSQL user

Issue: Python module import errors

Missing dependencies. Go back to Step 5 and reinstall requirements.txt

Step 8: Configure Your IDE (VS Code / PyCharm)

A properly configured IDE makes Odoo development infinitely easier—code completion, debugging, Git integration, and more.

Visual Studio Code Setup (Recommended for Beginners):

1. Install VS Code: Download from code.visualstudio.com

2. Install Essential Extensions:

Open VS Code, press Ctrl+Shift+X (Extensions), and install:

Python (by Microsoft) → Python language support, IntelliSense, debugging
XML (by Red Hat) → XML syntax highlighting and validation
PostgreSQL (by Chris Kolkman) → Database query and management
Better Jinja (by Samuel Colvin) → QWeb template syntax highlighting
GitLens (optional) → Enhanced Git capabilities
Odoo Snippets (optional) → Code snippets for common Odoo patterns

3. Open Your Odoo Workspace:

# Open VS Code in your odoo-dev directory
cd ~/odoo-dev
code .

4. Configure Python Interpreter:

Press Ctrl+Shift+P to open Command Palette
Type "Python: Select Interpreter"
Choose your virtual environment: ~/odoo-dev/odoo-venv/bin/python

This ensures VS Code uses the correct Python with all Odoo dependencies.

5. Create Debug Configuration:

Create .vscode/launch.json in your odoo-dev directory:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Odoo 18",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/odoo/odoo-bin",
            "args": [
                "-c", "${workspaceFolder}/odoo.conf",
                "-d", "odoo18-dev",
                "-u", "base"
            ],
            "console": "integratedTerminal",
            "justMyCode": false,
            "python": "${workspaceFolder}/odoo-venv/bin/python"
        }
    ]
}

What this enables:

Press F5 to start Odoo with debugger attached
Set breakpoints in Python code (click left of line numbers)
Step through code line-by-line
Inspect variable values in real-time

PyCharm Setup (Alternative):

PyCharm Community Edition is free and excellent for Python development.

1. Install PyCharm: Download from jetbrains.com/pycharm

2. Open Project: File → Open → Select ~/odoo-dev

3. Configure Interpreter:

File → Settings → Project → Python Interpreter
Add Interpreter → Existing Environment
Select: ~/odoo-dev/odoo-venv/bin/python

4. Mark Directories:

Right-click odoo/addons → Mark Directory as → Sources Root
Right-click odoo/odoo → Mark Directory as → Sources Root

5. Create Run Configuration:

Run → Edit Configurations → Add New → Python
Script path: ~/odoo-dev/odoo/odoo-bin
Parameters: -c ~/odoo-dev/odoo.conf -d odoo18-dev
Python interpreter: Your virtual environment

💡 Pro tip: Both IDEs have their strengths. VS Code is lighter and faster, PyCharm has more advanced refactoring tools. Try both and see which feels better for you.

Step 9: Enable Developer Mode and Useful Commands

Developer mode unlocks Odoo's technical features—essential for development work.

Why Developer Mode Matters:

Technical Menus: Access to database structure, security settings, view definitions
Edit View: See and edit XML behind every screen
Better Errors: Detailed Python tracebacks instead of generic messages
View Metadata: See field technical names, model names, XML IDs
Debugging Tools: Access to Python debugger, view inheritance

Enable Developer Mode:

Method 1: URL (Fastest)

Add ?debug=1 to your URL:

http://localhost:8069/web?debug=1

Method 2: Settings Menu

Click your username (top right)
Settings → Activate Developer Mode

Verify it's enabled: You'll see a bug icon 🐞 next to your username

Essential Odoo Commands:

Start Odoo:

# Basic start
./odoo-bin -c ../odoo.conf

# Specify database
./odoo-bin -c ../odoo.conf -d odoo18-dev

Update module after code changes:

# Update specific module
./odoo-bin -c ../odoo.conf -u module_name -d odoo18-dev

# Update multiple modules
./odoo-bin -c ../odoo.conf -u module1,module2 -d odoo18-dev

# Update all modules (dangerous in production!)
./odoo-bin -c ../odoo.conf -u all -d odoo18-dev

Install module:

# Install specific module
./odoo-bin -c ../odoo.conf -i module_name -d odoo18-dev

Stop Odoo:

In the terminal where Odoo is running, press Ctrl + C

Create new database from command line:

./odoo-bin -c ../odoo.conf -d new_database --db-filter=^new_database$ --stop-after-init

Run Odoo with verbose logging:

./odoo-bin -c ../odoo.conf --log-level=debug

💡 Bookmark these commands! You'll use -u module_name constantly when developing. Every time you modify code, you update the module to see changes.

Troubleshooting Common Issues

Even with perfect instructions, things can go wrong. Here's how to fix the most common problems:

Issue 1: Port 8069 Already in Use

Symptom: OSError: [Errno 98] Address already in use

Solution:

# Find process using port 8069
sudo lsof -i :8069

# Output shows PID (process ID). Kill it:
kill -9 PID_NUMBER

# Or change port in odoo.conf:
http_port = 8070

Issue 2: Python Module Import Errors

Symptom: ModuleNotFoundError: No module named 'psycopg2'

Solution:

# Make sure virtual environment is activated
source ~/odoo-dev/odoo-venv/bin/activate

# Reinstall requirements
cd ~/odoo-dev/odoo
pip install --upgrade -r requirements.txt

# For specific package issues
pip install --upgrade psycopg2-binary

Issue 3: PostgreSQL Connection Failed

Symptom: could not connect to server: Connection refused

Solution:

# Check PostgreSQL status
sudo systemctl status postgresql

# If not running, start it
sudo systemctl start postgresql

# Enable auto-start on boot
sudo systemctl enable postgresql

# Test connection manually
psql -l

Issue 4: Permission Denied Errors

Symptom: PermissionError: [Errno 13] Permission denied

Solution:

# Fix ownership of odoo-dev directory
sudo chown -R $USER:$USER ~/odoo-dev

# Fix permissions
chmod -R 755 ~/odoo-dev

# Make odoo-bin executable
chmod +x ~/odoo-dev/odoo/odoo-bin

Issue 5: Database Creation Fails

Symptom: "Master password" error or database won't create

Solution:

Check PostgreSQL user has create database permission: sudo -u postgres psql -c "ALTER USER $USER CREATEDB;"
Verify disk space: df -h (need at least 1GB free)
Check PostgreSQL logs: sudo tail -f /var/log/postgresql/postgresql-15-main.log

Getting Help When Stuck:

Official Documentation: docs.odoo.com
Community Forums: odoo.com/forum (search first, then ask)
Stack Overflow: Search with [odoo] tag
GitHub Issues: github.com/odoo/odoo/issues for bug reports
ChaosHub Comments: Leave a comment below—we monitor and help!

📸 When asking for help, always include:

Operating system and version
Python version (python3 --version)
PostgreSQL version (psql --version)
Exact error message (screenshot or copy-paste)
What you were doing when error occurred
Contents of your odoo.conf (remove passwords!)

Next Steps: You're Ready to Start Developing!

Take a moment to appreciate what you've accomplished. You now have:

✅ Python 3.10+ installed and configured
✅ PostgreSQL running and user created
✅ Odoo 18 source code downloaded
✅ Virtual environment created and activated
✅ All dependencies installed (requirements.txt)
✅ Configuration file created
✅ Odoo starts without errors
✅ Can access http://localhost:8069
✅ First database created
✅ IDE configured for development
✅ Developer mode enabled

Total setup time: 2-3 hours. That's it. You're now equipped with a professional Odoo development environment.

What's Next?

In our next post, "Understanding Odoo's Directory Structure and Architecture", we'll explore:

Where core modules live vs custom modules
How Odoo discovers and loads modules
The relationship between addons directories
Community vs Enterprise code organization
Where to place your custom development work
How the Odoo framework is structured internally

Practice Exercises (Do These Before Next Post):

Server Control: Practice starting and stopping Odoo server 3 times. Get comfortable with the commands.
Explore the Interface: Open Odoo in browser (http://localhost:8069) and click through the default apps. Look at Contacts, Calendar, Discuss.
Find Your Log File: Locate ~/odoo-dev/odoo.log and open it. Watch it update in real-time while you use Odoo.
Try Developer Mode: Enable developer mode and explore the technical menu. Click "Edit View" on a form to see XML code.
Update Base Module: Practice the update command: ./odoo-bin -c ../odoo.conf -u base -d odoo18-dev

👉 Next post: Understanding Odoo's Directory Structure

Don't skip the practice exercises—hands-on experience cements what you've learned!

Want to learn more about our Odoo development series? Visit ChaosHub About Page.

Official Odoo 18 installation documentation: Odoo 18 Installation Guide

Frequently Asked Questions

Q: Which Python version is best for Odoo 18?

A: Python 3.11 is recommended for the best balance of performance and compatibility. Odoo 18 officially supports Python 3.10, 3.11, and 3.12.

Why 3.11 specifically?

Up to 25% faster than Python 3.10 for typical operations
Thoroughly tested with Odoo 18 (most Odoo developers use it)
All dependencies in requirements.txt work smoothly
Stable and mature (released October 2022)

Can I use Python 3.12? Yes, it works, but some dependencies might show warnings. Stick with 3.11 for maximum compatibility.

What about Python 3.9 or earlier? Not supported. Odoo 18 requires 3.10 minimum.

Q: Do I need Docker for Odoo development?

A: No, Docker is completely optional for Odoo development.

Docker Pros:

Quick setup (one command gets you running)
Consistent environment across team
Easy to reset/recreate
Simulates production environment

Docker Cons:

Harder to debug (extra layer of abstraction)
Can't easily modify Odoo source code
Performance overhead on some systems
Requires learning Docker concepts

Our recommendation for learners: Start with source installation (this guide). You'll understand how Odoo works at a deeper level. Once comfortable, experiment with Docker for deployment scenarios.

Many professional Odoo developers use source installation for development and Docker for production deployment.

Q: Can I install Odoo on Windows without WSL?

A: Technically yes, but we strongly recommend against it.

Why Windows native installation is problematic:

Some dependencies don't compile properly on Windows
File path differences cause constant headaches
Production Odoo servers run on Linux—your dev environment should match
Many community modules assume Linux environment
Debugging issues is harder (less community support for Windows-specific problems)

The WSL2 solution:

WSL2 (Windows Subsystem for Linux) gives you real Linux environment inside Windows. It's free, officially supported by Microsoft, and works perfectly for Odoo development.

Install Ubuntu 22.04 via WSL2 in 10 minutes
Follow our Ubuntu instructions exactly
Access files from Windows Explorer (\\wsl$\Ubuntu-22.04)
Use Windows browsers to access localhost:8069
Best of both worlds: Windows desktop, Linux development

Installation guide: Microsoft WSL Installation

Q: How much RAM do I actually need for Odoo development?

A: Minimum 4GB, recommended 8GB+, comfortable with 16GB.

RAM usage breakdown:

Operating System: 1-2GB (Ubuntu/macOS/Windows)
Odoo Process: 500MB-1GB (increases with database size and modules)
PostgreSQL: 200-500MB
IDE (VS Code/PyCharm): 500MB-1GB
Browser: 500MB-1GB (with multiple tabs)
Other Apps: 500MB-1GB

With 4GB RAM:

Works, but you'll need to close unnecessary apps
Switching between apps might be sluggish
Can't run multiple Odoo instances simultaneously

With 8GB RAM:

Comfortable for most development work
Can run Odoo + IDE + browser + documentation
Occasional lag with heavy modules

With 16GB RAM:

Ideal for professional development
Run multiple Odoo instances (different versions/databases)
No performance concerns
Docker containers run smoothly alongside

Bottom line: You can learn Odoo with 4GB, but upgrade to 8GB+ as soon as possible for better experience.

Installation Complete Checklist

Before moving to the next tutorial, verify you have:

✓ Confirm These Items:

[ ] Python 3.10+ installed (python3.11 --version works)
[ ] PostgreSQL running (sudo systemctl status postgresql shows active)
[ ] PostgreSQL user created (psql -l works without errors)
[ ] Odoo 18 source code in ~/odoo-dev/odoo
[ ] Virtual environment created (~/odoo-dev/odoo-venv exists)
[ ] Dependencies installed (pip list shows psycopg2, lxml, etc.)
[ ] Configuration file created (~/odoo-dev/odoo.conf exists)
[ ] Odoo starts without errors (./odoo-bin -c ../odoo.conf works)
[ ] Can access http://localhost:8069 in browser
[ ] First database "odoo18-dev" created and accessible
[ ] IDE (VS Code or PyCharm) configured with Python interpreter
[ ] Developer mode enabled (bug icon visible in UI)

⏱️ Total setup time: 2-3 hours (including downloads and installations)

One-time effort — This environment will serve you for months of development!

Everything checked? Excellent! You're ready for the next lesson.

Having issues? Don't get stuck—leave a comment below or reach out in Odoo community forums. We're here to help!

This is post #2 in our "Odoo 18 Development: Zero to Hero" series. Subscribe to our blog for new posts, or follow us on social media for tips and updates.

Happy developing! 🚀

Subscribe to our newsletter

Get all the latest news, blog posts and product updates from our company, delivered directly to your inbox.

in Odoo Development

# Addons Directory Beginner Guide Beginner Tutorial Code Organization Hello World Manifest File Module Installation Module Organization Odoo 18 Structure Odoo Module Creation

ChaosHub January 29, 2026

Share this post

Our blogs

Sign in to leave a comment

Welcome to Odoo 18 Development: Your Complete Roadmap

Odoo 18 Development Complete Guide: Zero to Hero Roadmap 2026