pythonstock/stock V3.0: a Docker-deployed Python stock analysis system

What pythonstock/stock is for, and the disclaimer it leads with

The README opens with a warning rather than a feature list: stock markets carry risk, the project is for Python code study and stock analysis, and losing money on an investment is not a bug. That framing matters. This is a teaching and experimentation codebase that happens to fetch real market data, not a signal service you are meant to trust with capital.

The target reader is a Python developer who wants to see a complete pipeline rather than a library: data capture, storage, indicator math, an API, and a browser UI. The project has been on GitHub and Gitee since 2017, and the README states it was created on 2017-07-17 with irregular monthly updates. The current generation, V3.0, is described as an integration release: the frontend was rewritten in Vue, the backend moved to an API, and deployment moved to docker-compose. The stack is pandas 2.2.3, numpy 2.2.1, sqlalchemy 2.0.36, akshare 1.15.59, bokeh 3.6.2 and stockstats 0.3.2, all pinned in the README.

How the pipeline works: akshare in, MariaDB storage, Tornado API out

Everything is Python, and the README gives that as the design reason: the libraries call each other without a language boundary between capture, calculation and display. The repository is split into four directories plus the deployment folder: jobs holds the fetch-and-store code, libs holds shared utilities, web is the display layer, supervisor manages processes, and docker-compose and frontend sit alongside them.

Data comes from akshare. V2.0 replaced tushare with akshare because, in the README's words, some libraries could not be used. Storage is MariaDB (MySQL compatible), with a schema named stock_data created with utf8 collation. Indicator math runs through pandas, numpy, stockstats and ta-lib, and the results land in tables such as guess_indicators_daily. The README also names two derived tables, guess_indicators_lite_buy_daily and guess_indicators_lite_sell_daily, which hold buy and sell condition results.

Two operational details are worth knowing before you read the code. First, the fetch layer caches data per day to avoid being blocked by the upstream interface: it keeps roughly three days of data in gzip-compressed pickle files and clears old files on a schedule. Second, a cron job starts around 18:00 each day, because the README notes that today's data is only available around then, and computes the day's indicators using 300 days of history. The README puts that run at about 15 minutes.

The 17 indicators and the web pages they feed

The calculation table in the README lists 17 indicators computed into guess_indicators_daily: volume delta, n-day differences, n-day percentage change, CR, rolling max and min, KDJ, SMA, MACD, BOLL, RSI, W%R, TR and ATR, DMA, DMI with +DI, -DI, DX, ADX and ADXR, TRIX and MATRIX, and VR with MAVR. Each entry links to an MBAlib wiki page explaining the indicator, and the KDJ and RSI entries spell out the overbought and oversold thresholds the project uses, such as K above 80 and D above 70 for KDJ overbought, and RSI above 80 or below 20.

On the display side, the README describes a generic data presentation system: configure a dictionary template, and the page loads and renders the data automatically, so indicators you add later can be wired in without new frontend work. Clicking an indicator opens a Bokeh chart, and the README says up to 17 indicators can be plotted. There is also a jump to the East Money page for a given stock. The data pages named in the README cover daily stock data from East Money, the dragon-tiger list (individual stock appearances) from Sina, and block trade quotes from the data center.

My read is that the template-driven display is the most reusable idea in the repository, and the indicator table is the most copied. The indicator definitions themselves are textbook, so the value is in the plumbing, not the formulas.

Installing pythonstock/stock with docker-compose and running the first job

The README's deployment path is Docker plus docker-compose, and it gives the install commands directly. This installs Docker and then places the compose binary at /usr/local/bin/docker-compose:

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
curl -L "https://www.ghproxy.cn/https://github.com/docker/compose/releases/download/v2.23.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

With Docker in place, the production path compiles the frontend and starts the stack. The development path uses the node dev setup instead:

docker-compose up -d
docker-compose -f dev-docker-compose.yml up -d

Once the containers are running, the README shows how to enter the container and trigger the daily job by hand. Start the container first, then exec in and run the script:

docker exec -it stock bash
sh /data/stock/jobs/cron.daily/run_daily

When the container starts it calls run_init.sh to initialize data, and the README states that the first execution of the day's data runs in the background. After that, the cron schedule handles the daily fetch and calculation. The README gives two ports to check: http://localhost:8080 for the frontend and http://localhost:9090 for the backend API. If you are running the stack outside the provided compose file, the database has to exist first, and the README supplies the statement:

