miku@cachyos:~/Code/python-learning$ omp teach python-env --fish-first --vscode --uv

source642 行教学文档

platformCachyOS / Arch 系

shellfish-first 命令版

env manageruv + .venv

CachyOS + VS Code + uv：Python 学习环境搭建教学

适用对象：已经安装 VS Code，正在用 CachyOS / Arch 系 Linux，准备按 20 周 AI / 量化成长计划开始 Week 01：Python / Linux / Git / 数据分析基础。

核心结论
不需要把所有事情都放在命令行里做。你可以主要在 VS Code 里写代码、看文件、运行 notebook；但必须掌握少量命令行，因为 Python 环境、包管理、脚本运行、Git、项目复现都依赖这些基础命令。

本教程采用：

ompprompt

VS Code 负责：写代码、看文件、运行脚本、调试、使用 notebook
uv 负责：创建虚拟环境、安装依赖、记录项目配置
终端负责：创建目录、激活环境、运行命令、检查结果

本文命令行默认按 fish shell 写；如果某一步需要 Bash / Zsh，会单独标注。

当前机器已经具备：

ompprompt

Python 3.14.6
uv 0.11.31
VS Code 1.130.0

因此不需要从零安装 Python，直接建立学习环境即可。

1. 为什么不能完全不用命令行

你不需要成为 Linux 高手，但不能完全绕开命令行。

原因有四个：

环境隔离需要命令：每个项目应有自己的 .venv，避免不同项目的包互相污染。
安装包需要命令：例如 numpy、pandas、matplotlib、scikit-learn。
复现实验需要命令：以后别人看你的项目，需要知道如何一键安装依赖并运行。
Git 和部署需要命令：提交代码、查看状态、解决冲突，迟早会用到。

最低限度只需要会这些：

ompfish

pwd        # 看当前在哪个目录
ls         # 看当前目录有什么文件
cd         # 进入目录
mkdir      # 创建文件夹
code .     # 用 VS Code 打开当前目录
uv init    # 初始化 Python 项目
uv venv    # 创建虚拟环境
uv add     # 安装依赖
python     # 运行 Python

2. 建立统一学习目录

先给未来 20 周的学习项目留一个统一位置。

打开终端，执行：

ompfish

mkdir -p ~/Code/python-learning
cd ~/Code/python-learning
pwd

逐句解释：

命令	含义
`mkdir`	创建文件夹
`-p`	如果上级目录不存在，就一起创建；如果目录已存在，也不要报错
`~/Code/python-learning`	你的 Python 学习总目录，`~` 表示当前用户主目录
`cd`	进入这个目录
`pwd`	打印当前所在路径，用来确认你没有走错目录

如果输出类似：

ompprompt

/home/miku/Code/python-learning

说明位置正确。

3. 创建第一个 Week 01 项目

每周一个小项目，不要把所有练习都堆在一个文件夹里。

ompfish

mkdir week01-basics
cd week01-basics

建议结构：

ompprompt

week01-basics/
├── notes/       # 学习笔记
├── src/         # Python 源代码
├── data/        # 小数据文件
├── notebooks/   # Jupyter notebook
└── reports/     # 报告或总结

创建这些目录：

ompfish

mkdir -p notes src data notebooks reports

检查：

ompfish

ls

应该看到：

ompprompt

data  notebooks  notes  reports  src

4. 初始化 Python 项目

在 week01-basics 目录里执行：

ompfish

uv init

这一步会生成项目配置文件，通常包括：

ompprompt

pyproject.toml
README.md
main.py

解释：

文件	作用
`pyproject.toml`	记录项目名称、Python 版本、依赖包
`README.md`	项目说明，未来给老师、面试官或自己回看
`main.py`	默认入口脚本，可以改也可以删除

如果 uv init 提示文件已存在，不用慌，说明当前目录里已经有项目文件。

5. 创建虚拟环境 `.venv`

执行：

ompfish

uv venv

它会创建：

ompprompt

.venv/

.venv 是这个项目自己的 Python 环境。以后这个项目安装的包都放在里面，不污染系统 Python。

为什么重要：

ompprompt

系统 Python：给操作系统和系统工具用
项目 .venv：给当前学习项目用

不要把所有包直接装进系统 Python。CachyOS / Arch 是滚动发行版，系统 Python 更应该保持干净。

6. 激活虚拟环境

先确认你在真正的项目目录里，而不是只在总目录 ~/Code/python-learning 里：

ompfish

pwd
ls

如果你按本文创建的是 week01-basics 项目，那么应先进入：

ompfish

cd ~/Code/python-learning/week01-basics

判断标准：当前目录里应该能看到 pyproject.toml 和 .venv/。如果你在 ~/Code/python-learning 总目录下执行激活命令，而虚拟环境其实建在 week01-basics/.venv/，就会找错位置。

6.1 如果你使用 fish shell

