Master Odoo 19 Installation on Mac: The Ultimate Guide

Welcome to the cutting edge of business management! Odoo has consistently proven itself as a powerful, all-in-one ERP solution, and with the upcoming Odoo 19, its capabilities are set to expand even further. If you’re a Mac user eager to harness this robust system for your business or development projects, you’re in the right place. This guide will walk you through exactly how to install Odoo 19 Mac edition, ensuring a smooth and successful setup.

Odoo offers a unified suite of applications, covering everything from CRM and sales to accounting, manufacturing, and project management. Installing it locally provides an unparalleled environment for development, testing, and even running a small instance of your business operations. While the official Odoo 19 stable release is still anticipated, the development (master) branch offers an exciting peek into its future. This tutorial focuses on getting that development version up and running on your Apple machine.

Our goal is to demystify the installation process, breaking it down into manageable, actionable steps. By the end of this comprehensive guide, you’ll have Odoo 19 running on your Mac, ready for exploration and customization. Let’s dive in!

Before You Begin: Essential Prerequisites for Odoo 19

Before we jump into the core installation, ensuring your Mac is ready will save you a lot of headaches. Setting up the right environment is crucial for a stable Odoo 19 instance.

1. Python 3.10 or Higher

Odoo 19 specifically requires Python 3.10 or a more recent version. Earlier versions will not work.

• Check Your Python Version: Open your Mac’s Terminal application (you can find it in Applications > Utilities). Type python3 --version and press Enter. If you see a version older than 3.10 (e.g., Python 3.9.x) or if python3 isn’t found, you’ll need to install a newer version.

• Installing Python:

  • Homebrew (Recommended for Mac): If you don’t have Homebrew, install it by running /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" in your Terminal. Once Homebrew is installed, you can easily install Python 3.10+ by running brew install python@3.12 (or the latest stable version). Homebrew simplifies managing software on macOS.
  • Official Python Website: Alternatively, you can download the installer directly from the official Python website.

• Verify Installation: After installation, run python3 --version again to confirm you have the correct version.

2. PostgreSQL Database

Odoo relies on PostgreSQL as its database backend. You must have PostgreSQL installed and running on your system.

• Install PostgreSQL:

  • Homebrew: The easiest way to install PostgreSQL on a Mac is via Homebrew: brew install postgresql.
  • Postgres.app: For a more graphical and user-friendly installation, consider using Postgres.app, which provides a simple way to set up and manage PostgreSQL servers.

• Start PostgreSQL: After installation, ensure your PostgreSQL server is running. If you used Homebrew, you might need to run brew services start postgresql. Postgres.app usually starts automatically.

• Create Odoo User: Odoo needs a dedicated PostgreSQL user with appropriate permissions. Open your Terminal and execute the following commands.

  • createuser --createdb --username=postgres odoo (This creates a user named odoo with database creation privileges, using the default postgres superuser.)
  • psql -U postgres -d postgres -c "ALTER USER odoo WITH PASSWORD 'odoo';" (This sets the password for the odoo user to ‘odoo’. You can change ‘odoo’ to a stronger password, but remember it for your Odoo configuration file.)

• Verify: You can try to log in as the odoo user to confirm: psql -U odoo -d postgres. If successful, type \q to exit.

3. PyCharm (Recommended IDE)

While you can technically run Odoo from any terminal, PyCharm (the Community Edition is free) offers excellent features for Python development, including integrated terminal, virtual environment management, and run/debug configurations, which greatly simplify the Odoo setup.

• Download PyCharm: Download PyCharm Community Edition from the JetBrains website.

With these prerequisites handled, you’re now ready to proceed with the core steps to install Odoo 19 Mac version.

Step-by-Step Guide to Install Odoo 19 Mac

This section provides a detailed, step-by-step tutorial to get Odoo 19 up and running on your Mac.

1. Download Odoo 19 Source Code

Odoo’s development versions are hosted on GitHub. For Odoo 19, we’ll be downloading the ‘master’ branch.

• Navigate to GitHub: Open your web browser and search for “Odoo 19 GitHub” or go directly to the Odoo GitHub repository.

