Step-by-Step Guide to Creating Python Virtual Environments on Ubuntu

When you're developing Python applications, properly managing your project's dependencies is crucial. Using virtual environments helps you isolate each project's dependencies, preventing conflicts and simplifying your workflow.

In this short guide, you'll learn step-by-step how to set up and manage Python virtual environments cleanly on Ubuntu.

---

🔧 Step 1 – Install Python and tools

First, make sure you have Python installed. On Ubuntu, Python usually comes pre-installed, but let's ensure everything is up-to-date and install the necessary packages:

sudo apt update
sudo apt install python3 python3-pip python3-venv

---

📁 Step 2 – Creating your project folder

Start by creating a dedicated folder for your project and navigating into it:

mkdir my-python-project
cd my-python-project

---

🌱 Step 3 – Create your virtual environment (.venv)

Inside your project folder, create a hidden virtual environment. Naming it .venv ensures it remains hidden by default, keeping your project tidy:

python3 -m venv .venv

You now have a virtual environment located at my-python-project/.venv.

---

🚀 Step 4 – Activate your virtual environment

To start using your virtual environment, activate it with:

source .venv/bin/activate

Your prompt should change, indicating the virtual environment is active, for example:

(.venv) user@machine:~/my-python-project$

To deactivate it later, simply type:

deactivate

---

📦 Step 5 – Managing dependencies with pip

With your virtual environment activated, install your project's dependencies using pip.

For example, installing the popular requests library:

pip install requests

To save your current dependencies into a requirements.txt file (useful for version control and sharing):

pip freeze > requirements.txt

To install dependencies from an existing requirements.txt file (e.g., when cloning a project):

pip install -r requirements.txt

---

🚫 Step 6 – Setting up .gitignore

Although Git typically doesn't include hidden folders by default, it’s best practice to explicitly specify folders and files you want to exclude. Create a .gitignore file in your project root to exclude your environment and common Python caches:

touch .gitignore

Then edit your .gitignore file with the following content:

# Python virtual environment
.venv/

# Python cache and compiled files
__pycache__/
*.pyc
*.pyo
*.pyd

# Python distribution/build files
build/
develop-eggs/
dist/
.eggs/
*.egg-info/
*.egg

# Misc
.cache/
.vscode/
.idea/

---

⚙️ Step 7 – Quick practical example

Here’s a minimal example of setting up a new project using Flask as a quick recap:

# Create and enter project directory
mkdir flask-example && cd flask-example

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install Flask
pip install Flask
pip freeze > requirements.txt

Here's a minimal Flask app you could use to test:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
    return "Hello from Flask in a clean virtual environment!"

if __name__ == '__main__':
    app.run(debug=True)

Run your application:

python app.py

Visit http://127.0.0.1:5000 in your browser, and you should see your Flask app running smoothly!

---

⚠️ Common pitfalls

🔴 Issue: Virtual environment not activating

Cause: Possibly using incorrect path.

Solution: Double-check your environment path and ensure you’re sourcing it from the correct directory.

source .venv/bin/activate

🔴 Issue: Dependencies not recognized after activation

Cause: You may have installed dependencies outside your virtual environment.

Solution: Always activate your virtual environment before installing dependencies with pip.

---

🎯 Best practices

• Always use a virtual environment per Python project.

• Clearly name your project directories and virtual environments.

• Include your .venv directory and common caches explicitly in .gitignore.

• Regularly update and maintain your requirements.txt for easy collaboration.

---

🚀 Conclusion

Using virtual environments for Python development under Ubuntu greatly enhances your workflow by isolating dependencies and avoiding conflicts.

Adopt this clean and simple approach systematically, and your Python projects will stay organized, maintainable, and conflict-free!

Happy Python coding! 🐍✨