你现在遇到的报错就是 fish shell 把 Bash 版激活脚本当成 fish 脚本执行了。

fish 里应执行：

ompfish

source .venv/bin/activate.fish

不要在 fish 里执行：

ompbash/zsh

source .venv/bin/activate

.venv/bin/activate 是给 Bash / Zsh 用的，里面有 变量=值 这种语法；fish 不支持这种写法，所以会报：

ompprompt

不支持使用 '='

6.2 如果你使用 bash 或 zsh

Bash / Zsh 才使用：

ompbash/zsh

source .venv/bin/activate

6.3 激活成功后的检查

成功后，终端提示符前面通常会出现：

ompprompt

(.venv)

这表示当前终端已经进入项目环境。

验证 Python 路径：

ompfish

command -v python
python --version

你希望看到的 command -v python 应该类似：

ompprompt

/home/miku/Code/python-learning/week01-basics/.venv/bin/python

如果看到的是 /usr/bin/python，说明虚拟环境没有激活成功，或者你不在创建 .venv 的项目目录里。

7. 安装第一批学习包

Week 01 到 Week 04 建议安装：

ompfish

uv add numpy pandas matplotlib jupyter ipykernel

逐个解释：

包	用途
`numpy`	数值计算，数组、矩阵、随机数
`pandas`	表格数据处理，CSV、DataFrame
`matplotlib`	基础画图
`jupyter`	notebook 环境
`ipykernel`	让 VS Code / Jupyter 使用当前虚拟环境

安装完成后，pyproject.toml 会记录这些依赖。以后别人拿到你的项目，可以根据配置恢复环境。

8. 用 VS Code 打开项目

确认你还在项目目录：

ompfish

pwd

然后执行：

ompfish

code .

含义：用 VS Code 打开当前目录。

不要只打开单个 .py 文件，应该打开整个项目文件夹。这样 VS Code 才能识别 .venv、pyproject.toml、目录结构和相对路径。

9. 在 VS Code 里选择 Python 解释器

打开 VS Code 后：

按 Ctrl + Shift + P。
输入 Python: Select Interpreter。
选择当前项目的解释器：

ompprompt

.venv/bin/python

如果列表里没看到，可以手动选择：

ompprompt

/home/miku/Code/python-learning/week01-basics/.venv/bin/python

这一步的意义：告诉 VS Code 使用当前项目环境，而不是系统 Python。

10. 写第一个脚本

在 src/ 下新建文件：

ompprompt

src/hello.py

内容：

omppython

print("Hello, Python")
scores = [85, 92, 78]
mean_score = sum(scores) / len(scores)
print(mean_score)

用终端运行：

ompfish

python src/hello.py

应该输出：

ompprompt

Hello, Python
85.0

如果 VS Code 右上角运行按钮也能跑出同样结果，说明解释器配置正确。

11. 写第一个 pandas 练习

新建：

ompprompt

src/pandas_demo.py

内容：

omppython

import pandas as pd
data = {
“name”: [“Alice”, “Bob”, “Cindy”],
“score”: [85, 92, 78],
}
df = pd.DataFrame(data)
print(df)
print(“mean score:”, df[“score”].mean())

运行：

ompfish

python src/pandas_demo.py

如果能看到表格和平均分，说明：

ompprompt

Python 能运行
pandas 已安装
VS Code 项目路径正确
虚拟环境可用

12. 建立 notebook

在 VS Code 里新建：

ompprompt

notebooks/week01.ipynb

第一次打开 notebook 时，右上角选择 Kernel：

ompprompt

.venv/bin/python

新建一个 cell：

omppython

import pandas as pd
pd.DataFrame({“x”: [1, 2, 3], “y”: [2, 4, 6]})

如果表格正常显示，notebook 环境配置成功。

13. 推荐项目结构

Week 01 最终建议变成：

ompprompt

week01-basics/
├── .venv/
├── data/
│   └── scores.csv
├── notebooks/
│   └── week01.ipynb
├── notes/
│   └── week01-python.md
├── reports/
│   └── week01-summary.md
├── src/
│   ├── hello.py
│   └── pandas_demo.py
├── pyproject.toml
├── README.md
└── uv.lock

其中：

路径	说明
`.venv/`	虚拟环境，不手动编辑，不提交到 Git
`data/`	小数据文件
`notebooks/`	交互式分析
`notes/`	学习笔记
`reports/`	阶段总结
`src/`	正式 Python 脚本
`pyproject.toml`	项目依赖配置
`uv.lock`	锁定依赖版本，保证复现

14. Git 初始化

如果你要把练习当成项目积累，建议从 Week 01 就用 Git。

ompfish

git init

创建 .gitignore：

ompfish

printf "%s\n" ".venv/" "__pycache__/" ".ipynb_checkpoints/" "*.pyc" ".env" > .gitignore

解释：

