How To Install the Django Web Framework on Ubuntu 22.04

Table of Contents#

1. Prerequisites
2. Step 1: Update System Packages
3. Step 2: Install Python and Pip
4. Step 3: Create a Virtual Environment (Best Practice)
5. Step 4: Install Django
6. Step 5: Verify Installation (Create a Test Project)
7. Step 6: Deactivate the Virtual Environment
8. Best Practices for Django Development
9. Common Issues and Troubleshooting
10. Conclusion
11. References

Prerequisites#

• A system running Ubuntu 22.04 LTS (local or remote via SSH).
• Basic familiarity with the Linux terminal (navigating directories, running commands).
• Internet access to download packages.

Step 1: Update System Packages#

Before installing software, update your system’s package index and upgrade existing packages (for security and stability):

sudo apt update
sudo apt upgrade -y

The -y flag automatically confirms prompts to avoid manual intervention.

Step 2: Install Python and Pip#

Ubuntu 22.04 ships with Python 3.10 pre-installed. Django requires Python, so we’ll verify it and install pip (Python’s package manager) if needed.

Check Python Version#

Run:

python3 --version

Output (example):

Python 3.10.12

Install pip (if not already installed)#

Most Ubuntu installations include pip for Python 3, but if not, install it with:

sudo apt install python3-pip

Verify pip is installed:

pip3 --version

Output (example):

pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)

Step 3: Create a Virtual Environment (Best Practice)#

A virtual environment isolates your project’s dependencies from the system-wide Python packages. This prevents conflicts (e.g., one project needs Django 4.0, another needs 3.2).

We use Python’s built-in venv module (no additional installation needed).

Create a Virtual Environment#

Choose a name (e.g., myenv):

python3 -m venv myenv

Activate the Virtual Environment#

To activate it (your terminal prompt will show the environment name):

source myenv/bin/activate

Output (example):

(myenv) user@ubuntu:~$

Step 4: Install Django#

With the virtual environment active, install Django using pip. You can install the latest version or a specific version (recommended for consistency).

Install the Latest Django#

For the latest stable release:

pip install django

Install a Specific Version (Optional)#

To install a specific version (e.g., Django 4.2.1):

pip install django==4.2.1

Verify Installation#

Check the installed Django version:

django-admin --version

Output (example):

4.2.1

Step 5: Verify Installation (Create a Test Project)#

Let’s create a simple Django project to confirm everything works.

Create a New Project#

Use django-admin to start a new project (replace mysite with your project name):

django-admin startproject mysite

Navigate to the Project Directory#

cd mysite

Run the Development Server#

Django includes a built-in development server for testing:

python manage.py runserver

Output (example):

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).

You have 18 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.
August 21, 2023 - 12:34:56
Django version 4.2.1, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Access the Server in a Browser#

Open your web browser and go to http://127.0.0.1:8000/. You should see the Django welcome page.

Step 6: Deactivate the Virtual Environment#

When you’re done working, deactivate the virtual environment:

deactivate

Your terminal prompt will return to its original state (no environment name).

Best Practices for Django Development#

1. Use Virtual Environments Consistently#

Always create a virtual environment for each Django project to isolate dependencies (avoids version conflicts).

2. Track Dependencies with requirements.txt#

After installing packages, save them to a requirements.txt file (e.g., for sharing or deployment):

pip freeze > requirements.txt

To install from this file later:

pip install -r requirements.txt

3. Secure Your Project#

• Keep the SECRET_KEY (in settings.py) secret (e.g., use environment variables in production).
• Avoid checking settings.py (or .env files) into public version control (use .gitignore).

4. Use Version Control (e.g., Git)#

Initialize a Git repository in your project directory:

git init
git add .
git commit -m "Initial Django project setup"

5. Plan for Production#

For a production server:

• Use a production-ready web server (e.g., Gunicorn for application serving, Nginx for reverse proxy).
• Configure a database (e.g., PostgreSQL instead of SQLite for production).
• Set DEBUG = False in settings.py and configure ALLOWED_HOSTS.

Common Issues and Troubleshooting#

1. Permission Errors in Virtual Environment#

Avoid using sudo inside a virtual environment (it installs packages system-wide, defeating isolation). If you get a permission error, ensure your user owns the virtual environment directory.

2. Python Version Conflicts#

If you have multiple Python versions, specify python3 (or the desired version) when creating the virtual environment:

python3.10 -m venv myenv

3. django-admin Command Not Found#

Ensure your virtual environment is active, or check that Django was installed in the correct environment.

4. Outdated pip#

Upgrade pip to avoid installation issues:

pip install --upgrade pip

Conclusion#

You’ve successfully installed Django on Ubuntu 22.04 using a virtual environment! This setup provides a clean, isolated space to develop your web applications. From here, you can:

• Explore Django’s features (e.g., creating apps, models, views).
• Follow best practices to secure and scale your project.
• Deploy to a production server with tools like Gunicorn, Nginx, and PostgreSQL.

References#

• Django Official Documentation
• Python venv Documentation
• Ubuntu 22.04 Python Guide (adapted for 22.04)
• Django Deployment Guide

Happy coding with Django! 🚀