• Select Master Branch: On the GitHub page, you’ll see a dropdown menu that typically says “main” or “17.0”. Click on this dropdown and select master. This branch represents the active development for the next major version, which is Odoo 19.

  • Important Note: As mentioned, the ‘master’ branch is a development version. It might contain bugs, unfinished features, or be unstable. It’s not recommended for production environments until the stable Odoo 19 release.

• Download the Code:

  • Click on the green “Code” button.
  • Choose “Download ZIP”. This will download a .zip file containing the entire Odoo 19 source code.
  • Alternatively, if you’re familiar with Git, you can clone the repository using git clone https://github.com/odoo/odoo.git.

• Unzip and Organize: Once downloaded, locate the odoo-master.zip file (or similar) in your Downloads folder. Unzip it. We recommend moving the unzipped folder to a clean, easily accessible location on your hard drive, for example, ~/Documents/odoo19/ or ~/Development/odoo19/. Rename the folder to something like odoo19 for clarity. This will be your Odoo 19 directory.

2. Open the Project in PyCharm

PyCharm provides a structured environment that makes managing your Odoo project much simpler.

• Launch PyCharm: Open PyCharm on your Mac.
• Open Project: From the PyCharm welcome screen, select “Open”. Navigate to the odoo19 directory you just unzipped and moved. Click “Open”.
• Trust Project: PyCharm might ask if you “Trust Project”. Since you downloaded it from a reputable source (Odoo’s official GitHub), you can safely click “Trust Project”.

3. Create a Python Virtual Environment

A virtual environment is critical for managing Python dependencies. It isolates your Odoo 19 project’s dependencies from other Python projects on your system, preventing conflicts.

• PyCharm’s Automatic Prompt: When you open the Odoo 19 project in PyCharm, it often detects a requirements.txt file and prompts you to create a virtual environment. Look for a notification in the bottom-right corner that says “No interpreter configured” or suggests “Create Virtual Environment”.

  • Click on this notification.
  • Choose “New environment” or “Virtualenv Environment”.
  • Ensure the “Base interpreter” is set to Python 3.10 or higher (the one you installed earlier).
  • PyCharm will suggest a location for the virtual environment (usually venv or .venv inside your project directory). Accept the default or choose a preferred location.
  • Click “OK” or “Create”. PyCharm will then create the virtual environment and start indexing it. This might take a few moments.

• Manual Creation (Terminal Alternative): If PyCharm doesn’t prompt you, or if you prefer the command line:

  • Open PyCharm’s integrated Terminal (View > Tool Windows > Terminal, or Alt+F12).
  • Navigate to your odoo19 project directory if you’re not already there (cd path/to/odoo19).
  • Run python3 -m venv .venv. This creates a new directory named .venv (or whatever you name it) containing the isolated Python environment.
  • Activate the environment: source .venv/bin/activate. You’ll know it’s active when your terminal prompt changes to include (.venv) or the name of your virtual environment.

4. Create a Custom Configuration File

Running Odoo with a configuration file (.conf) is standard practice. It allows you to manage settings like database connection, passwords, and addon paths easily.

• Create the File: In PyCharm, right-click on the odoo19 project folder in the Project explorer (left sidebar). Select “New” > “File”. Name the file custom.conf (or any name you prefer, but remember it).

• Add Configuration Details: Paste the following content into your custom.conf file. Crucially, replace placeholder values with your specific details.

  [options]
  ; Master password for database operations (backup, restore, delete)
  admin_passwd = your_strong_admin_password_here
  
  ; Database connection details
  db_host = localhost
  db_port = 5432
  db_user = odoo
  db_password = odoo_postgres_password ; Use the password you set for the 'odoo' user in Postgres
  
  ; Add-ons path - REQUIRED for Odoo to find modules
  ; Adjust this path based on your Odoo 19 directory structure
  ; The first path is for official modules, the second is for custom modules
  addons_path = /path/to/your/odoo19/addons,/path/to/your/odoo19/odoo/addons
  
  ; Odoo server port
  xmlrpc_port = 8069
  
  ; Increase memory limits for handling larger operations (optional but recommended)
  limit_memory_soft = 2048MB
  limit_memory_hard = 2560MB
  ; limit_time_cpu = 600
  ; limit_time_real = 1200
  
  ; Logging (optional)
  ; log_level = info
  ; logfile = /path/to/your/odoo19/odoo.log
  
  ; Filter databases (optional - remove or set to false to see all dbs)
  ; db_filter = odoo19_custom
  