CREATE DATABASE IF NOT EXISTS `stock_data` CHARACTER SET utf8 COLLATE utf8_general_ci;

Where the project is thin: documentation, akshare coupling and the buy/sell tables

The first limitation is documentation language and depth. The README is in Chinese, and the operational guidance is a set of commands and a changelog rather than a manual. The README does not document rollback, does not describe how to upgrade between releases, and does not explain what happens if the daily job fails halfway through. If your team cannot read Chinese, the code is the documentation.

The second is upstream coupling. The changelog records a concrete break: akshare renamed stock_sina_lhb_ggtj to stock_lhb_ggtj_sina, and the project had to change its call. Any akshare rename can break the jobs directory the same way, and the pinned version in the README (1.15.59) is the only known-good combination it states. The daily cache exists precisely because the upstream interface can block aggressive clients, which tells you the fetch layer is operating on someone else's terms.

The third is the nature of the output tables. guess_indicators_lite_buy_daily and guess_indicators_lite_sell_daily are condition results, and the README's own disclaimer says investment losses are not a bug. Treat those tables as columns of computed indicator values and thresholds, not as advice. The changelog entry for 2025-02-28 also mentions a schema fix and a switch of stored values to double because decimal conversion caused problems, which is a reminder that the schema has moved and old data may not line up cleanly with a fresh checkout.

What to compare it against: akshare plus pandas on its own

The honest alternative is not another stock website. It is using akshare directly with pandas and stockstats in a script or notebook you control. akshare is the same data source this project calls, and stockstats computes a similar family of indicators, so the difference is everything around them: pythonstock/stock adds MariaDB persistence, a cron schedule, a Tornado API, a Vue frontend, Bokeh charts and a template-driven display layer, all packaged as a docker-compose stack.

That packaging is the trade. A notebook gives you a two-line install and no server to run; you also get no scheduled history, no query API and no browser UI, and you rebuild the same plumbing each time you want to look at a different indicator. pythonstock/stock gives you the plumbing already assembled, at the cost of a Docker host, a MariaDB instance, roughly 500 MB of local disk according to the README (about 200 MB compressed on Docker Hub), and a codebase whose comments and docs are Chinese. If you only need to compute MACD for a handful of tickers once, the notebook wins. If you want a running system that accumulates daily indicator rows and serves them to a browser, the assembled stack is the reason to pick this project.

Maintenance, upgrade cost and the Apache-2.0 licence

The last push to the repository was on 2026-05-07, and the most recent tagged release is v3.0 from 2025-03-01. Before that, the gap was wider: v2.0 arrived in 2021-10-11 and v1.0 in 2020-07-14. The README itself says updates are irregular (每月不定期更新). Plan for a project that moves in bursts, with long stretches where the pinned library versions are the only guarantee you have.

Upgrade cost concentrates in three places. The database schema has changed across releases, and the 2025-02-28 changelog notes a field change plus a switch to double for sortable values, so migrating existing data is a manual exercise. The Python dependency set is pinned in the README, and the changelog for release 16 states that Python 3.8 or above is needed for newer akshare features. The frontend changed deployment model in V3.0, moving to a compiled nginx build with the HTML mapped to ./data/html, so anyone upgrading from the Tornado-served frontend has a build step to add.

The repository ships an Apache-2.0 licence and a LICENSE file at the top level. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also carries notice and attribution obligations, and the project bundles third-party libraries under their own licences. Read the LICENSE file and the dependency licences yourself; this is a description of what is in the repository, not legal advice.

Editorial conclusion

Adopt pythonstock/stock if you want a working reference for wiring akshare data collection, pandas indicator calculation and a Vue plus Tornado web layer into one docker-compose stack, and you are comfortable reading Chinese documentation. Do not adopt it if you need an English-language codebase, a supported production trading tool, or anything with a release cadence you can plan around: the last push was on 2026-05-07 and the previous tagged release before v3.0 was v2.0 in 2021. Before committing, verify that akshare 1.15.59 still returns the endpoints the jobs call, and check the LICENSE file for the Apache-2.0 terms yourself.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. pythonstock/stock on GitHub
4. README
5. Releases