条目	为什么忽略
`.venv/`	虚拟环境很大，可以重建，不应提交
`__pycache__/`	Python 自动缓存
`.ipynb_checkpoints/`	Jupyter 自动生成
`*.pyc`	编译缓存
`.env`	可能包含 API key

查看状态：

ompfish

git status

提交：

ompfish

git add README.md pyproject.toml uv.lock src notes notebooks reports data .gitignore
git commit -m "init python learning environment"

如果你暂时还不熟 Git，可以先不提交，但至少要理解 .venv/ 不该放进仓库。

15. 以后每天怎么用

每次重新打开项目，如果你使用 fish：

ompfish

cd ~/Code/python-learning/week01-basics
source .venv/bin/activate.fish
code .

如果你使用 bash / zsh：

ompbash/zsh

cd ~/Code/python-learning/week01-basics
source .venv/bin/activate
code .

如果只在 VS Code 里运行，解释器选好后不一定每次都要手动激活；但只要你在终端里运行 python，建议先激活。

16. 常见错误排查

16.1 VS Code 找不到 pandas

现象：

ompprompt

ModuleNotFoundError: No module named 'pandas'

检查：

ompfish

command -v python
python -c "import pandas as pd; print(pd.__version__)"

如果终端能导入，但 VS Code 不能，说明 VS Code 解释器没选 .venv/bin/python。

16.2 终端前面没有 `(.venv)`

先确认当前目录：

ompfish

pwd
ls

如果你在 ~/Code/python-learning 总目录，先进入具体项目：

ompfish

cd ~/Code/python-learning/week01-basics

fish 用户重新激活：

ompfish

source .venv/bin/activate.fish

bash / zsh 用户重新激活：

ompbash/zsh

source .venv/bin/activate

16.3 不知道当前在哪个目录

执行：

ompfish

pwd
ls

如果看不到 pyproject.toml，说明你不在项目根目录。

16.4 uv add 失败

先检查网络和当前目录：

ompfish

pwd
uv --version

确认在项目目录后再执行：

ompfish

uv add pandas

17. Week 01 验收清单

完成后你应该能做到：

能解释 .venv 是什么。
能用 uv add 安装包。
能在 VS Code 里选择 .venv/bin/python。
能运行 python src/hello.py。
能运行 pandas 示例。
能创建 notebook 并选择当前 kernel。
知道 .venv/ 不应该提交到 Git。
知道如何从终端进入项目目录。

18. 最小命令速查

18.1 创建项目

ompfish

mkdir -p ~/Code/python-learning/week01-basics
cd ~/Code/python-learning/week01-basics

18.2 初始化环境

ompfish

uv init
uv venv

18.3 激活环境

fish 用户执行：

ompfish

source .venv/bin/activate.fish

bash / zsh 用户才执行：

ompbash/zsh

source .venv/bin/activate

18.4 安装包

ompfish

uv add numpy pandas matplotlib jupyter ipykernel

18.5 打开 VS Code

ompfish

code .

18.6 运行脚本

ompfish

python src/hello.py

19. 和 20 周计划的关系

这篇文档对应 20 周 AI / 量化成长计划的：

ompprompt

Phase 1 / Week 01：环境与 Python 基础

完成本文后，你就可以进入下一步：

ompprompt

Week 01：Python 基础语法、函数、列表、字典、字符串、文件读写
Week 02：Python 进阶 + Linux 工作流
Week 03：NumPy / Pandas
Week 04：可视化 + EDA 报告

最终目标不是“装好了环境”，而是能持续产出可运行、可复现、可解释的小项目。

plain

CachyOS + VS Code + uv：Python 学习环境搭建教学

CachyOS + VS Code + uv：Python 学习环境搭建教学

1. 为什么不能完全不用命令行

2. 建立统一学习目录

3. 创建第一个 Week 01 项目

4. 初始化 Python 项目

5. 创建虚拟环境 .venv

6. 激活虚拟环境

6.1 如果你使用 fish shell

6.2 如果你使用 bash 或 zsh

6.3 激活成功后的检查

7. 安装第一批学习包

8. 用 VS Code 打开项目

9. 在 VS Code 里选择 Python 解释器

10. 写第一个脚本

11. 写第一个 pandas 练习

12. 建立 notebook

13. 推荐项目结构

14. Git 初始化

15. 以后每天怎么用

16. 常见错误排查

16.1 VS Code 找不到 pandas

16.2 终端前面没有 (.venv)

16.3 不知道当前在哪个目录

16.4 uv add 失败

17. Week 01 验收清单

18. 最小命令速查

18.1 创建项目

18.2 初始化环境

18.3 激活环境

18.4 安装包

18.5 打开 VS Code

18.6 运行脚本

19. 和 20 周计划的关系

5. 创建虚拟环境 `.venv`

16.2 终端前面没有 `(.venv)`