• Adjust addons_path: This is the most common pitfall when you install Odoo 19 Mac. You must replace /path/to/your/odoo19/ with the actual absolute path to your odoo19 folder. For example, if your odoo19 folder is in ~/Development/odoo19, your addons_path would be:
  addons_path = /Users/yourusername/Development/odoo19/addons,/Users/yourusername/Development/odoo19/odoo/addons
  To get the absolute path, right-click your odoo19 folder in Finder, hold Option key, and select “Copy odoo19 as Pathname”.

• Set Passwords: Replace your_strong_admin_password_here with a secure master password for Odoo’s internal database management. Also, replace odoo_postgres_password with the password you set for the odoo PostgreSQL user earlier.

5. Install Python Dependencies

Odoo has numerous Python libraries it depends on. These are listed in the requirements.txt file within the Odoo 19 source code.

• Open PyCharm Terminal: Ensure your PyCharm’s integrated Terminal is open (View > Tool Windows > Terminal).

• Activate Virtual Environment (if necessary): Confirm your virtual environment is active. You should see its name in parentheses at the start of your terminal prompt (e.g., (.venv) user@macbook odoo19 %). If not, activate it: source .venv/bin/activate.

• Install Requirements: Run the following command:

  pip3 install -r requirements.txt
  

  This command tells pip (Python’s package installer) to install all packages listed in requirements.txt into your currently active virtual environment. This process might take several minutes as it downloads and compiles various libraries.

• Troubleshooting pip install:

  • If you encounter errors related to specific packages (e.g., psycopg2-binary), ensure you have PostgreSQL headers and development tools installed (Homebrew often handles this, but sometimes specific libraries need brew install libpq or similar).
  • Another common issue is missing command-line developer tools. You might need to run xcode-select --install in your Terminal if you see build errors.
  • Don’t panic if you see warnings; focus on errors. If an error persists, search for the specific error message online (Odoo forums or Stack Overflow are great resources).

6. Configure Run/Debug Configuration in PyCharm

Setting up a run configuration in PyCharm allows you to start, stop, and debug Odoo directly from the IDE.

• Access Configurations: Go to “Run” > “Edit Configurations…” in PymCharm’s top menu bar.

• Add New Python Configuration:

  • Click the + button in the top left of the “Run/Debug Configurations” window.
  • Select “Python”.

• Configure Details:

  • Name: Give it a descriptive name, like Odoo 19 Local or Run Odoo.
  • Script path: This should point to the odoo-bin executable within your odoo19 directory. Click the folder icon next to “Script path”, navigate into your odoo19 folder, and select odoo-bin.
  • Parameters: Enter -c custom.conf. This tells Odoo to use your custom configuration file.
  • Python interpreter: Ensure this is set to your virtual environment’s interpreter (e.g., Python 3.12 (Odoo 19) ~/.venv/bin/python).
  • Working directory: Set this to your main odoo19 project folder. Click the folder icon and select your odoo19 directory.
• Apply and OK: Click “Apply” then “OK”.

7. Run Odoo 19

With everything configured, it’s time to launch your Odoo 19 instance!

• Run from PyCharm: In the top right corner of PyCharm, next to the green “Run” (play) button, select your newly created “Odoo 19 Local” (or whatever you named it) configuration from the dropdown. Then, click the green “Run” button.
• Monitor Output: A “Run” window will appear at the bottom of PyCharm, displaying Odoo’s server logs. Look for lines indicating the server is starting up and listening on the specified port (default: 8069). You should see messages like “listening on 0.0.0.0:8069” and “Odoo server started”.

• Common Issues:

  • Port in use: If port 8069 is already in use, Odoo will throw an error. You can change xmlrpc_port in your custom.conf file to another port, like 8070.
  • Database connection errors: Double-check your db_host, db_port, db_user, and db_password in custom.conf against your PostgreSQL setup. Ensure PostgreSQL is running and the odoo user has the correct password.

8. Create the Odoo Database

Once the Odoo server is running, you’ll need to create a new database to store your Odoo data.

• Open Browser: Open your web browser (Safari, Chrome, Firefox, etc.) and navigate to:
  http://localhost:8069/web/database/manager
  (If you changed xmlrpc_port in your custom.conf, replace 8069 with your chosen port).

• Database Manager: You will be greeted by the Odoo database manager interface.

• Create Database:

  • Master Password: Enter the admin_passwd you defined in your custom.conf file. This is crucial.
  • Database Name: Choose a unique and descriptive name for your database (e.g., my_odoo19_db, company_name_odoo19).
  • Email: Enter an email address for the administrator user of this specific database.
  • Password: Set a password for the administrator user of this database. This is the password you’ll use to log into Odoo itself.
  • Phone Number/Language/Country: Fill these in if desired.
  • Load Demo Data: Check the “Load demonstration data” box if you want sample data (like demo sales orders, products, customers) to be pre-filled for practice. This is highly recommended for new users.
• Click “Create Database”: Odoo will now create your database. This might take a few moments.

9. Access Odoo 19

Congratulations! Your Odoo 19 instance is now ready to use.

• Login: After the database creation is complete, Odoo will automatically redirect you to the login screen. Use the Email and Password you set for the database administrator (in the previous step) to log in.
• Explore: You’ll be welcomed by the Odoo dashboard. Take some time to explore the interface.

10. Install Modules (Optional but Recommended)

Odoo’s power comes from its modular design. You can install apps (modules) as needed.

• Navigate to Apps: From the Odoo dashboard, click on the “Apps” icon (usually represented by a grid of squares).
• Search and Install: You’ll see a list of available Odoo modules. Use the search bar to find modules like “Sales”, “Inventory”, “CRM”, etc. Click “Activate” on any module you wish to install.
• Dependencies: Odoo will automatically install any dependencies required by the module you choose.

Important Considerations and Troubleshooting

Setting up complex software like Odoo can sometimes present challenges. Here are some key points and common troubleshooting tips:

• PostgreSQL User and Permissions: A frequent issue is incorrect PostgreSQL user setup. Ensure the odoo user exists and has CREATEDB privileges, and that the password matches what’s in your custom.conf. Always restart PostgreSQL after making user changes.
• addons_path Accuracy: Re-verify that your addons_path in custom.conf points to the correct absolute paths of the Odoo source addons folders. If Odoo can’t find its core modules, it won’t start.
• Virtual Environment Activation: If you run pip install -r requirements.txt or start Odoo from a terminal outside PyCharm, always ensure your virtual environment is activated (source .venv/bin/activate).
• Error Logs: When Odoo doesn’t start or behaves unexpectedly, the first place to look is the error log in PyCharm’s Run window (or your terminal). Specific error messages are your best clue for searching for solutions online.

• Community Support: The Odoo community is vast and helpful. If you encounter persistent issues, don’t hesitate to:

  • Search Odoo’s official forum.
  • Check Stack Overflow for similar problems and solutions.
  • Review the Odoo documentation.

By following these guidelines, you’ll be well-equipped to handle most installation hurdles when you install Odoo 19 Mac.

Your Odoo 19 Journey Begins!

You’ve successfully completed the process to install Odoo 19 Mac edition. This is a significant first step towards leveraging a powerful ERP system for your needs, whether for development, testing, or managing your business operations.

Odoo 19 offers a world of possibilities, from streamlining sales and improving customer relationships to optimizing inventory and automating accounting. With your local installation, you have the flexibility to experiment, customize, and truly understand how Odoo can transform your workflow.

We encourage you to dive deeper, explore the various applications, and start adapting Odoo to fit your unique requirements. If you encounter any questions or run into specific challenges during your Odoo 19 journey, feel free to leave a comment below. We’re here to help you unlock the full potential of this incredible open-source ERP. Happy Odoo-ing!